More documentation for setup meta-data
I'm trying to better document the meta-data for the distutils (and hence PyPI). I've added words to the section in the dev doc about meta-data, and would like some feedback before I post the patch to be applied. Sorry, it's in LaTeX form (until someone writes the ReST->python doc converter ;) \subsection{Additional meta-data} \label{meta-data} The setup script may include additional meta-data beyond the name and version. This information includes: \begin{tableiii}{l|l|l|c}{code}% {Meta-Data}{Description}{Value}{Notes} \lineiii{name}{the name of the package}{short string}{(1)} \lineiii{version}{the version of this release}{short string}{(1)(4)} \lineiii{author}{package author's name}{short string}{(2)} \lineiii{author_email}{email address of the package author}{email address}{(2)} \lineiii{maintainer}{package maintainer's name}{short string}{(2)} \lineiii{maintainer_email}{email address of the package maintainer}{email address}{(2)} \lineiii{home_page}{the location of the homepage for the package}{URL}{(1)} \lineiii{description}{a short, summary description of the package}{short string}{} \lineiii{long_description}{a longer description of the package}{long string}{} \lineiii{download_url}{a location where the package may be downloaded}{URL}{(3)} \lineiii{classifiers}{a list of Trove classifiers}{list of strings}{(3)} \end{tableiii} \noindent Notes: \begin{description} \item[(1)] these fields are required \item[(2)] either the author or the maintainer must be nominated \item[(3)] 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. \item[(4)] it is recommended that versions take the form <major>.<minor>.<patch>[.<sub>] \item["short string"] a single line of text, not more than 200 characters \item["long string"] multiple lines of text \item["list of strings"] see below \end{description} \option{version} encoding is an art in itself. Python packages generally adhere to the version format \em{major.minor.patch}. 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: \begin{description} \item[0.1.0] the first, experimental release of a package \item[1.0.1a2] the second alpha release of the first patch version of 1.0 \end{description} \option{classifiers} are specified in a python list: \begin{verbatim} 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', ], ... ) \end{verbatim} If you wish to include classifiers in your \file{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 \file{setup.py} before the \code{setup()} call. \begin{verbatim} # patch distutils if it can't cope with the "classifiers" or # "download_url" keywords if sys.version < '2.2.3': from distutils.dist import DistributionMetadata DistributionMetadata.classifiers = None DistributionMetadata.download_url = None \end{verbatim}
participants (5)
-
A.M. Kuchling
-
holger krekel
-
M.-A. Lemburg
-
Richard Jones
-
Richard Jones