Configuring setuptools using pyproject.toml
files¶
Note
New in 61.0.0
Important
If compatibility with legacy builds or versions of tools that don’t support
certain packaging standards (e.g. PEP 517 or PEP 660), a simple setup.py
script can be added to your project [1]
(while keeping the configuration in pyproject.toml
):
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.
build or 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 the
Writing your pyproject.toml guide.
[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"
[project]
name = "my_package"
authors = [
{name = "Josiah Carberry", email = "josiah_carberry@brown.edu"},
]
description = "My package description"
readme = "README.rst"
requires-python = ">=3.8"
keywords = ["one", "two"]
license = {text = "BSD-3-Clause"}
classifiers = [
"Framework :: Django",
"Programming Language :: Python :: 3",
]
dependencies = [
"requests",
'importlib-metadata; python_version<"3.10"',
]
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"
# ... other project metadata fields as listed in:
# https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
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 Keywords used by the setup.py
file, and can be set via the tool.setuptools
table:
Key |
Value Type (TOML) |
Notes |
---|---|---|
|
array |
See tip below. |
|
array of tables/inline-tables |
Experimental - Each item corresponds to a
|
|
array or |
See tip below. |
|
table/inline-table |
Used when explicitly/manually listing |
|
table/inline-table |
See Data Files Support. |
|
boolean |
|
|
table/inline-table |
Empty by default. See Data Files Support. |
|
array of glob patterns |
Provisional - likely to change with PEP 639
(by default: |
|
table/inline-table |
Discouraged - check Data Files Support. Whenever possible, consider using data files inside the package directories. |
|
array |
Discouraged - equivalent to the |
|
array |
ignored by pip when installing packages |
|
array |
ignored by pip when installing packages |
|
array |
Sets the |
|
boolean |
Obsolete - only relevant for |
|
array |
Obsolete - only relevant for |
|
array |
Deprecated - use implicit namespaces instead (PEP 420). |
Note
The TOML value types array
and table/inline-table
are roughly
equivalent to the Python’s list
and dict
data types, respectively.
Please note that some of these configurations are deprecated, obsolete or at least
discouraged, but they are made available to ensure portability.
Deprecated and obsolete configurations may be removed in future versions of setuptools
.
New packages should avoid relying on discouraged fields if possible, and
existing packages should consider migrating to alternatives.
Tip
When both py-modules
and packages
are left unspecified,
setuptools
will attempt to perform Automatic discovery, which should
cover most popular project directory organization techniques, such as the
src-layout and the 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 [3] as shown below:
[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:
[tool.setuptools]
packages = ["my_package"]
If you want to publish a distribution that does not include any Python module (e.g. a “meta-distribution” that just aggregate dependencies), please consider something like the following:
[tool.setuptools]
packages = []
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
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
[2]. For example:
# ...
[project]
name = "my_package"
dynamic = ["version", "readme"]
# ...
[tool.setuptools.dynamic]
version = {attr = "my_package.__version__"} # any module attribute compatible with ast.literal_eval
readme = {file = ["README.rst", "USAGE.rst"]}
In the dynamic
table, the attr
directive [3] will read an
attribute from the given module [4], while file
will read the contents
of all given files and concatenate them in a single string.
Key |
Directive |
Notes |
---|---|---|
|
|
|
|
|
Here you can also set
If |
|
|
One-line text (no line breaks) |
|
|
Multi-line text with one classifier per line |
|
|
INI format following Entry points specification
( |
|
|
subset of the |
|
|
subset of the |
Supporting file
for dependencies is meant for a convenience for packaging
applications with possibly strictly versioned dependencies.
Library packagers are discouraged from using overly strict (or “locked”)
dependency versions in their dependencies
and optional-dependencies
.
Currently, when specifying optional-dependencies
dynamically, all of the groups
must be specified dynamically; one can not specify some of them statically and
some of them dynamically.
Also note that the file format for specifying dependencies resembles a requirements.txt
file,
however please keep in mind that all non-comment lines must conform with PEP 508
(pip
specific syntaxes, e.g. -c/-r/-e
and other flags, are not supported).
Note
If you are using an old version of setuptools
, you might need to ensure
that all files referenced by the file
directive are included in the sdist
(you can do that via MANIFEST.in
or using plugins such as setuptools-scm
,
please have a look on Controlling files in the distribution for more information).
Changed in version 66.1.0: Newer versions of setuptools
will automatically add these files to the sdist
.
It is advisable to use literal values together with attr
(e.g. str
,
tuple[str]
, see ast.literal_eval()
). This is recommend
in order to support the common case of a literal value assigned to a variable
in a module containing (directly or indirectly) third-party imports.
attr
first tries to read the value from the module by examining the
module’s AST. If that fails, attr
falls back to importing the module,
using importlib.util.spec_from_file_location()
recommended recipe
(see example on Python docs
about “Importing a source file directly”).
Note however that importing the module is error prone since your package is
not installed yet. You may also need to manually add the project directory to
sys.path
(via setup.py
) in order to be able to do that.
Notes