Declaring project metadata¶
PEP 621 specifies how to write a project’s
core metadata in a pyproject.toml
file for
packaging-related tools to consume. It defines the following
specification as the canonical source for the format used.
There are two kinds of metadata: static and dynamic. Static
metadata is specified in the pyproject.toml
file directly and
cannot be specified or changed by a tool. Dynamic metadata is listed
via the dynamic
field (defined later in this specification) and
represents metadata that a tool will later provide.
The fields defined in this specification MUST be in a table named
[project]
in pyproject.toml
. No tools may add fields to this
table which are not defined by this specification. For tools wishing
to store their own settings in pyproject.toml
, they may use the
[tool]
table as defined in the
build dependency declaration specification.
The lack of a [project]
table implicitly means the build back-end
will dynamically provide all fields.
The only fields required to be statically defined are:
name
The fields which are required but may be specified either statically or listed as dynamic are:
version
All other fields are considered optional and my be specified statically, listed as dynamic, or left unspecified.
name
¶
TOML type: string
Corresponding core metadata field: Name
The name of the project.
Tools SHOULD normalize this name, as specified by PEP 503, as soon as it is read for internal consistency.
version
¶
TOML type: string
Corresponding core metadata field: Version
The version of the project as supported by PEP 440.
Users SHOULD prefer to specify already-normalized versions.
description
¶
TOML type: string
Corresponding core metadata field: Summary
The summary description of the project.
readme
¶
TOML type: string or table
Corresponding core metadata field: Description and Description-Content-Type
The full description of the project (i.e. the README).
The field accepts either a string or a table. If it is a string then
it is a path relative to pyproject.toml
to a text file containing
the full description. Tools MUST assume the file’s encoding is UTF-8.
If the file path ends in a case-insensitive .md
suffix, then tools
MUST assume the content-type is text/markdown
. If the file path
ends in a case-insensitive .rst
, then tools MUST assume the
content-type is text/x-rst
. If a tool recognizes more extensions
than this PEP, they MAY infer the content-type for the user without
specifying this field as dynamic
. For all unrecognized suffixes
when a content-type is not provided, tools MUST raise an error.
The readme
field may also take a table. The file
key has a
string value representing a path relative to pyproject.toml
to a
file containing the full description. The text
key has a string
value which is the full description. These keys are
mutually-exclusive, thus tools MUST raise an error if the metadata
specifies both keys.
A table specified in the readme
field also has a content-type
field which takes a string specifying the content-type of the full
description. A tool MUST raise an error if the metadata does not
specify this field in the table. If the metadata does not specify the
charset
parameter, then it is assumed to be UTF-8. Tools MAY
support other encodings if they choose to. Tools MAY support
alternative content-types which they can transform to a content-type
as supported by the core metadata. Otherwise
tools MUST raise an error for unsupported content-types.
requires-python
¶
TOML type: string
Corresponding core metadata field: Requires-Python
The Python version requirements of the project.
license
¶
TOML type: table
Corresponding core metadata field: License
The table may have one of two keys. The file
key has a string
value that is a file path relative to pyproject.toml
to the file
which contains the license for the project. Tools MUST assume the
file’s encoding is UTF-8. The text
key has a string value which is
the license of the project. These keys are mutually exclusive, so a
tool MUST raise an error if the metadata specifies both keys.
keywords
¶
TOML type: array of strings
Corresponding core metadata field: Keywords
The keywords for the project.
classifiers
¶
TOML type: array of strings
Corresponding core metadata field: Classifier
Trove classifiers which apply to the project.
urls
¶
TOML type: table with keys and values of strings
Corresponding core metadata field: Project-URL
A table of URLs where the key is the URL label and the value is the URL itself.
Entry points¶
TOML type: table (
[project.scripts]
,[project.gui-scripts]
, and[project.entry-points]
)
There are three tables related to entry points. The
[project.scripts]
table corresponds to the console_scripts
group in the entry points specification. The key
of the table is the name of the entry point and the value is the
object reference.
The [project.gui-scripts]
table corresponds to the gui_scripts
group in the entry points specification. Its
format is the same as [project.scripts]
.
The [project.entry-points]
table is a collection of tables. Each
sub-table’s name is an entry point group. The key and value semantics
are the same as [project.scripts]
. Users MUST NOT create
nested sub-tables but instead keep the entry point groups to only one
level deep.
Build back-ends MUST raise an error if the metadata defines a
[project.entry-points.console_scripts]
or
[project.entry-points.gui_scripts]
table, as they would
be ambiguous in the face of [project.scripts]
and
[project.gui-scripts]
, respectively.
dependencies
/optional-dependencies
¶
TOML type: Array of PEP 508 strings (
dependencies
), and a table with values of arrays of PEP 508 strings (optional-dependencies
)Corresponding core metadata field: Requires-Dist and Provides-Extra
The (optional) dependencies of the project.
For dependencies
, it is a key whose value is an array of strings.
Each string represents a dependency of the project and MUST be
formatted as a valid PEP 508 string. Each string maps directly to
a Requires-Dist entry.
For optional-dependencies
, it is a table where each key specifies
an extra and whose value is an array of strings. The strings of the
arrays must be valid PEP 508 strings. The keys MUST be valid values
for Provides-Extra. Each value
in the array thus becomes a corresponding
Requires-Dist entry for the
matching Provides-Extra
metadata.
dynamic
¶
TOML type: array of string
A corresponding core metadata field does not exist
Specifies which fields listed by this PEP were intentionally unspecified so another tool can/will provide such metadata dynamically. This clearly delineates which metadata is purposefully unspecified and expected to stay unspecified compared to being provided via tooling later on.
A build back-end MUST honour statically-specified metadata (which means the metadata did not list the field in
dynamic
).A build back-end MUST raise an error if the metadata specifies
name
indynamic
.If the core metadata specification lists a field as “Required”, then the metadata MUST specify the field statically or list it in
dynamic
(build back-ends MUST raise an error otherwise, i.e. it should not be possible for a required field to not be listed somehow in the[project]
table).If the core metadata specification lists a field as “Optional”, the metadata MAY list it in
dynamic
if the expectation is a build back-end will provide the data for the field later.Build back-ends MUST raise an error if the metadata specifies a field statically as well as being listed in
dynamic
.If the metadata does not list a field in
dynamic
, then a build back-end CANNOT fill in the requisite metadata on behalf of the user (i.e.dynamic
is the only way to allow a tool to fill in metadata and the user must opt into the filling in).Build back-ends MUST raise an error if the metadata specifies a field in
dynamic
but the build back-end was unable to determine the data for it (omitting the data, if determined to be the accurate value, is acceptable).