docs/setuptools.rst - platform/external/python/setuptools - Git at Google

 ==================================================
 Building and Distributing Packages with Setuptools
 ==================================================

 ``Setuptools`` is a collection of enhancements to the Python ``distutils``
 that allow developers to more easily build and
 distribute Python packages, especially ones that have dependencies on other
 packages.

 Packages built and distributed using ``setuptools`` look to the user like
 ordinary Python packages based on the ``distutils``.

 Feature Highlights:

 * Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
   a single-file importable distribution format

 * Enhanced support for accessing data files hosted in zipped packages.

 * Automatically include all packages in your source tree, without listing them
   individually in setup.py

 * Automatically include all relevant files in your source distributions,
   without needing to create a |MANIFEST.in|_ file, and without having to force
   regeneration of the ``MANIFEST`` file when your source tree changes
   [#manifest]_.

 * Automatically generate wrapper scripts or Windows (console and GUI) .exe
   files for any number of "main" functions in your project.  (Note: this is not
   a py2exe replacement; the .exe files rely on the local Python installation.)

 * Transparent Cython support, so that your setup.py can list ``.pyx`` files and
   still work even when the end-user doesn't have Cython installed (as long as
   you include the Cython-generated C in your source distribution)

 * Command aliases - create project-specific, per-user, or site-wide shortcut
   names for commonly used commands and options

 * Deploy your project in "development mode", such that it's available on
   ``sys.path``, yet can still be edited directly from its source checkout.

 * Easily extend the distutils with new commands or ``setup()`` arguments, and
   distribute/reuse your extensions for multiple projects, without copying code.

 * Create extensible applications and frameworks that automatically discover
   extensions, using simple "entry points" declared in a project's setup script.

 * Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards
   compatible to the existing ``find_packages()`` for Python >= 3.3.

 -----------------
 Developer's Guide
 -----------------

 The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`.


 TRANSITIONAL NOTE
 ~~~~~~~~~~~~~~~~~

 Setuptools automatically calls ``declare_namespace()`` for you at runtime,
 but future versions may *not*.  This is because the automatic declaration
 feature has some negative side effects, such as needing to import all namespace
 packages during the initialization of the ``pkg_resources`` runtime, and also
 the need for ``pkg_resources`` to be explicitly imported before any namespace
 packages work at all.  In some future releases, you'll be responsible
 for including your own declaration lines, and the automatic declaration feature
 will be dropped to get rid of the negative side effects.

 During the remainder of the current development cycle, therefore, setuptools
 will warn you about missing ``declare_namespace()`` calls in your
 ``__init__.py`` files, and you should correct these as soon as possible
 before the compatibility support is removed.
 Namespace packages without declaration lines will not work
 correctly once a user has upgraded to a later version, so it's important that
 you make this change now in order to avoid having your code break in the field.
 Our apologies for the inconvenience, and thank you for your patience.


 setup.cfg-only projects
 =======================

 .. versionadded:: 40.9.0

 If ``setup.py`` is missing from the project directory when a :pep:`517`
 build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing
 only a ``setuptools.setup()`` call.

 .. note::

     :pep:`517` doesn't support editable installs so this is currently
     incompatible with ``pip install -e .``.

 This means that you can have a Python project with all build configuration
 specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely
 on** your project always being built by a :pep:`517`/:pep:`518` compatible
 frontend.

 To use this feature:

 * Specify build requirements and :pep:`517` build backend in
   ``pyproject.toml``.
   For example:

   .. code-block:: toml

       [build-system]
       requires = [
         "setuptools >= 40.9.0",
         "wheel",
       ]
       build-backend = "setuptools.build_meta"

 * Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``.

   .. warning::

       As :pep:`517` is new, support is not universal, and frontends that
       do support it may still have bugs. For compatibility, you may want to
       put a ``setup.py`` file containing only a ``setuptools.setup()``
       invocation.


 Configuration API
 =================

 Some automation tools may wish to access data from a configuration file.

 ``Setuptools`` exposes a ``read_configuration()`` function for
 parsing ``metadata`` and ``options`` sections into a dictionary.


 .. code-block:: python

     from setuptools.config import read_configuration

     conf_dict = read_configuration("/home/user/dev/package/setup.cfg")


 By default, ``read_configuration()`` will read only the file provided
 in the first argument. To include values from other configuration files
 which could be in various places, set the ``find_others`` keyword argument
 to ``True``.

 If you have only a configuration file but not the whole package, you can still
 try to get data out of it with the help of the ``ignore_option_errors`` keyword
 argument. When it is set to ``True``, all options with errors possibly produced
 by directives, such as ``attr:`` and others, will be silently ignored.
 As a consequence, the resulting dictionary will include no such options.


 Forum and Bug Tracker
 =====================

 Please use `GitHub Discussions`_ for questions and discussion about
 setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
 confirmed via the forum are actual bugs, and which you have reduced to a minimal
 set of steps to reproduce.

 .. _GitHub Discussions: https://github.com/pypa/setuptools/discussions
 .. _setuptools bug tracker: https://github.com/pypa/setuptools/


 ----


 .. [#manifest] The default behaviour for ``setuptools`` will work well for pure
    Python packages, or packages with simple C extensions (that don't require
    any special C header). See :ref:`Controlling files in the distribution` and
    :doc:`userguide/datafiles` for more information about complex scenarios, if
    you want to include other types of files.


 .. |MANIFEST.in| replace:: ``MANIFEST.in``
 .. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
	==================================================
	Building and Distributing Packages with Setuptools
	==================================================

	``Setuptools`` is a collection of enhancements to the Python ``distutils``
	that allow developers to more easily build and
	distribute Python packages, especially ones that have dependencies on other
	packages.

	Packages built and distributed using ``setuptools`` look to the user like
	ordinary Python packages based on the ``distutils``.

	Feature Highlights:

	* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
	a single-file importable distribution format

	* Enhanced support for accessing data files hosted in zipped packages.

	* Automatically include all packages in your source tree, without listing them
	individually in setup.py

	* Automatically include all relevant files in your source distributions,
	without needing to create a \|MANIFEST.in\|_ file, and without having to force
	regeneration of the ``MANIFEST`` file when your source tree changes
	[#manifest]_.

	* Automatically generate wrapper scripts or Windows (console and GUI) .exe
	files for any number of "main" functions in your project. (Note: this is not
	a py2exe replacement; the .exe files rely on the local Python installation.)

	* Transparent Cython support, so that your setup.py can list ``.pyx`` files and
	still work even when the end-user doesn't have Cython installed (as long as
	you include the Cython-generated C in your source distribution)

	* Command aliases - create project-specific, per-user, or site-wide shortcut
	names for commonly used commands and options

	* Deploy your project in "development mode", such that it's available on
	``sys.path``, yet can still be edited directly from its source checkout.

	* Easily extend the distutils with new commands or ``setup()`` arguments, and
	distribute/reuse your extensions for multiple projects, without copying code.

	* Create extensible applications and frameworks that automatically discover
	extensions, using simple "entry points" declared in a project's setup script.

	* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards
	compatible to the existing ``find_packages()`` for Python >= 3.3.

	-----------------
	Developer's Guide
	-----------------

	The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`.































	TRANSITIONAL NOTE
	~~~~~~~~~~~~~~~~~

	Setuptools automatically calls ``declare_namespace()`` for you at runtime,
	but future versions may not. This is because the automatic declaration
	feature has some negative side effects, such as needing to import all namespace
	packages during the initialization of the ``pkg_resources`` runtime, and also
	the need for ``pkg_resources`` to be explicitly imported before any namespace
	packages work at all. In some future releases, you'll be responsible
	for including your own declaration lines, and the automatic declaration feature
	will be dropped to get rid of the negative side effects.

	During the remainder of the current development cycle, therefore, setuptools
	will warn you about missing ``declare_namespace()`` calls in your
	``__init__.py`` files, and you should correct these as soon as possible
	before the compatibility support is removed.
	Namespace packages without declaration lines will not work
	correctly once a user has upgraded to a later version, so it's important that
	you make this change now in order to avoid having your code break in the field.
	Our apologies for the inconvenience, and thank you for your patience.

















	setup.cfg-only projects
	=======================

	.. versionadded:: 40.9.0

	If ``setup.py`` is missing from the project directory when a :pep:`517`
	build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing
	only a ``setuptools.setup()`` call.

	.. note::

	:pep:`517` doesn't support editable installs so this is currently
	incompatible with ``pip install -e .``.

	This means that you can have a Python project with all build configuration
	specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely
	on** your project always being built by a :pep:`517`/:pep:`518` compatible
	frontend.

	To use this feature:

	* Specify build requirements and :pep:`517` build backend in
	``pyproject.toml``.
	For example:

	.. code-block:: toml

	[build-system]
	requires = [
	"setuptools >= 40.9.0",
	"wheel",
	]
	build-backend = "setuptools.build_meta"

	* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``.

	.. warning::

	As :pep:`517` is new, support is not universal, and frontends that
	do support it may still have bugs. For compatibility, you may want to
	put a ``setup.py`` file containing only a ``setuptools.setup()``
	invocation.


	Configuration API
	=================

	Some automation tools may wish to access data from a configuration file.

	``Setuptools`` exposes a ``read_configuration()`` function for
	parsing ``metadata`` and ``options`` sections into a dictionary.


	.. code-block:: python

	from setuptools.config import read_configuration

	conf_dict = read_configuration("/home/user/dev/package/setup.cfg")


	By default, ``read_configuration()`` will read only the file provided
	in the first argument. To include values from other configuration files
	which could be in various places, set the ``find_others`` keyword argument
	to ``True``.

	If you have only a configuration file but not the whole package, you can still
	try to get data out of it with the help of the ``ignore_option_errors`` keyword
	argument. When it is set to ``True``, all options with errors possibly produced
	by directives, such as ``attr:`` and others, will be silently ignored.
	As a consequence, the resulting dictionary will include no such options.











	Forum and Bug Tracker
	=====================

	Please use `GitHub Discussions`_ for questions and discussion about
	setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
	confirmed via the forum are actual bugs, and which you have reduced to a minimal
	set of steps to reproduce.

	.. _GitHub Discussions: https://github.com/pypa/setuptools/discussions
	.. _setuptools bug tracker: https://github.com/pypa/setuptools/


	----


	.. [#manifest] The default behaviour for ``setuptools`` will work well for pure
	Python packages, or packages with simple C extensions (that don't require
	any special C header). See :ref:`Controlling files in the distribution` and
	:doc:`userguide/datafiles` for more information about complex scenarios, if
	you want to include other types of files.


	.. \|MANIFEST.in\| replace:: ``MANIFEST.in``
	.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/