2.7 Additional meta-data

Python 2.2

previous page next page

2.7 Additional meta-data

The setup script may include additional meta-data beyond the name and version. This information includes:

Meta-Data	Description	Value	Notes
`name`	name of the package	short string	(1)
`version`	version of this release	short string	(1)(2)
`author`	package author's name	short string	(3)
`author_email`	email address of the package author	email address	(3)
`maintainer`	package maintainer's name	short string	(3)
`maintainer_email`	email address of the package maintainer	email address	(3)
`url`	home page for the package	URL	(1)
`description`	short, summary description of the package	short string
`long_description`	longer description of the package	long string
`download_url`	location where the package may be downloaded	URL	(4)
`classifiers`	a list of classifiers	list of strings	(4)

Notes:

(1): These fields are required.
(2): It is recommended that versions take the form major.minor[.patch[.sub]].
(3): Either the author or the maintainer must be identified.
(4): These fields should not be used if your package is to be compatible with Python versions prior to 2.2.3 or 2.3. The list is available from the PyPI website.
'short string': A single line of text, not more than 200 characters.
'long string': Multiple lines of plain text in reStructuredText format (see http://docutils.sf.net/).
'list of strings': See below.

None of the string values may be Unicode.

Encoding the version information is an art in itself. Python packages generally adhere to the version format major.minor[.patch][sub]. The major number is 0 for initial, experimental releases of software. It is incremented for releases that represent major milestones in a package. The minor number is incremented when important new features are added to the package. The patch number increments when bug-fix releases are made. Additional trailing version information is sometimes used to indicate sub-releases. These are "a1,a2,...,aN" (for alpha releases, where functionality and API may change), "b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN" (for final pre-release release testing). Some examples:

0.1.0: the first, experimental release of a package
1.0.1a2: the second alpha release of the first patch version of 1.0

classifiers are specified in a python list:

setup(...
      classifiers=[
          'Development Status :: 4 - Beta',
          'Environment :: Console',
          'Environment :: Web Environment',
          'Intended Audience :: End Users/Desktop',
          'Intended Audience :: Developers',
          'Intended Audience :: System Administrators',
          'License :: OSI Approved :: Python Software Foundation License',
          'Operating System :: MacOS :: MacOS X',
          'Operating System :: Microsoft :: Windows',
          'Operating System :: POSIX',
          'Programming Language :: Python',
          'Topic :: Communications :: Email',
          'Topic :: Office/Business',
          'Topic :: Software Development :: Bug Tracking',
          ],
      )

If you wish to include classifiers in your setup.py file and also wish to remain backwards-compatible with Python releases prior to 2.2.3, then you can include the following code fragment in your setup.py before the setup() call.

# patch distutils if it can't cope with the "classifiers" or
# "download_url" keywords
from sys import version
if version < '2.2.3':
    from distutils.dist import DistributionMetadata
    DistributionMetadata.classifiers = None
    DistributionMetadata.download_url = None

See About this document... for information on suggesting changes.

previous page start next page