1==================================================
2Building and Distributing Packages with Setuptools
3==================================================
4
5``Setuptools`` is a collection of enhancements to the Python ``distutils``
6that allow developers to more easily build and
7distribute Python packages, especially ones that have dependencies on other
8packages.
9
10Packages built and distributed using ``setuptools`` look to the user like
11ordinary Python packages based on the ``distutils``.
12
13Feature Highlights:
14
15* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
16  a single-file importable distribution format
17
18* Enhanced support for accessing data files hosted in zipped packages.
19
20* Automatically include all packages in your source tree, without listing them
21  individually in setup.py
22
23* Automatically include all relevant files in your source distributions,
24  without needing to create a |MANIFEST.in|_ file, and without having to force
25  regeneration of the ``MANIFEST`` file when your source tree changes
26  [#manifest]_.
27
28* Automatically generate wrapper scripts or Windows (console and GUI) .exe
29  files for any number of "main" functions in your project.  (Note: this is not
30  a py2exe replacement; the .exe files rely on the local Python installation.)
31
32* Transparent Cython support, so that your setup.py can list ``.pyx`` files and
33  still work even when the end-user doesn't have Cython installed (as long as
34  you include the Cython-generated C in your source distribution)
35
36* Command aliases - create project-specific, per-user, or site-wide shortcut
37  names for commonly used commands and options
38
39* Deploy your project in "development mode", such that it's available on
40  ``sys.path``, yet can still be edited directly from its source checkout.
41
42* Easily extend the distutils with new commands or ``setup()`` arguments, and
43  distribute/reuse your extensions for multiple projects, without copying code.
44
45* Create extensible applications and frameworks that automatically discover
46  extensions, using simple "entry points" declared in a project's setup script.
47
48* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards
49  compatible to the existing ``find_packages()`` for Python >= 3.3.
50
51-----------------
52Developer's Guide
53-----------------
54
55The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`.
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87TRANSITIONAL NOTE
88~~~~~~~~~~~~~~~~~
89
90Setuptools automatically calls ``declare_namespace()`` for you at runtime,
91but future versions may *not*.  This is because the automatic declaration
92feature has some negative side effects, such as needing to import all namespace
93packages during the initialization of the ``pkg_resources`` runtime, and also
94the need for ``pkg_resources`` to be explicitly imported before any namespace
95packages work at all.  In some future releases, you'll be responsible
96for including your own declaration lines, and the automatic declaration feature
97will be dropped to get rid of the negative side effects.
98
99During the remainder of the current development cycle, therefore, setuptools
100will warn you about missing ``declare_namespace()`` calls in your
101``__init__.py`` files, and you should correct these as soon as possible
102before the compatibility support is removed.
103Namespace packages without declaration lines will not work
104correctly once a user has upgraded to a later version, so it's important that
105you make this change now in order to avoid having your code break in the field.
106Our apologies for the inconvenience, and thank you for your patience.
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124setup.cfg-only projects
125=======================
126
127.. versionadded:: 40.9.0
128
129If ``setup.py`` is missing from the project directory when a :pep:`517`
130build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing
131only a ``setuptools.setup()`` call.
132
133.. note::
134
135    :pep:`517` doesn't support editable installs so this is currently
136    incompatible with ``pip install -e .``.
137
138This means that you can have a Python project with all build configuration
139specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely
140on** your project always being built by a :pep:`517`/:pep:`518` compatible
141frontend.
142
143To use this feature:
144
145* Specify build requirements and :pep:`517` build backend in
146  ``pyproject.toml``.
147  For example:
148
149  .. code-block:: toml
150
151      [build-system]
152      requires = [
153        "setuptools >= 40.9.0",
154        "wheel",
155      ]
156      build-backend = "setuptools.build_meta"
157
158* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``.
159
160  .. warning::
161
162      As :pep:`517` is new, support is not universal, and frontends that
163      do support it may still have bugs. For compatibility, you may want to
164      put a ``setup.py`` file containing only a ``setuptools.setup()``
165      invocation.
166
167
168Configuration API
169=================
170
171Some automation tools may wish to access data from a configuration file.
172
173``Setuptools`` exposes a ``read_configuration()`` function for
174parsing ``metadata`` and ``options`` sections into a dictionary.
175
176
177.. code-block:: python
178
179    from setuptools.config import read_configuration
180
181    conf_dict = read_configuration("/home/user/dev/package/setup.cfg")
182
183
184By default, ``read_configuration()`` will read only the file provided
185in the first argument. To include values from other configuration files
186which could be in various places, set the ``find_others`` keyword argument
187to ``True``.
188
189If you have only a configuration file but not the whole package, you can still
190try to get data out of it with the help of the ``ignore_option_errors`` keyword
191argument. When it is set to ``True``, all options with errors possibly produced
192by directives, such as ``attr:`` and others, will be silently ignored.
193As a consequence, the resulting dictionary will include no such options.
194
195
196
197
198
199
200
201
202
203
204
205Forum and Bug Tracker
206=====================
207
208Please use `GitHub Discussions`_ for questions and discussion about
209setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
210confirmed via the forum are actual bugs, and which you have reduced to a minimal
211set of steps to reproduce.
212
213.. _GitHub Discussions: https://github.com/pypa/setuptools/discussions
214.. _setuptools bug tracker: https://github.com/pypa/setuptools/
215
216
217----
218
219
220.. [#manifest] The default behaviour for ``setuptools`` will work well for pure
221   Python packages, or packages with simple C extensions (that don't require
222   any special C header). See :ref:`Controlling files in the distribution` and
223   :doc:`userguide/datafiles` for more information about complex scenarios, if
224   you want to include other types of files.
225
226
227.. |MANIFEST.in| replace:: ``MANIFEST.in``
228.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
229