Better Package Metadata

The setuptools.setup() call accepts a variety of keyword arguments to specify additional metadata about your package. This can help people find your package and evaluate quickly whether or not it is what they’re looking for.:

from setuptools import setup

setup(name='funniest',
      version='0.1',
      description='The funniest joke in the world',
      long_description='Really, the funniest around.',
      classifiers=[
        'Development Status :: 3 - Alpha',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 2.7',
        'Topic :: Text Processing :: Linguistic',
      ],
      keywords='funniest joke comedy flying circus',
      url='http://github.com/storborg/funniest',
      author='Flying Circus',
      author_email='flyingcircus@example.com',
      license='MIT',
      packages=['funniest'],
      install_requires=[
          'markdown',
      ],
      include_package_data=True,
      zip_safe=False)

For a full list of the possible arguments to classifiers, visit http://pypi.python.org/pypi?%3Aaction=list_classifiers.

A README / Long Description

You’ll probably want a README file in your source distribution, and that file can serve double purpose as the long_description specified to PyPI. Further, if that file is written in reStructuredText, it can be formatted nicely.

For funniest, let’s add two files:

funniest/
    funniest/
        __init__.py
    setup.py
    README.rst
    MANIFEST.in

README.rst contains:

Funniest
--------

To use (with caution), simply do::

    >>> import funniest
    >>> print funniest.joke()

MANIFEST.in contains:

include README.rst

This file is necessary to tell setuptools to include the README.rst file when generating source distributions. Otherwise, only Python files will be included.

Now we can use it in setup.py like:

from setuptools import setup

def readme():
    with open('README.rst') as f:
        return f.read()

setup(name='funniest',
      version='0.1',
      description='The funniest joke in the world',
      long_description=readme(),
      classifiers=[
        'Development Status :: 3 - Alpha',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 2.7',
        'Topic :: Text Processing :: Linguistic',
      ],
      keywords='funniest joke comedy flying circus',
      url='http://github.com/storborg/funniest',
      author='Flying Circus',
      author_email='flyingcircus@example.com',
      license='MIT',
      packages=['funniest'],
      install_requires=[
          'markdown',
      ],
      include_package_data=True,
      zip_safe=False)

When the repo is hosted on GitHub or BitBucket, the README.rst file will also automatically be picked up and used as a ‘homepage’ for the project.