`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`.
`DependencyGroupsParser`()	Parser for the dependency groups 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

config (Dict[str, Any])
set_defaults (bool) – If True, the values in self.defaults and self.factories will be set as defaults for the returned mapping. Default False.

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:

`normalize_requirement_name`(name)	Function to normalize a requirement name per e.g.
`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.

static normalize_requirement_name(name)[source]¶

Function to normalize a requirement name per e.g. PEP 503 (where underscores are replaced by hyphens).

New in version 0.9.0.

Return type: str

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

config (Dict[str, Any])
set_defaults (bool) – If True, the values in self.defaults and self.factories will be set as defaults for the returned mapping. Default False.

Return type

BuildSystemDict

class DependencyGroupsParser[source]¶

Bases: AbstractConfigParser

Parser for the dependency groups table table from pyproject.toml.

New in version 0.13.0.

Attributes:

keys

The keys to parse from the TOML file.

Methods:

`parse_group`(config)	Parse a group from the TOML configuration.
`parse`(config[, set_defaults])	Parse the TOML configuration.

property keys¶

The keys to parse from the TOML file.

Return type: List[str]

static parse_group(config)[source]¶

Parse a group from the TOML configuration.

Parameters: config (Any)
Return type: List[Union[str, Dict[str, str]]]

parse(config, set_defaults=False)[source]¶

Parse the TOML configuration.

Parameters

config (Dict[str, Any])
set_defaults (bool) – If True, the values in self.defaults and self.factories will be set as defaults for the returned mapping. Default False.

Return type

Dict[str, List[Union[str, IncludeGroupDict]]]

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_license_files`(config)	Parse the `license-files` key, giving paths to the licence(s) for the project.
`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.
`normalize_requirement_name`(name)	Function to normalize a requirement name per e.g.
`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.

Format: String
Core Metadata: Name

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.

Format: String
Core Metadata: Version

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.

Format: String
Core Metadata: Summary

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

Format: String or table
Core Metadata: Description

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.

Format: String
Core Metadata: Requires-Python

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.

Format: Table or String
Core Metadata: License or License-Expression

Changed in version 0.14.0: Added support for PEP 639 license expressions.

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.

Alternatively, for PEP 639 support, the value may be a string giving an SPDX License Expression.

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.
"""

[project]
license = "MIT AND (Apache-2.0 OR BSD-2-Clause)"

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the project table.
Return type: License

parse_license_files(config)[source]¶

Parse the license-files key, giving paths to the licence(s) for the project.

Format: Array of strings
Core Metadata: License-Files

New in version 0.14.0.

Example:

[project]
license-files = ["LICEN[CS]E*", "vendored/licenses/*.txt", "AUTHORS.md"]

Parameters: config (Dict[str, Any]) – The unparsed TOML config for the project table.
Return type: List[str]

parse_authors(config)[source]¶

Parse the authors key.

Format: Array of inline tables with string keys and values
Core Metadata: Author/Author-email

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:

If only name is provided, the value goes in Author.
If only email is provided, the value goes in Author-email.
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).
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.

Format: Array of inline tables with string keys and values
Core Metadata: Maintainer/Maintainer-email

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.

If only name is provided, the value goes in Maintainer.
If only email is provided, the value goes in Maintainer-email.
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).
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.

Format: Array of strings
Core Metadata: Keywords

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.

Format: Array of strings
Core Metadata: Classifiers

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.

Format: Table, with keys and values of strings
Core Metadata: Project-URL

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]]

static normalize_requirement_name(name)[source]¶

Function to normalize a requirement name per e.g. PEP 503 (where underscores are replaced by hyphens).

New in version 0.9.0.

Return type: str

parse_dependencies(config)[source]¶

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

Format: Array of PEP 508 strings
Core Metadata: Requires-Dist

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.

Format: Table with values of arrays of PEP 508 strings
Core Metadata: Requires-Dist and Provides-Extra

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]]

Changed in version 0.5.0: Extra names with hyphens are now considered valid. If two extra names would normalize to the same string per PEP 685 a warning is emitted. In a future version this will become an error.

Attention

A future version of pyproject-parser will normalize all extra names and write them to METADATA in this normalized form.

parse(config, set_defaults=False)[source]¶

Parse the TOML configuration.

Parameters

config (Dict[str, Any])
set_defaults (bool) – If True, the values in self.defaults and self.factories will be set as defaults for the returned mapping. Default False.

Return type

ProjectDict

pyproject_parser.parsers¶

`pyproject_parser.parsers`¶