pyproject_parser.parsers

TOML configuration parsers.

Classes:

RequiredKeysConfigParser(​)

Abstract base class for TOML configuration parsers which have required keys.

BuildSystemParser(​)

Parser for the build-system table table from pyproject.toml.

PEP621Parser(​)

Parser for PEP 621 metadata from pyproject.toml.

class RequiredKeysConfigParser[source]

Bases: AbstractConfigParser

Abstract base class for TOML configuration parsers which have required keys.

Methods:

parse(​config[, set_defaults])

Parse the TOML configuration.

assert_sequence_not_str(​obj, path[, what])

Assert that obj is a Sequence and not a str, otherwise raise an error with a helpful message.

parse(config, set_defaults=False)[source]

Parse the TOML configuration.

Parameters
Return type

Dict[str, Any]

assert_sequence_not_str(obj, path, what='type')[source]

Assert that obj is a Sequence and not a str, otherwise raise an error with a helpful message.

Parameters
  • obj (Any) – The object to check the type of.

  • path (Iterable[str]) – The elements of the path to obj in the TOML mapping.

  • what (str) – What obj is, e.g. 'type', 'value type'. Default 'type'.

class BuildSystemParser[source]

Bases: RequiredKeysConfigParser

Parser for the build-system table table from pyproject.toml.

Methods:

parse_requires(​config)

Parse the requires key.

parse_build_backend(​config)

Parse the build_backend key defined by PEP 517.

parse_backend_path(​config)

Parse the backend-path key defined by PEP 517.

parse(​config[, set_defaults])

Parse the TOML configuration.

parse_requires(config)[source]

Parse the requires key.

Parameters

config (Dict[str, Any]) – The unparsed TOML config for the build-system table.

Return type

List[ComparableRequirement]

parse_build_backend(config)[source]

Parse the build_backend key defined by PEP 517.

Parameters

config (Dict[str, Any]) – The unparsed TOML config for the build-system table.

Return type

str

parse_backend_path(config)[source]

Parse the backend-path key defined by PEP 517.

Parameters

config (Dict[str, Any]) – The unparsed TOML config for the build-system table.

Return type

List[str]

parse(config, set_defaults=False)[source]

Parse the TOML configuration.

Parameters
Return type

BuildSystemDict

class PEP621Parser[source]

Bases: RequiredKeysConfigParser

Parser for PEP 621 metadata from pyproject.toml.

Methods:

parse_name(​config)

Parse the name key, giving the name of the project.

parse_version(​config)

Parse the version key, giving the version of the project as supported by PEP 440.

parse_description(​config)

Parse the description key, giving a summary description of the project.

parse_readme(​config)

Parse the readme key, giving the full description of the project (i.e.

parse_requires_python(​config)

Parse the requires-python key, giving the Python version requirements of the project.

parse_license(​config)

Parse the license key.

parse_authors(​config)

Parse the authors key.

parse_maintainers(​config)

Parse the maintainers key.

parse_keywords(​config)

Parse the keywords key, giving the keywords for the project.

parse_classifiers(​config)

Parse the classifiers key, giving the trove classifiers which apply to the project.

parse_urls(​config)

Parse the urls table.

parse_scripts(​config)

Parse the scripts table.

parse_gui_scripts(​config)

Parse the gui-scripts table.

parse_entry_points(​config)

Parse the entry-points table.

parse_dependencies(​config)

Parse the dependencies key, giving the dependencies of the project.

parse_optional_dependencies(​config)

Parse the optional-dependencies table, giving the optional dependencies of the project.

parse(​config[, set_defaults])

Parse the TOML configuration.

static parse_name(config)[source]

Parse the name key, giving the name of the project.

This key is required, and must be defined statically.

Tools SHOULD normalize this name, as specified by PEP 503, as soon as it is read for internal consistency.

Example:

[project]
name = "spam"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

str

static parse_version(config)[source]

Parse the version key, giving the version of the project as supported by PEP 440.

Users SHOULD prefer to specify normalized versions.

Example:

[project]
version = "2020.0.0"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Version

parse_description(config)[source]

Parse the description key, giving a summary description of the project.

Example:

[project]
description = "Lovely Spam! Wonderful Spam!"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

str

static parse_readme(config)[source]

Parse the readme key, giving the full description of the project (i.e. the README).

This field accepts either a string or a table. If it is a string then it is the relative path to a text file containing the full description. The file’s encoding MUST be UTF-8, and have one of the following content types:

  • text/markdown, with a case-insensitive .md suffix.

  • text/x-rst, with a case-insensitive .rst suffix.

  • text/plain, with a case-insensitive .txt suffix.

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 instead be a table with the following keys:

  • file – a string value representing a relative path to a file containing the full description.

  • text – a string value which is the full description.

  • content-type – (required) a string specifying the content-type of the full description.

  • charset – (optional, default UTF-8) the encoding of the file. Tools MAY support other encodings if they choose to.

The file and text keys are mutually exclusive, but one must be provided in the table.

Examples:

[project]
readme = "README.rst"

[project.readme]
file = "README.rst"
content-type = "text/x-rst"
encoding = "UTF-8"

[project.readme]
text = "Spam is a brand of canned cooked pork made by Hormel Foods Corporation."
content-type = "text/x-rst"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Readme

static parse_requires_python(config)[source]

Parse the requires-python key, giving the Python version requirements of the project.

The requirement should be in the form of a PEP 508 marker.

Example:

[project]
requires-python = ">=3.6"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

SpecifierSet

static parse_license(config)[source]

Parse the license key.

The table may have one of two keys:

  • file – a string value that is a relative file path to the file which contains the license for the project. The file’s encoding MUST be UTF-8.

  • text – 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.

Example:

[project.license]
file = "LICENSE.rst"

[project.license]
file = "COPYING"

[project.license]
text = """
This software may only be obtained by sending the author a postcard,
and then the user promises not to redistribute it.
"""
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

License

parse_authors(config)[source]

Parse the authors key.

The tables list the people or organizations considered to be the “authors” of the project.

Each table has 2 keys: name and email. Both values must be strings.

  • The name value MUST be a valid email name (i.e. whatever can be put as a name, before an email, in RFC 822) and not contain commas.

  • The email value MUST be a valid email address.

Both keys are optional.

Using the data to fill in core metadata is as follows:

  1. If only name is provided, the value goes in Author.

  2. If only email is provided, the value goes in Author-email.

  3. If both email and name are provided, the value goes in Author-email. The value should be formatted as {name} <{email}> (with appropriate quoting, e.g. using email.headerregistry.Address).

  4. Multiple values should be separated by commas.

Example:

[project]
authors = [
    {email = "hi@pradyunsg.me"},
    {name = "Tzu-Ping Chung"}
]

[[project.authors]]
name = "Tzu-Ping Chung"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

List[Author]

parse_maintainers(config)[source]

Parse the maintainers key.

The tables list the people or organizations considered to be the “maintainers” of the project.

Each table has 2 keys: name and email. Both values must be strings.

  • The name value MUST be a valid email name (i.e. whatever can be put as a name, before an email, in RFC 822) and not contain commas.

  • The email value MUST be a valid email address.

Both keys are optional.

  1. If only name is provided, the value goes in Maintainer.

  2. If only email is provided, the value goes in Maintainer-email.

  3. If both email and name are provided, the value goes in Maintainer-email, with the format {name} <{email}> (with appropriate quoting, e.g. using email.headerregistry.Address).

  4. Multiple values should be separated by commas.

Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

List[Author]

parse_keywords(config)[source]

Parse the keywords key, giving the keywords for the project.

Example:

[project]
keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

List[str]

parse_classifiers(config)[source]

Parse the classifiers key, giving the trove classifiers which apply to the project.

Example:

[project]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python"
]
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

