Packaging Python modules¶
The Python Packaging User Guide has excellent guidance on packaging Python projects - in particular, use the information on packaging and distributing projects, and the suggested tools. Python projects that provide a package should include
setup.cfg configuration files:
from setuptools import setup setup( name='<NAME>', version='0.0.0', description='A short description of the package', long_description=open('README.md').read(), author='Sam Clements', firstname.lastname@example.org', url='https://github.com/borntyping/python-<NAME>', license='MIT License', packages=[ '<NAME>' ], classifiers=[ 'Development Status :: 3 - Alpha', 'License :: OSI Approved :: MIT License', 'Programming Language :: Python', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 2.6', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.3', 'Programming Language :: Python :: 3.4' ] )
Notes on specific metadata items:
- Version numbers should follow the semantic versioning specification.
- PyPI provides a list of available package classifiers.
- Python 3 only projects should use
Programming Language :: Python :: 3 :: Only.
- Python projects should use the MIT License (see Projects).
Packages that run on Python 2 and 3 should ensure they have a
setup.cfg file that configures
bdist_wheel to mark the wheel as ‘universal’ (otherwise, the wheel will declare that it is only for the version of Python it was built on).
A new python package can be registered to PyPI with:
python setup.py register
Python packages can generally be released with:
python setup.py sdist bdist_wheel upload
Tox can be used to automate package releases, by including a test environment that runs the release commands:
[testenv:release] commands=python setup.py sdist bdist_wheel upload deps=wheel
In the unusual case that a package supplies metadata depending on which Python version it is running on (see complex_setup_example), you’ll need to run bdist_wheel for each of those Python versions. While source distributions run setup.py when installing a package, built distributions run setup.py when creating the package).
[testenv:release] commands= python2 setup.py sdist upload python2 setup.py bdist_wheel upload python3 setup.py bdist_wheel upload deps=wheel
README files for Python projects should use Markdown (see this commit). The README should include links to the GitHub repository, any packages on PyPi,builds on Travis-CI and documentation on Read The Docs (which is especially useful when the README is shown in multiple places).
# EXAMPLE [!(https://img.shields.io/pypi/v/EXAMPLE.svg)](https://warehouse.python.org/project/EXAMPLE/) [!(https://img.shields.io/pypi/l/EXAMPLE.svg)](https://warehouse.python.org/project/EXAMPLE/) [!(https://img.shields.io/travis/borntyping/EXAMPLE/master.svg)](https://travis-ci.org/borntyping/EXAMPLE) [!(https://img.shields.io/github/issues/borntyping/EXAMPLE.svg)](https://github.com/borntyping/EXAMPLE/issues) A short description of the project. * [Source on GitHub](https://github.com/borntyping/EXAMPLE) * [Packages on PyPI](https://warehouse.python.org/project/EXAMPLE/) * [Documentation on Read the Docs](https://EXAMPLE.readthedocs.org/en/latest/) * [Builds on Travis CI](https://travis-ci.org/borntyping/EXAMPLE) Usage ----- Run `EXAMPLE --help` for a list of availible subcommands. Installation ------------ ```bash pip install EXAMPLE ``` Licence ------- **EXAMPLE** is licenced under the [MIT Licence](http://opensource.org/licenses/MIT). Authors ------- Written by [Sam Clements](email@example.com).
You will need to create a
MANIFEST.in file so that the README is included in the package:
example ======= .. image:: https://img.shields.io/pypi/v/example.svg?style=flat-square :target: https://warehouse.python.org/project/example/ :alt: example on PyPI .. image:: https://img.shields.io/pypi/l/example.svg?style=flat-square :target: https://warehouse.python.org/project/example/ :alt: example on PyPI .. image:: https://readthedocs.org/projects/example/badge/?version=latest&style=flat-square :target: https://example.readthedocs.org/en/latest/ :alt: Documentation for example on Read The Docs .. image:: https://img.shields.io/travis/borntyping/example/master.svg?style=flat-square :target: https://travis-ci.org/borntyping/example :alt: Travis-CI build status for example .. image:: https://img.shields.io/github/issues/borntyping/example.svg?style=flat-square :target: https://github.com/borntyping/example/issues :alt: GitHub issues for example | Short description of the project. * `Source on GitHub <https://github.com/borntyping/example>`_ * `Documentation on Read the Docs <https://example.readthedocs.org/en/latest/>`_ * `Packages on PyPI <https://warehouse.python.org/project/example/>`_ * `Builds on Travis CI <https://travis-ci.org/borntyping/example>`_