229 lines
6.7 KiB
ReStructuredText
229 lines
6.7 KiB
ReStructuredText
==================================================
|
|
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/
|