pyproject_parser.parsers
¶
TOML configuration parsers.
Classes:
Abstract base class for TOML configuration parsers which have required keys. |
|
Parser for the build-system table table from |
|
Parser for PEP 621 metadata from |
-
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 aSequence
and not astr
, otherwise raise an error with a helpful message.
-
class
BuildSystemParser
[source]¶ Bases:
RequiredKeysConfigParser
Parser for the build-system table table from
pyproject.toml
.Methods:
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
-
parse_requires
(config)[source]¶ Parse the requires key.
- Parameters
config (
Dict
[str
,Any
]) – The unparsed TOML config for the build-system table.- Return type
-
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
-
parse
(config, set_defaults=False)[source]¶ Parse the TOML configuration.
- Parameters
set_defaults (
bool
) – IfTrue
, the values inself.defaults
andself.factories
will be set as defaults for the returned mapping. DefaultFalse
.
- Return type
-
static
-
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.
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.
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
-
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
-
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
-
static
parse_readme
(config)[source]¶ Parse the readme key, giving the full description of the project (i.e. the README).
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 thefile
. Tools MAY support other encodings if they choose to.
The
file
andtext
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
-
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
-
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
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
andemail
. 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
andname
are provided, the value goes in Author-email. The value should be formatted as{name} <{email}>
(with appropriate quoting, e.g. usingemail.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"
-
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
andemail
. 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
andname
are provided, the value goes in Maintainer-email, with the format{name} <{email}>
(with appropriate quoting, e.g. usingemail.headerregistry.Address
).Multiple values should be separated by commas.
-
parse_keywords
(config)[source]¶ Parse the keywords key, giving the keywords for the project.
Example:
[project] keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
-
parse_classifiers
(config)[source]¶ Parse the classifiers key, giving the trove classifiers which apply to the project.
Core Metadata: Classifiers
Example:
[project] classifiers = [ "Development Status :: 4 - Beta", "Programming Language :: Python" ]
-
parse_urls
(config)[source]¶ Parse the urls table.
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"
-
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"
-
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"
-
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
orgui_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"
-
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
-
parse_dependencies
(config)[source]¶ Parse the dependencies key, giving the dependencies of the project.
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
-
parse_optional_dependencies
(config)[source]¶ Parse the optional-dependencies table, giving the optional dependencies of the project.
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
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
set_defaults (
bool
) – IfTrue
, the values inself.defaults
andself.factories
will be set as defaults for the returned mapping. DefaultFalse
.
- Return type
-
static