PNG
IHDR x sBIT|d pHYs + tEXtSoftware www.inkscape.org< ,tEXtComment
File Manager
File Manager
Viewing File: declarative_config.rst
.. _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 :doc:`keyword arguments </references/keywords>` 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 configuration has all the Python 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, using :ref:`package_dir <keyword/package_dir>`, 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
In this example, the value for the :ref:`package_dir <keyword/package_dir>`
configuration (i.e. ``=src``) is parsed as ``{"": "src"}``.
The ``""`` key has a special meaning in this context, and indicates that all the
packages are contained inside the given directory.
Also note that the value for ``[options.packages.find] where`` matches the
value associated with ``""`` in the ``package_dir`` dictionary.
..
TODO: Add the following tip once the auto-discovery is no longer experimental:
Starting in version 61, ``setuptools`` can automatically infer the
configurations for both ``packages`` and ``package_dir`` for projects using
a ``src/`` layout (as long as no value is specified for ``py_modules``).
Please see :doc:`package discovery </userguide/package_discovery>` for more
details.
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 each entry corresponds to a key/value pair,
with keys separated from values by ``=``.
If an entry starts with ``=``, the key is assumed to be an empty string
(e.g. ``=src`` is parsed as ``{"": "src"}``).
* ``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
.. important::
The ``file:`` directive is sandboxed and won't reach anything outside the
project directory (i.e. the directory containing ``setup.cfg``/``pyproject.toml``).
.. attention::
When using the ``file:`` directive, please make sure that all necessary
files are included in the ``sdist``. You can do that via ``MANIFEST.in``
or using plugins such as ``setuptools-scm``.
Please have a look on :doc:`/userguide/miscellaneous` for more information.
Metadata
--------
.. attention::
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 file:, list-semi **BETA** [#opt-6]_
extras_require file:, section **BETA** [#opt-2]_, [#opt-6]_
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 [#opt-5]_
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.
.. [#opt-5] ``namespace_packages`` is deprecated in favour of native/implicit
namespaces (:pep:`420`). Check :doc:`the Python Packaging User Guide
<PyPUG:guides/packaging-namespace-packages>` for more information.
.. [#opt-6] ``file:`` directives for reading requirements are supported since version 62.6.
The format for the file resembles a ``requirements.txt`` file,
however please keep in mind that all non-comment lines must conform with :pep:`508`
(``pip``-specify syntaxes, e.g. ``-c/-r/-e`` flags, are not supported).
Library developers should avoid tightly pinning their dependencies to a specific
version (e.g. via a "locked" requirements file).
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.
b IDATxytVսϓ22 A@IR :hCiZ[v*E:WũZA ^dQeQ @ !jZ'>gsV仿$|?g)&x-E IENT ; @x T.i%-X} SvS5.r/ UHz^_$-W" w)Ɗ/ @Z &IoX P$K} JzX:;` &, ŋui,e6mX
Եr Kb1ԗ) D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A D A ݀!I*]R;I2$eZ#ORZSrr 6mteffu*((Pu'v{ DIߔ4^pIm '77WEEE;vƎ 4- $]'RI{\I&G :IHJ
DWBB=\WRm
o$K(V 9 ABB.}jѢv `^?IOȅ} ڶmG }T#FJ`5 6$- ھ}FI&v;0(h; Б 38CӧOWf!; A
i:F _m9s&|q%=# wZprrrla
A & P\\СC[A#! { olF}
`E2} MK/vV )i{ 4BffV\|ۭX `b@kɶ@%i$K z5zhmX [IXZ ` 'b%$r5 M4º /l
ԃ ߖ xhʔ)[@=}
K6IM}^ 5k㏷݆z
ΗÿO:gdGBmyT/@+Vɶ纽zl.yit뭷zV 0[Y^>Wsqs}\/@$(T7f.Inݺi R$푔n.~?H))\Z RW'Mo~v
Ov6oԃ xz! S,&xm/yɞԟ?'uaSѽb, 8GלKboi&3 t7Y,)JJ c[nzӳdE&KsZLӄ I ?@ & %ӟ۶mSMMњ0 iؐSZ, |J+N
~,0A 0!5%Q-YQQa 3 }$_vVr f9f?S 8` z D A D A D A D A D A D A D A D A D A dqP,تmMmg 1V?rSI꒟]u|l
RCyEf٢9 jURbztѰ!m5~tGj2DhG*{H9)꒟ר3:(+3\?/;TUݭʴ~S6lڧUJ*i$d(#=Yݺd{,p|3B)) q:vN0Y.jkק6;SɶVzHJJЀ-utѹսk>QUU \~]fFnK?&ߡ5b=z9)^|u_k-[ y%ZNU6 7Mi:]ۦ tk[n
X(e6 Bb."8cۭ|~teuuw|ήI-5"~Uk;ZicEmN/:]M>
cQ^uiƞ??Ң pc# TUU3UakNwA`:Y_V-8.KKfRi tv*
9S6ֿj,ՃNOMߤ]z^fOh|<>@Å5 _/Iu?{SY4hK/2]4%it5q]GGe2%iR|
W&f*^]??vq[LgE_3f}Fxu~}qd-ږFxu~I N >\;͗O֊:̗WJ@ Bh W=y|GgwܷH_NY?)Tdi'?խwhlmQi !SUUsw4kӺe4rfxu-[nHtMFj}H_u~w>)oV}(T'ebʒv3_[+vn @Ȭ\S}ot}w=k HFnxg S 0eޢm~l}uqZfF oZuuEg
`zt~? b;t%>WTkķh[ 2eG8LIWx,^\thrl^Ϊ{=dž<}qV@ ⠨Wy^LF_>0UkD uʫuCs$)I v:IK; 6ֲ4{^6 եm+l 3>݆uM 9u ?>Zc }g~qhKwڭ e FMM~pМuqǿz6Tb@8 @Y|jx](^]gf}M"tG
-w.@ vOqh~/HII` S[l.6nØXL9vU cOoB\xoǤ'T&I ǍQw_wpv[kmO{w~>#=P1Pɞa-we:iǏlHo꒟f9SzH?+shk%Fs:q VhqY `jvO'ρ?PyX3lх]˾uV{ݞ]1,MzYNW~̈́ joYn}ȚF߾mS]F z+EDxm/d{F{-W-4wY듏:??_gPf
^3ecg ҵs8R2מz@TA NGj)}CNi/R~}c:5{! ZHӋӾ6}T] G]7W6^n
9*,YqOZj :P?Q D FL|?-^.Ɵ7}fFhxe2Ps cz1&5\cn[=Vn[ĶE鎀uˌd3GII k;lNmشOuuRVfBE]ۣe Ӷu
:X-[(er4~LHi6:Ѻ@ԅr ST0 trk%$Č0 ez" *z " T/X9|8.C5Feg} C Q%͞ˣJvL/? j^ h & 9xF`њZ( & yF&Iݻfg #W;3^{Wo^4'v V[[K';+mӍִ] AC @ W?1^{එyh +^]fm~iԵ] AB @WTk̏t uR?l.OIHiYyԶ] Aˀ 7c:q}ힽaf6Z~қm(+sK4{^6}T *UUu]n.:kx{:2 _m=sAߤU@? Z-Vކе z왍Nэ{|5 pڶn b
p-@sPg]0G7fy-M{GCF'%{4` =$-Ge\ eU:m+Zt'WjO!OAF @ik&t݆ϥ_
e}=]" Wz_.͜E3leW Fih|t-wZۍ-uw=6 YN {6|} | *={Ѽn.S .z1z jۻTH]흾 D uDvmvK .` V]yY~sI@t?/ϓ. m&[ " +P?MzovVЫG3- G RR[(!!\_,^%?v@ ҵő
m`Y)tem8GM x.))A]Y i`ViW`?^~! S#^+ѽGZj?Vģ 0.))AlzL*]OXrY `DBBLOj{-MH'ii-ϰ ok7^
)쭡b]UXSְmռY|5 *cֽk0B7镹%ڽP# 8nȎq}mJr23_>lE5$iwui+ H~F`IjƵ@q
\ @#qG 0" . 0" l ` . 0! , AQHN6qzkKJ#o;`Xv2>,tێJJ7Z/*A .@fفjMzkg @TvZH3Zxu6Ra'%O?/d Q5x YkU]Rֽkق@ DaS^RSּ5|BeHNN͘p
HvcYcC5:y
#`οb; z2 .!kr}gUWkyZn=f Pvsn3p~;4p˚=ē~NmI] ¾ 0lH[_L hs h_ ғߤc_њe c) g 7VIZ5 yrgk̞W#IjӪv>՞y睝M8[ |]\շ 8M 6%|@P ZڨI-m>=k= 'aiRo-x?>Q. }`Ȏ:Wsmu u >
.@,&;+!!˱tﭧD QwRW\vF\~Q7>sp Yw$%A~;~}6 ¾ g &if_=j,v+U L1(tW ake:@Ș>j$Gq2t7S?vL|]u/ .(0 E 6Mk6hiۺzښOrifޱxm/Gx> Lal%%~{lBsR4* }{0Z/ tNIɚpV ^# Lf:u@k#RSu
=S^ZyuR/.@n&z~B=0eg뺆#,Þ[ B/?H uUf7y
Wy}Bwegל`Wh(||`l`.;Ws?V@" c:iɍL֯PGv6zctM̠':wuW;d=;EveD}9J@ B(0iհ bvP1{\P&G7DIy_$-Q jm~Yrr&]CDv%bh|Yzni _ R ;kg}nJOIIwy uL}{ЌNj}:+3Y?:WJ/N+Rzd=hb;dj͒suݔ@NKMԄ jqzC5 @y°hL m;*5ezᕏ=ep
XL n?מ:r`۵tŤZ|1v`V뽧_csج'ߤ%oTuumk%%%h)uy]Nk[n
'b2 l.=͜E%gf$[c;s:V-͞WߤWh-j7]4=F-X]>ZLSi[Y*We; Zan(Ӈ W|e(HNNP5[=
r4tP
&0< pc# `vTNV
GFqvTi * Tyam$ߏWyE* VJKMTfFw >'$-ؽ.Ho.8c"@ D A D A D A D A D A D A D A D A D A~j*֘, N;Pi3599h=g oض L giJ5փy~}&Zd9 p֚
e:|hL``b/d9 p? fgg+%%hMg Xosج, ΩOl0Zh=x djL mhݻo O [g_l, 8a]٭+ӧ0 $I] c]:粹:Teꢢ"5a^Kgh,&= =՟ ^߶ߢE ܹS J}I%:8
IDAT~,9/ʃ PW'Mo }zNƍ쨓zPb NZ~^z=4mswg;5 Y~SVMR XUյڱRf?s:w
; 6H:º i 5 -maM &O3; 1IKeam Zh͛7+##v+c ~u~ca] GnF'ټL~ PPPbn
v oC 4R,ӟgg %hq} @#M4IÇ Oy^xM Zx
) yO w @HkN˖-Sǎ mb]X@n+i͖ !++K3gd\$mt$^ YfJ \8PRF )77Wא!Cl $i: @@_oG I{$# 8磌ŋ9 1A (Im7 ֭>}ߴJq7ޗt^ -[ԩSj*}%]&'
- ɓ'ꫯVzzvB#; a
7@GxI{jƌ.LÇWBB7 `O"I$ /@R @ eee@۷ >}0 ,ɒ2$53Xs|cS~r pTYYY} k Hc %&k.], @ A D A D A D A D A D A D A D A D A @lT<%''*Lo^={رc5h %$+CnܸQ3fҥK}vUVVs9G
R,_{ xˇ3 o߾;TTTd}馛]uuuG~iԩ@4 bnvmvfϞ /Peeeq}}z a
I~,誫{UWW뮻}_~YƍSMMMYχ ֝waw \ ď cxꩧtEƍկ_?۷5@u ?1kNׯWzz/wy>}zj3 k (ٺu q_Zvf̘:~ AB Q&r| ! %KҥKg Ԟ={<_X-z ! CyFUUz~ AB QIIIjݺW $ UXXDٳZ~ AB QƍecW $<(~<RSSvZujjjԧO ZQu@4 8m&&&jԩg $ ď 1h ͟?_{768@ g
=@ `)))5o6m 3 ) ѣƌJ;wҿUTT /KZR{~a=@ 0o<*狔iFɶ[ˎ ;T]] OX@ ?K.ۈxN p p p p p p p p p p p p p p p p pP fl߾] ,{ｧk۶mڿo5 BTӦMӴiӴ|r D B2e |An!D y'tkΝ[A $***t5'
" !駟oaD nΝ:t֭[gD ШQ0 6qD;@ x M6v( PiizmZ 4ew" @ ̴ixf [~-F ٱc&IZ 2|n!?$ @{[HTɏ #@h Ȏ I# _m (F /6Z3 z'\r, r!;w2Z3j=~G Y 7"I$i I. p_" ? p N` y D D ?: _ G ÿa b7 J ! Bx @0 Bo
cG @`1C [ @0G
@`0C _ u V1 aC X > W ` | `! < S `" <. `# c `? cA C 4
? c p# ~ @0 ?: 0 8& _ M Q1 J h# ? /` 7; I q 7 a w Q A 1 H p
! #< 8/# @1Ul7 =S=K.4Z?E _$i@ ! 1!E 4? ` P_ @B ă 1 0# : " aU,xb F Y1
[n |n
#' v EH:`x b
# v D 4 Y hi.i& EΖv# O H 4IŶ}:Ik h @tZRF # (tXҙzZ ? I3l7 q@õ|ۍ 1,GpuY Ꮿ@ hJv# x xk$
v# 9 5 }_$ c S#=+"K {F*m7`# %H:NRS p6I?sIՖ{Ap$I$I:QRv2$Z @UJ*$]<FO4 IENDB`