Package: otquickmodule
Easy Python Packaging(7 steps to publish on PyPI)This document aims at giving a quick tutorial for structuring, packaging, and publishing your Python package onhttps://pypi.org/.To illustrate this tutorial, let's work on ditribution of a full Python package calledotquickmoduleexample, based on the following tutorialhttps://github.com/judy2k/publishing_python_packages_talk.Our illustrative package,otquickmodule, includes two classes:KernelHerdingQuadratureWeighting0. Create a new environmentBefore strating, creating a new environment for this occasion is highly recomanded to properly manage dependencies (we decided to name oursotqm_env). For more information, check-out the conda environnments documentationhttps://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html.~$condacreate-notqm_envpython=3.9~$condaactivateotqm_envDo not forget to activate this environment for all the following steps.1. Write__init__.pyfileThis file will allow the auto-completion your methods when using the package. Note that the version defined here will be the package version (including on pypi)."""otquickmodule module"""from.KernelHerdingimportKernelHerdingfrom.QuadratureWeightingimportQuadratureWeighting__all__=["KernelHerding","QuadratureWeighting",]__version__="0.0.1"2. Create the package structureBefore creating the package structure, we recommand to follow a few good practices in Python:Avoid unecessary dependancies to simplify package maintenancyFollow the PEP 8 coding standards and use the packageblackto format your code according to PEP 8.Write explicit docstrings on each method using the numpydoc syntax. This formalism will allow you to easily create a beautiful documentation in the future (e.g.,https://efekhari27.github.io/otkerneldesign/master/)Here is the recommended Python package structure, do not foget to place the__init__.pyfile in the by the two classes.PACKAGE STRUCTURE (step 2)
==========================
├── otquickmodule
|    ├── example
|    ├── test
|    ├── otquickmodule
|    |   ├── __init__.py
|    |   ├── QuadratureWeighting.py
|    |   └── KernelHerding.py3. Add license, readme and gitignore filesTheREADME.mdfile should describe the package and will appear on your github repository and your pypi page.To help you choosing a license:https://choosealicense.com/. In our case, we chose a GPL license in the form of the fileLICENSE.To create a .gitignore file (to make sure git doesn't follow auxillary files): copy ours or check outhttps://www.toptal.com/developers/gitignore/PACKAGE STRUCTURE (step 3)
==========================
├── otquickmodule
|    ├── example
|    ├── test
|    ├── otquickmodule
|    |   ├── __init__.py
|    |   ├── QuadratureWeighting.py
|    |   └── KernelHerding.py
|    ├── LICENSE
|    ├── README.md
|    └── .gitignore4. Write asetup.pyfileThesetup.pyis the most important file for installing your package. Note that thenamedefined here will be the name published on pypi.# coding: utf8"""Setup script for a Python package"""importosimportrefromsetuptoolsimportsetup# Get the version from __init__.pypath=os.path.join(os.path.dirname(__file__),'otquickmodule','__init__.py')withopen(path)asf:version_file=f.read()version=re.search(r"^\s*__version__\s*=\s*['\"]([^'\"]+)['\"]",version_file,re.M)ifversion:version=version.group(1)else:raiseRuntimeError("Unable to find version string.")# Long descriptionwithopen("README.md","r")asfh:long_description=fh.read()setup(name="otquickmodule",version=version,author="Elias Fekhari",author_email="elias.fekhari@edf.fr",description="This repository is a turorial for easy Python packaging",license='GPLv3+',keywords=['OpenTURNS','KernelHerding'],url="https://github.com/efekhari27/otquickmodule",packages=['otquickmodule','test'],long_description=long_description,long_description_content_type="text/markdown",classifiers=["Programming Language :: Python :: 3","License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)","Intended Audience :: Science/Research","Topic :: Software Development","Topic :: Scientific/Engineering",],install_requires=["numpy","scipy","openturns>=1.17"],)At this step, you should be able to run the following commands without error. It will first create abuildrepertory with the sources of your package. Then, you can try to install the package locally (the option-eimposes a local install).~/otquickmodule$pytonsetup.pybdist_wheel
~/otquickmodule$pipinstall-e.You can now import the module from anywhere with the Python interpreter of theotqm_envconda environment:~$condaactivateotqm_env~$python>>>importotquickmoduleasotqm>>>5. Write tests and examplesEach class should have a corresponding test file. Tests can either be writen using theunittestorpytestpackage.pytestis very popular and present various practical features but requires to be added to the package requirements. For our needs, we chose to use the native Python moduleunnitest.Additionally, users appreciate to get started with a simple usage example which can be a ipython notebook file.PACKAGE STRUCTURE (step 5)
==========================
├── otquickmodule
|    ├── build
|    |   ├── ...
|    |   └── ...
|    ├── example
|    |   └── kernel_herding_example.ipynb
|    ├── test
|    |   ├── TestQuadratureWeighting.py
|    |   └── TestKernelHerding.py
|    ├── otquickmodule
|    |   ├── __init__.py
|    |   ├── TestQuadratureWeighting.py
|    |   └── KernelHerding.py
|    ├── LICENSE
|    ├── README.md
|    ├── setup.py
|    └── .gitignoreAt this step you can repeat the build and install commands from the previous step.6. Build, distribute and publishCreate the source distribution of the package: (creates a tar gz archive and the hostingdistrepertory)~/otquickmodule$pytonsetup.pybdist_wheelsdistCheck if it worked: (you should see the content of the archive)~/otquickmodule$tartzfdist/otquickmodule-0.0.1.tar.gzCreate a PyPI account online and remember your username and password.Install the packagetwine:~/otquickmodule$condainstalltwinePublish the package on PyPI:~/otquickmodule$twineuploaddist/*
Uploadingdistributionstohttps://upload.pypi.org/legacy/
Enteryourusername:YOUR_USER_NAME
Enteryourpassword:YOUR_PASSWORD
Uploadingotquickmodule-0.0.1.tar.gz100%|██████████████████████████████████████████████████████████████|3.49k/3.49k[00:01<00:00,2.17kB/s]Viewat:
https://pypi.org/project/otquickmodule/0.0.1/Your package is available online!7. Try your packageCreate or switch to a different conda environment and install your package from pypi:~$condaactivateother_env
~$pipinstallotquickmodule