1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
.. _pyproject.toml config:
-----------------------------------------------------
Configuring setuptools using ``pyproject.toml`` files
-----------------------------------------------------
.. note:: New in 61.0.0 (**experimental**)
.. warning::
Support for declaring :doc:`project metadata
<PyPUG:specifications/declaring-project-metadata>` or configuring
``setuptools`` via ``pyproject.toml`` files is still experimental and might
change (or be removed) in future releases.
.. important::
For the time being, ``pip`` still might require a ``setup.py`` file
to support :doc:`editable installs <pip:cli/pip_install>`.
A simple script will suffice, for example:
.. code-block:: python
from setuptools import setup
setup()
Starting with :pep:`621`, the Python community selected ``pyproject.toml`` as
a standard way of specifying *project metadata*.
``Setuptools`` has adopted this standard and will use the information contained
in this file as an input in the build process.
The example below illustrates how to write a ``pyproject.toml`` file that can
be used with ``setuptools``. It contains two TOML tables (identified by the
``[table-header]`` syntax): ``build-system`` and ``project``.
The ``build-system`` table is used to tell the build frontend (e.g.
:pypi:`build` or :pypi:`pip`) to use ``setuptools`` and any other plugins (e.g.
``setuptools-scm``) to build the package.
The ``project`` table contains metadata fields as described by
:doc:`PyPUG:specifications/declaring-project-metadata` guide.
.. _example-pyproject-config:
.. code-block:: toml
[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"
[project]
name = "my_package"
description = "My package description"
readme = "README.rst"
keywords = ["one", "two"]
license = {text = "BSD 3-Clause License"}
classifiers = [
"Framework :: Django",
"Programming Language :: Python :: 3",
]
dependencies = [
"requests",
'importlib-metadata; python_version<"3.8"',
]
dynamic = ["version"]
[project.optional-dependencies]
pdf = ["ReportLab>=1.2", "RXP"]
rest = ["docutils>=0.3", "pack ==1.1, ==1.3"]
[project.scripts]
my-script = "my_package.module:function"
.. _setuptools-table:
Setuptools-specific configuration
=================================
While the standard ``project`` table in the ``pyproject.toml`` file covers most
of the metadata used during the packaging process, there are still some
``setuptools``-specific configurations that can be set by users that require
customization.
These configurations are completely optional and probably can be skipped when
creating simple packages.
They are equivalent to the :doc:`/references/keywords` used by the ``setup.py``
file, and can be set via the ``tool.setuptools`` table:
========================= =========================== =========================
Key Value Type (TOML) Notes
========================= =========================== =========================
``platforms`` array
``zip-safe`` boolean If not specified, ``setuptools`` will try to guess
a reasonable default for the package
``eager-resources`` array
``py-modules`` array See tip below
``packages`` array or ``find`` directive See tip below
``package-dir`` table/inline-table Used when explicitly listing ``packages``
``namespace-packages`` array Not necessary if you use :pep:`420`
``package-data`` table/inline-table See :doc:`/userguide/datafiles`
``include-package-data`` boolean ``True`` by default
``exclude-package-data`` table/inline-table
``license-files`` array of glob patterns **Provisional** - likely to change with :pep:`639`
(by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``)
``data-files`` table/inline-table **Deprecated** - check :doc:`/userguide/datafiles`
``script-files`` array **Deprecated** - equivalent to the ``script`` keyword in ``setup.py``
(should be avoided in favour of ``project.scripts``)
``provides`` array **Ignored by pip**
``obsoletes`` array **Ignored by pip**
========================= =========================== =========================
.. note::
The `TOML value types`_ ``array`` and ``table/inline-table`` are roughly
equivalent to the Python's :obj:`dict` and :obj:`list` data types.
Please note that some of these configurations are deprecated or at least
discouraged, but they are made available to ensure portability.
New packages should avoid relying on deprecated/discouraged fields, and
existing packages should consider alternatives.
.. tip::
When both ``py-modules`` and ``packages`` are left unspecified,
``setuptools`` will attempt to perform :ref:`auto-discovery`, which should
cover most popular project directory organization techniques, such as the
:ref:`src-layout` and the :ref:`flat-layout`.
However if your project does not follow these conventional layouts
(e.g. you want to use a ``flat-layout`` but at the same time have custom
directories at the root of your project), you might need to use the ``find``
directive [#directives]_ as shown below:
.. code-block:: toml
[tool.setuptools.packages.find]
where = ["src"] # list of folders that contain the packages (["."] by default)
include = ["my_package*"] # package names should match these glob patterns (["*"] by default)
exclude = ["my_package.tests*"] # exclude packages matching these glob patterns (empty by default)
namespaces = false # to disable scanning PEP 420 namespaces (true by default)
Note that the glob patterns in the example above need to be matched
by the **entire** package name. This means that if you specify ``exclude = ["tests"]``,
modules like ``tests.my_package.test1`` will still be included in the distribution
(to remove them, add a wildcard to the end of the pattern: ``"tests*"``).
Alternatively, you can explicitly list the packages in modules:
.. code-block:: toml
[tool.setuptools]
packages = ["my_package"]
.. _dynamic-pyproject-config:
Dynamic Metadata
================
Note that in the first example of this page we use ``dynamic`` to identify
which metadata fields are dynamically computed during the build by either
``setuptools`` itself or the plugins installed via ``build-system.requires``
(e.g. ``setuptools-scm`` is capable of deriving the current project version
directly from the ``git`` :wiki:`version control` system).
Currently the following fields can be listed as dynamic: ``version``,
``classifiers``, ``description``, ``entry-points``, ``scripts``,
``gui-scripts`` and ``readme``.
When these fields are expected to be provided by ``setuptools`` a
corresponding entry is required in the ``tool.setuptools.dynamic`` table
[#entry-points]_. For example:
.. code-block:: toml
# ...
[project]
name = "my_package"
dynamic = ["version", "readme"]
# ...
[tool.setuptools.dynamic]
version = {attr = "my_package.VERSION"}
readme = {file = ["README.rst", "USAGE.rst"]}
In the ``dynamic`` table, the ``attr`` directive [#directives]_ will read an
attribute from the given module [#attr]_, while ``file`` will read the contents
of all given files and concatenate them in a single string.
================= =================== =========================
Key Directive Notes
================= =================== =========================
``version`` ``attr``, ``file``
``readme`` ``file``
``description`` ``file`` One-line text
``classifiers`` ``file`` Multi-line text with one classifier per line
``entry-points`` ``file`` INI format following :doc:`PyPUG:specifications/entry-points`
(``console_scripts`` and ``gui_scripts`` can be included)
================= =================== =========================
----
.. rubric:: Notes
.. [#entry-points] Dynamic ``scripts`` and ``gui-scripts`` are a special case.
When resolving these metadata keys, ``setuptools`` will look for
``tool.setuptool.dynamic.entry-points``, and use the values of the
``console_scripts`` and ``gui_scripts`` :doc:`entry-point groups
<PyPUG:specifications/entry-points>`.
.. [#directives] In the context of this document, *directives* are special TOML
values that are interpreted differently by ``setuptools`` (usually triggering an
associated function). Most of the times they correspond to a special TOML table
(or inline-table) with a single top-level key.
For example, you can have the ``{find = {where = ["src"], exclude=["tests*"]}}``
directive for ``tool.setuptools.packages``, or ``{attr = "mymodule.attr"}``
directive for ``tool.setuptools.dynamic.version``.
.. [#attr] ``attr`` is meant to be used when the module attribute is statically
specified (e.g. as a string, list or tuple). As a rule of thumb, the
attribute should be able to be parsed with :func:`ast.literal_eval`, and
should not be modified or re-assigned.
.. _TOML value types: https://toml.io/en/v1.0.0
|
