Setuptools-specific configuration¶

While the standardproject table in thepyproject.toml file covers mostof the metadata used during the packaging process, there are still somesetuptools-specific configurations that can be set by users that requirecustomization.These configurations are completely optional and probably can be skipped whencreating simple packages.They are equivalent to theKeywords used by thesetup.pyfile, and can be set via thetool.setuptools table:

Please note that some of these configurations are deprecated, obsolete or at leastdiscouraged, but they are made available to ensure portability.Deprecated and obsolete configurations may be removed in future versions ofsetuptools.New packages should avoid relying on discouraged fields if possible, andexisting packages should consider migrating to alternatives.

[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)

[tool.setuptools]packages=["my_package"]

[tool.setuptools]packages=[]

Dynamic Metadata¶

Note that in the first example of this page we usedynamic to identifywhich metadata fields are dynamically computed during the build by eithersetuptools itself or the plugins installed viabuild-system.requires(e.g.setuptools-scm is capable of deriving the current project versiondirectly from thegitversion control system).

Currently the following fields can be listed as dynamic:version,classifiers,description,entry-points,scripts,gui-scripts andreadme.When these fields are expected to be provided bysetuptools acorresponding entry is required in thetool.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_evalreadme={file=["README.rst","USAGE.rst"]}

In thedynamic table, theattr directive[3] will read anattribute from the given module[4], whilefile will read the contentsof all given files and concatenate them in a single string.

Supportingfile for dependencies is meant for a convenience for packagingapplications with possibly strictly versioned dependencies.

Library packagers are discouraged from using overly strict (or “locked”)dependency versions in theirdependencies andoptional-dependencies.

Currently, when specifyingoptional-dependencies dynamically, all of the groupsmust be specified dynamically; one can not specify some of them statically andsome of them dynamically.

Also note that the file format for specifying dependencies resembles arequirements.txt file,however please keep in mind that all non-comment lines must conform withPEP 508(pip specific syntaxes, e.g.-c/-r/-e and other flags, are not supported).

It is advisable to use literal values together withattr (e.g.str,tuple[str], seeast.literal_eval()). This is recommendin order to support the common case of a literal value assigned to a variablein a module containing (directly or indirectly) third-party imports.

attr first tries to read the value from the module by examining themodule’s AST. If that fails,attr falls back to importing the module,usingimportlib.util.spec_from_file_location() recommended recipe(seeexample on Python docsabout “Importing a source file directly”).Note however that importing the module is error prone since your package isnot installed yet. You may also need to manually add the project directory tosys.path (viasetup.py) in order to be able to do that.

Notes

pip may allow editable install only withpyproject.tomlandsetup.cfg. However, this behavior may not be consistent over variouspipversions and other packaging-related tools(setup.py is more reliable on those scenarios).

Dynamicscripts andgui-scripts are a special case.When resolving these metadata keys,setuptools will look fortool.setuptools.dynamic.entry-points, and use the values of theconsole_scripts andgui_scriptsentry-point groups.

In the context of this document,directives are special TOMLvalues that are interpreted differently bysetuptools (usually triggering anassociated 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 fortool.setuptools.packages, or{attr="mymodule.attr"}directive fortool.setuptools.dynamic.version.

attr is meant to be used when the module attribute is staticallyspecified (e.g. as a string). As a rule of thumb, theattribute should be able to be parsed withast.literal_eval(), andshould not be modified or re-assigned.