283 lines
10 KiB
ReStructuredText
283 lines
10 KiB
ReStructuredText
|
.. _declarative config:
|
|||
|
|
|
|||
|
|
------------------------------------------------
|
|||
|
|
Configuring setuptools using ``setup.cfg`` files
|
|||
|
|
------------------------------------------------
|
|||
|
|
|
|||
|
|
.. note:: New in 30.3.0 (8 Dec 2016).
|
|||
|
|
|
|||
|
|
.. important::
|
|||
|
|
If compatibility with legacy builds (i.e. those not using the :pep:`517`
|
|||
|
|
build API) is desired, a ``setup.py`` file containing a ``setup()`` function
|
|||
|
|
call is still required even if your configuration resides in ``setup.cfg``.
|
|||
|
|
|
|||
|
|
``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
|
|||
|
|
to define a package’s metadata and other options that are normally supplied
|
|||
|
|
to the ``setup()`` function (declarative config).
|
|||
|
|
|
|||
|
|
This approach not only allows automation scenarios but also reduces
|
|||
|
|
boilerplate code in some cases.
|
|||
|
|
|
|||
|
|
.. _example-setup-config:
|
|||
|
|
|
|||
|
|
.. code-block:: ini
|
|||
|
|
|
|||
|
|
[metadata]
|
|||
|
|
name = my_package
|
|||
|
|
version = attr: my_package.VERSION
|
|||
|
|
description = My package description
|
|||
|
|
long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
|
|||
|
|
keywords = one, two
|
|||
|
|
license = BSD 3-Clause License
|
|||
|
|
classifiers =
|
|||
|
|
Framework :: Django
|
|||
|
|
Programming Language :: Python :: 3
|
|||
|
|
|
|||
|
|
[options]
|
|||
|
|
zip_safe = False
|
|||
|
|
include_package_data = True
|
|||
|
|
packages = find:
|
|||
|
|
install_requires =
|
|||
|
|
requests
|
|||
|
|
importlib-metadata; python_version<"3.8"
|
|||
|
|
|
|||
|
|
[options.package_data]
|
|||
|
|
* = *.txt, *.rst
|
|||
|
|
hello = *.msg
|
|||
|
|
|
|||
|
|
[options.entry_points]
|
|||
|
|
console_scripts =
|
|||
|
|
executable-name = my_package.module:function
|
|||
|
|
|
|||
|
|
[options.extras_require]
|
|||
|
|
pdf = ReportLab>=1.2; RXP
|
|||
|
|
rest = docutils>=0.3; pack ==1.1, ==1.3
|
|||
|
|
|
|||
|
|
[options.packages.find]
|
|||
|
|
exclude =
|
|||
|
|
examples*
|
|||
|
|
tools*
|
|||
|
|
docs*
|
|||
|
|
my_package.tests*
|
|||
|
|
|
|||
|
|
Metadata and options are set in the config sections of the same name.
|
|||
|
|
|
|||
|
|
* Keys are the same as the keyword arguments one provides to the ``setup()``
|
|||
|
|
function.
|
|||
|
|
|
|||
|
|
* Complex values can be written comma-separated or placed one per line
|
|||
|
|
in *dangling* config values. The following are equivalent:
|
|||
|
|
|
|||
|
|
.. code-block:: ini
|
|||
|
|
|
|||
|
|
[metadata]
|
|||
|
|
keywords = one, two
|
|||
|
|
|
|||
|
|
[metadata]
|
|||
|
|
keywords =
|
|||
|
|
one
|
|||
|
|
two
|
|||
|
|
|
|||
|
|
* In some cases, complex values can be provided in dedicated subsections for
|
|||
|
|
clarity.
|
|||
|
|
|
|||
|
|
* Some keys allow ``file:``, ``attr:``, ``find:``, and ``find_namespace:`` directives in
|
|||
|
|
order to cover common usecases.
|
|||
|
|
|
|||
|
|
* Unknown keys are ignored.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Using a ``src/`` layout
|
|||
|
|
=======================
|
|||
|
|
|
|||
|
|
One commonly used package configuration has all the module source code in a
|
|||
|
|
subdirectory (often called the ``src/`` layout), like this::
|
|||
|
|
|
|||
|
|
├── src
|
|||
|
|
│ └── mypackage
|
|||
|
|
│ ├── __init__.py
|
|||
|
|
│ └── mod1.py
|
|||
|
|
├── setup.py
|
|||
|
|
└── setup.cfg
|
|||
|
|
|
|||
|
|
You can set up your ``setup.cfg`` to automatically find all your packages in
|
|||
|
|
the subdirectory like this:
|
|||
|
|
|
|||
|
|
.. code-block:: ini
|
|||
|
|
|
|||
|
|
# This example contains just the necessary options for a src-layout, set up
|
|||
|
|
# the rest of the file as described above.
|
|||
|
|
|
|||
|
|
[options]
|
|||
|
|
package_dir=
|
|||
|
|
=src
|
|||
|
|
packages=find:
|
|||
|
|
|
|||
|
|
[options.packages.find]
|
|||
|
|
where=src
|
|||
|
|
|
|||
|
|
Specifying values
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
Some values are treated as simple strings, some allow more logic.
|
|||
|
|
|
|||
|
|
Type names used below:
|
|||
|
|
|
|||
|
|
* ``str`` - simple string
|
|||
|
|
* ``list-comma`` - dangling list or string of comma-separated values
|
|||
|
|
* ``list-semi`` - dangling list or string of semicolon-separated values
|
|||
|
|
* ``bool`` - ``True`` is 1, yes, true
|
|||
|
|
* ``dict`` - list-comma where keys are separated from values by ``=``
|
|||
|
|
* ``section`` - values are read from a dedicated (sub)section
|
|||
|
|
|
|||
|
|
|
|||
|
|
Special directives:
|
|||
|
|
|
|||
|
|
* ``attr:`` - Value is read from a module attribute. ``attr:`` supports
|
|||
|
|
callables and iterables; unsupported types are cast using ``str()``.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
* ``file:`` - Value is read from a list of files and then concatenated
|
|||
|
|
|
|||
|
|
.. note::
|
|||
|
|
The ``file:`` directive is sandboxed and won't reach anything outside
|
|||
|
|
the directory containing ``setup.py``.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Metadata
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
.. note::
|
|||
|
|
The aliases given below are supported for compatibility reasons,
|
|||
|
|
but their use is not advised.
|
|||
|
|
|
|||
|
|
============================== ================= ================= =============== ==========
|
|||
|
|
Key Aliases Type Minimum Version Notes
|
|||
|
|
============================== ================= ================= =============== ==========
|
|||
|
|
name str
|
|||
|
|
version attr:, file:, str 39.2.0 [#meta-1]_
|
|||
|
|
url home-page str
|
|||
|
|
download_url download-url str
|
|||
|
|
project_urls dict 38.3.0
|
|||
|
|
author str
|
|||
|
|
author_email author-email str
|
|||
|
|
maintainer str
|
|||
|
|
maintainer_email maintainer-email str
|
|||
|
|
classifiers classifier file:, list-comma
|
|||
|
|
license str
|
|||
|
|
license_files license_file list-comma 42.0.0
|
|||
|
|
description summary file:, str
|
|||
|
|
long_description long-description file:, str
|
|||
|
|
long_description_content_type str 38.6.0
|
|||
|
|
keywords list-comma
|
|||
|
|
platforms platform list-comma
|
|||
|
|
provides list-comma
|
|||
|
|
requires list-comma
|
|||
|
|
obsoletes list-comma
|
|||
|
|
============================== ================= ================= =============== ==========
|
|||
|
|
|
|||
|
|
**Notes**:
|
|||
|
|
|
|||
|
|
.. [#meta-1] The ``version`` file attribute has only been supported since 39.2.0.
|
|||
|
|
|
|||
|
|
A version loaded using the ``file:`` directive must comply with PEP 440.
|
|||
|
|
It is easy to accidentally put something other than a valid version
|
|||
|
|
string in such a file, so validation is stricter in this case.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Options
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
======================= =================================== =============== =========
|
|||
|
|
Key Type Minimum Version Notes
|
|||
|
|
======================= =================================== =============== =========
|
|||
|
|
zip_safe bool
|
|||
|
|
setup_requires list-semi 36.7.0
|
|||
|
|
install_requires list-semi
|
|||
|
|
extras_require section [#opt-2]_
|
|||
|
|
python_requires str 34.4.0
|
|||
|
|
entry_points file:, section 51.0.0
|
|||
|
|
scripts list-comma
|
|||
|
|
eager_resources list-comma
|
|||
|
|
dependency_links list-comma
|
|||
|
|
tests_require list-semi
|
|||
|
|
include_package_data bool
|
|||
|
|
packages find:, find_namespace:, list-comma [#opt-3]_
|
|||
|
|
package_dir dict
|
|||
|
|
package_data section [#opt-1]_
|
|||
|
|
exclude_package_data section
|
|||
|
|
namespace_packages list-comma
|
|||
|
|
py_modules list-comma 34.4.0
|
|||
|
|
data_files section 40.6.0 [#opt-4]_
|
|||
|
|
======================= =================================== =============== =========
|
|||
|
|
|
|||
|
|
**Notes**:
|
|||
|
|
|
|||
|
|
.. [#opt-1] In the ``package_data`` section, a key named with a single asterisk
|
|||
|
|
(``*``) refers to all packages, in lieu of the empty string used in ``setup.py``.
|
|||
|
|
|
|||
|
|
.. [#opt-2] In the ``extras_require`` section, values are parsed as ``list-semi``.
|
|||
|
|
This implies that in order to include markers, they **must** be *dangling*:
|
|||
|
|
|
|||
|
|
.. code-block:: ini
|
|||
|
|
|
|||
|
|
[options.extras_require]
|
|||
|
|
rest = docutils>=0.3; pack ==1.1, ==1.3
|
|||
|
|
pdf =
|
|||
|
|
ReportLab>=1.2
|
|||
|
|
RXP
|
|||
|
|
importlib-metadata; python_version < "3.8"
|
|||
|
|
|
|||
|
|
.. [#opt-3] The ``find:`` and ``find_namespace:`` directive can be further configured
|
|||
|
|
in a dedicated subsection ``options.packages.find``. This subsection accepts the
|
|||
|
|
same keys as the ``setuptools.find_packages`` and the
|
|||
|
|
``setuptools.find_namespace_packages`` function:
|
|||
|
|
``where``, ``include``, and ``exclude``.
|
|||
|
|
|
|||
|
|
The ``find_namespace:`` directive is supported since Python >=3.3.
|
|||
|
|
|
|||
|
|
.. [#opt-4] ``data_files`` is deprecated and should be avoided.
|
|||
|
|
Please check :doc:`/userguide/datafiles` for more information.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Compatibility with other tools
|
|||
|
|
==============================
|
|||
|
|
|
|||
|
|
Historically, several tools explored declarative package configuration
|
|||
|
|
in parallel. And several of them chose to place the packaging
|
|||
|
|
configuration within the project's :file:`setup.cfg` file.
|
|||
|
|
One of the first was ``distutils2``, which development has stopped in
|
|||
|
|
2013. Other include ``pbr`` which is still under active development or
|
|||
|
|
``d2to1``, which was a plug-in that backports declarative configuration
|
|||
|
|
to ``distutils``, but has had no release since Oct. 2015.
|
|||
|
|
As a way to harmonize packaging tools, ``setuptools``, having held the
|
|||
|
|
position of *de facto* standard, has gradually integrated those
|
|||
|
|
features as part of its core features.
|
|||
|
|
|
|||
|
|
Still this has lead to some confusion and feature incompatibilities:
|
|||
|
|
|
|||
|
|
- some tools support features others don't;
|
|||
|
|
- some have similar features but the declarative syntax differs;
|
|||
|
|
|
|||
|
|
The table below tries to summarize the differences. But, please, refer
|
|||
|
|
to each tool documentation for up-to-date information.
|
|||
|
|
|
|||
|
|
=========================== ========== ========== ===== ===
|
|||
|
|
feature setuptools distutils2 d2to1 pbr
|
|||
|
|
=========================== ========== ========== ===== ===
|
|||
|
|
[metadata] description-file S Y Y Y
|
|||
|
|
[files] S Y Y Y
|
|||
|
|
entry_points Y Y Y S
|
|||
|
|
[backwards_compat] N Y Y Y
|
|||
|
|
=========================== ========== ========== ===== ===
|
|||
|
|
|
|||
|
|
Y: supported, N: unsupported, S: syntax differs (see
|
|||
|
|
:ref:`above example<example-setup-config>`).
|
|||
|
|
|
|||
|
|
Also note that some features were only recently added to ``setuptools``.
|
|||
|
|
Please refer to the previous sections to find out when.
|