List[str]

parse_urls(config)[source]

Parse the urls table.

A table of URLs where the key is the URL label and the value is the URL itself.

Example:

[project.urls]
homepage = "https://example.com"
documentation = "https://readthedocs.org"
repository = "https://github.com"
changelog = "https://github.com/me/spam/blob/master/CHANGELOG.md"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Dict[str, str]

parse_scripts(config)[source]

Parse the scripts table.

Format: Table, with keys and values of strings

The console scripts provided by the project.

The keys are the names of the scripts and the values are the object references in the form module.submodule:object.

Example:

[project.scripts]
spam-cli = "spam:main_cli"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Dict[str, str]

parse_gui_scripts(config)[source]

Parse the gui-scripts table.

Format: table, with keys and values of strings

The graphical application scripts provided by the project.

The keys are the names of the scripts and the values are the object references in the form module.submodule:object.

Example:

[project.gui-scripts]
spam-gui = "spam.gui:main_gui"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Dict[str, str]

parse_entry_points(config)[source]

Parse the entry-points table.

Format: Table of tables, with keys and values of strings

Each sub-table’s name is an entry point group.

  • Users MUST NOT create nested sub-tables but instead keep the entry point groups to only one level deep.

  • Users MUST NOT created sub-tables for console_scripts or gui_scripts. Use [project.scripts] and [project.gui-scripts] instead.

See the entry point specification for more details.

Example:

[project.entry-points."spam.magical"]
tomatoes = "spam:main_tomatoes"

# pytest plugins refer to a module, so there is no ':obj'
[project.entry-points.pytest11]
nbval = "nbval.plugin"
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Dict[str, Dict[str, str]]

parse_dependencies(config)[source]

Parse the dependencies key, giving the dependencies of the project.

Each string MUST be formatted as a valid PEP 508 string.

Example:

[project]
dependencies = [
    "httpx",
    "gidgethub[httpx]>4.0.0",
    "django>2.1; os_name != 'nt'",
    "django>2.0; os_name == 'nt'"
]
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

List[ComparableRequirement]

parse_optional_dependencies(config)[source]

Parse the optional-dependencies table, giving the optional dependencies of the project.

  • The keys specify an extra, and must be valid Python identifiers.

  • The values are arrays of strings, which must be valid PEP 508 strings.

Example:

[project.optional-dependencies]
test = [
  "pytest < 5.0.0",
  "pytest-cov[all]"
]
Parameters

config (Dict[str, Any]) – The unparsed TOML config for the project table.

Return type

Dict[str, List[ComparableRequirement]]

parse(config, set_defaults=False)[source]

Parse the TOML configuration.

Parameters
Return type

ProjectDict