cpython/Doc/library/packaging.dist.rst

109 lines
11 KiB
ReStructuredText
Raw Normal View History

:mod:`packaging.dist` --- The Distribution class
================================================
.. module:: packaging.dist
:synopsis: Core Distribution class.
This module provides the :class:`Distribution` class, which represents the
module distribution being built/packaged/distributed/installed.
.. class:: Distribution(arguments)
A :class:`Distribution` describes how to build, package, distribute and
install a Python project.
The arguments accepted by the constructor are laid out in the following
table. Some of them will end up in a metadata object, the rest will become
data attributes of the :class:`Distribution` instance.
.. TODO improve constructor to take a Metadata object + named params?
(i.e. Distribution(metadata, cmdclass, py_modules, etc)
.. TODO also remove obsolete(?) script_name, etc. parameters? see what
py2exe and other tools need
+--------------------+--------------------------------+-------------------------------------------------------------+
| argument name | value | type |
+====================+================================+=============================================================+
| *name* | The name of the project | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *version* | The version number of the | a string |
| | release; see | |
| | :mod:`packaging.version` | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *summary* | A single line describing the | a string |
| | project | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *description* | Longer description of the | a string |
| | project | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *author* | The name of the project author | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *author_email* | The email address of the | a string |
| | project author | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *maintainer* | The name of the current | a string |
| | maintainer, if different from | |
| | the author | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *maintainer_email* | The email address of the | a string |
| | current maintainer, if | |
| | different from the author | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *home_page* | A URL for the proejct | a string |
| | (homepage) | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *download_url* | A URL to download the project | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *packages* | A list of Python packages that | a list of strings |
| | packaging will manipulate | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *py_modules* | A list of Python modules that | a list of strings |
| | packaging will manipulate | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *scripts* | A list of standalone scripts | a list of strings |
| | to be built and installed | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *ext_modules* | A list of Python extensions to | a list of instances of |
| | be built | :class:`packaging.compiler.extension.Extension` |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPi |
| | distribution | <http://pypi.python.org/pypi?:action=list_classifiers>`_. |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *distclass* | the :class:`Distribution` | a subclass of |
| | class to use | :class:`packaging.dist.Distribution` |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *script_name* | The name of the setup.py | a string |
| | script - defaults to | |
| | ``sys.argv[0]`` | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *script_args* | Arguments to supply to the | a list of strings |
| | setup script | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *options* | default options for the setup | a string |
| | script | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *license* | The license for the | a string |
| | distribution; should be used | |
| | when there is no suitable | |
| | License classifier, or to | |
| | refine a classifier | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *keywords* | Descriptive keywords; used by | a list of strings or a comma-separated string |
| | catalogs such as PyPI | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *platforms* | Platforms compatible with this | a list of strings or a comma-separated string |
| | distribution; should be used | |
| | when there is no suitable | |
| | Platform classifier | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *cmdclass* | A mapping of command names to | a dictionary |
| | :class:`Command` subclasses | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *data_files* | A list of data files to | a list |
| | install | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *package_dir* | A mapping of Python packages | a dictionary |
| | to directory names | |
+--------------------+--------------------------------+-------------------------------------------------------------+