1.. _declarative config:
2
3------------------------------------------------
4Configuring setuptools using ``setup.cfg`` files
5------------------------------------------------
6
7.. note:: New in 30.3.0 (8 Dec 2016).
8
9.. important::
10    If compatibility with legacy builds (i.e. those not using the :pep:`517`
11    build API) is desired, a ``setup.py`` file containing a ``setup()`` function
12    call is still required even if your configuration resides in ``setup.cfg``.
13
14``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
15to define a package’s metadata and other options that are normally supplied
16to the ``setup()`` function (declarative config).
17
18This approach not only allows automation scenarios but also reduces
19boilerplate code in some cases.
20
21.. _example-setup-config:
22
23.. code-block:: ini
24
25    [metadata]
26    name = my_package
27    version = attr: my_package.VERSION
28    description = My package description
29    long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
30    keywords = one, two
31    license = BSD 3-Clause License
32    classifiers =
33        Framework :: Django
34        Programming Language :: Python :: 3
35
36    [options]
37    zip_safe = False
38    include_package_data = True
39    packages = find:
40    install_requires =
41        requests
42        importlib-metadata; python_version<"3.8"
43
44    [options.package_data]
45    * = *.txt, *.rst
46    hello = *.msg
47
48    [options.entry_points]
49    console_scripts =
50        executable-name = my_package.module:function
51
52    [options.extras_require]
53    pdf = ReportLab>=1.2; RXP
54    rest = docutils>=0.3; pack ==1.1, ==1.3
55
56    [options.packages.find]
57    exclude =
58        examples*
59        tools*
60        docs*
61        my_package.tests*
62
63Metadata and options are set in the config sections of the same name.
64
65* Keys are the same as the keyword arguments one provides to the ``setup()``
66  function.
67
68* Complex values can be written comma-separated or placed one per line
69  in *dangling* config values. The following are equivalent:
70
71  .. code-block:: ini
72
73      [metadata]
74      keywords = one, two
75
76      [metadata]
77      keywords =
78          one
79          two
80
81* In some cases, complex values can be provided in dedicated subsections for
82  clarity.
83
84* Some keys allow ``file:``, ``attr:``, ``find:``, and ``find_namespace:`` directives in
85  order to cover common usecases.
86
87* Unknown keys are ignored.
88
89
90Using a ``src/`` layout
91=======================
92
93One commonly used package configuration has all the module source code in a
94subdirectory (often called the ``src/`` layout), like this::
95
96    ├── src
97    │   └── mypackage
98    │       ├── __init__.py
99    │       └── mod1.py
100    ├── setup.py
101    └── setup.cfg
102
103You can set up your ``setup.cfg`` to automatically find all your packages in
104the subdirectory like this:
105
106.. code-block:: ini
107
108    # This example contains just the necessary options for a src-layout, set up
109    # the rest of the file as described above.
110
111    [options]
112    package_dir=
113        =src
114    packages=find:
115
116    [options.packages.find]
117    where=src
118
119Specifying values
120=================
121
122Some values are treated as simple strings, some allow more logic.
123
124Type names used below:
125
126* ``str`` - simple string
127* ``list-comma`` - dangling list or string of comma-separated values
128* ``list-semi`` - dangling list or string of semicolon-separated values
129* ``bool`` - ``True`` is 1, yes, true
130* ``dict`` - list-comma where keys are separated from values by ``=``
131* ``section`` - values are read from a dedicated (sub)section
132
133
134Special directives:
135
136* ``attr:`` - Value is read from a module attribute.  ``attr:`` supports
137  callables and iterables; unsupported types are cast using ``str()``.
138
139  In order to support the common case of a literal value assigned to a variable
140  in a module containing (directly or indirectly) third-party imports,
141  ``attr:`` first tries to read the value from the module by examining the
142  module's AST.  If that fails, ``attr:`` falls back to importing the module.
143
144* ``file:`` - Value is read from a list of files and then concatenated
145
146  .. note::
147      The ``file:`` directive is sandboxed and won't reach anything outside
148      the directory containing ``setup.py``.
149
150
151Metadata
152--------
153
154.. note::
155    The aliases given below are supported for compatibility reasons,
156    but their use is not advised.
157
158==============================  =================  =================  =============== ==========
159Key                             Aliases            Type               Minimum Version Notes
160==============================  =================  =================  =============== ==========
161name                                               str
162version                                            attr:, file:, str  39.2.0          [#meta-1]_
163url                             home-page          str
164download_url                    download-url       str
165project_urls                                       dict               38.3.0
166author                                             str
167author_email                    author-email       str
168maintainer                                         str
169maintainer_email                maintainer-email   str
170classifiers                     classifier         file:, list-comma
171license                                            str
172license_files                   license_file       list-comma         42.0.0
173description                     summary            file:, str
174long_description                long-description   file:, str
175long_description_content_type                      str                38.6.0
176keywords                                           list-comma
177platforms                       platform           list-comma
178provides                                           list-comma
179requires                                           list-comma
180obsoletes                                          list-comma
181==============================  =================  =================  =============== ==========
182
183**Notes**:
184
185.. [#meta-1] The ``version`` file attribute has only been supported since 39.2.0.
186
187   A version loaded using the ``file:`` directive must comply with PEP 440.
188   It is easy to accidentally put something other than a valid version
189   string in such a file, so validation is stricter in this case.
190
191
192Options
193-------
194
195=======================  ===================================  =============== =========
196Key                      Type                                 Minimum Version Notes
197=======================  ===================================  =============== =========
198zip_safe                 bool
199setup_requires           list-semi                            36.7.0
200install_requires         list-semi
201extras_require           section                                              [#opt-2]_
202python_requires          str                                  34.4.0
203entry_points             file:, section                       51.0.0
204scripts                  list-comma
205eager_resources          list-comma
206dependency_links         list-comma
207tests_require            list-semi
208include_package_data     bool
209packages                 find:, find_namespace:, list-comma                   [#opt-3]_
210package_dir              dict
211package_data             section                                              [#opt-1]_
212exclude_package_data     section
213namespace_packages       list-comma
214py_modules               list-comma                            34.4.0
215data_files               section                              40.6.0          [#opt-4]_
216=======================  ===================================  =============== =========
217
218**Notes**:
219
220.. [#opt-1] In the ``package_data`` section, a key named with a single asterisk
221   (``*``) refers to all packages, in lieu of the empty string used in ``setup.py``.
222
223.. [#opt-2] In the ``extras_require`` section, values are parsed as ``list-semi``.
224   This implies that in order to include markers, they **must** be *dangling*:
225
226   .. code-block:: ini
227
228      [options.extras_require]
229      rest = docutils>=0.3; pack ==1.1, ==1.3
230      pdf =
231        ReportLab>=1.2
232        RXP
233        importlib-metadata; python_version < "3.8"
234
235.. [#opt-3] The ``find:`` and ``find_namespace:`` directive can be further configured
236   in a dedicated subsection ``options.packages.find``. This subsection accepts the
237   same keys as the ``setuptools.find_packages`` and the
238   ``setuptools.find_namespace_packages`` function:
239   ``where``, ``include``, and ``exclude``.
240
241   The ``find_namespace:`` directive is supported since Python >=3.3.
242
243.. [#opt-4] ``data_files`` is deprecated and should be avoided.
244   Please check :doc:`/userguide/datafiles` for more information.
245
246
247Compatibility with other tools
248==============================
249
250Historically, several tools explored declarative package configuration
251in parallel. And several of them chose to place the packaging
252configuration within the project's :file:`setup.cfg` file.
253One of the first was ``distutils2``, which development has stopped in
2542013. Other include ``pbr`` which is still under active development or
255``d2to1``, which was a plug-in that backports declarative configuration
256to ``distutils``, but has had no release since Oct. 2015.
257As a way to harmonize packaging tools, ``setuptools``, having held the
258position of *de facto* standard, has gradually integrated those
259features as part of its core features.
260
261Still this has lead to some confusion and feature incompatibilities:
262
263- some tools support features others don't;
264- some have similar features but the declarative syntax differs;
265
266The table below tries to summarize the differences. But, please, refer
267to each tool documentation for up-to-date information.
268
269=========================== ========== ========== ===== ===
270feature                     setuptools distutils2 d2to1 pbr
271=========================== ========== ========== ===== ===
272[metadata] description-file S          Y          Y     Y
273[files]                     S          Y          Y     Y
274entry_points                Y          Y          Y     S
275[backwards_compat]          N          Y          Y     Y
276=========================== ========== ========== ===== ===
277
278Y: supported, N: unsupported, S: syntax differs (see
279:ref:`above example<example-setup-config>`).
280
281Also note that some features were only recently added to ``setuptools``.
282Please refer to the previous sections to find out when.
283