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.py and 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',
    author_email='sam@borntyping.co.uk',
    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:

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).

[bdist_wheel]
universal=1

PyPi

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

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](sam@borntyping.co.uk).

You will need to create a MANIFEST.in file so that the README is included in the package:

include README.md

README files for older Python projects using reStructuredText can use the rst-lint tool for checking the validity of a README file.

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>`_