Metadata#

Both source distributions and binary distributions (_sdists_ and _wheels_, respectively) contain files recording the core metadata for the distribution. This information is used for everything from recording the name of the distribution to the installation dependencies.

Usage#

>>> from packaging.metadata import parse_email
>>> metadata = "Metadata-Version: 2.3\nName: packaging\nVersion: 24.0"
>>> raw, unparsed = parse_email(metadata)
>>> raw["metadata_version"]
'2.3'
>>> raw["name"]
'packaging'
>>> raw["version"]
'24.0'
>>> from packaging.metadata import Metadata
>>> parsed = Metadata.from_raw(raw)
>>> parsed.name
'packaging'
>>> parsed.version
<Version('24.0')>

Reference#

High Level Interface#

class packaging.metadata.Metadata#

Representation of distribution metadata.

Compared to RawMetadata, this class provides objects representing metadata fields instead of only using built-in types. Any invalid metadata will cause InvalidMetadata to be raised (with a __cause__ attribute as appropriate).

classmethod from_raw(data, *, validate=True)#

Create an instance from RawMetadata.

If validate is true, all metadata will be validated. All exceptions related to validation will be gathered and raised as an ExceptionGroup.

Parameters:

data (RawMetadata) –
validate (bool) –

Return type:

Metadata

classmethod from_email(data, *, validate=True)#

Parse metadata from email headers.

If validate is true, the metadata will be validated. All exceptions related to validation will be gathered and raised as an ExceptionGroup.

Parameters:

data (bytes | str) –
validate (bool) –

Return type:

Metadata

metadata_version: _Validator[_MetadataVersion]#: Metadata-Version (required; validated to be a valid metadata version)

name: _Validator[str]#: Name (required; validated using canonicalize_name() and its validate parameter)

version: _Validator[version_module.Version]#: Version (required)

dynamic: _Validator[list[str] | None]#: Dynamic (multiple use) (validated against core metadata field names and lowercased)

platforms: _Validator[list[str] | None]#: Platform (multiple use)

supported_platforms: _Validator[list[str] | None]#: Supported-Platform (multiple use)

summary: _Validator[str | None]#: Summary (validated to contain no newlines)

description: _Validator[str | None]#: Description

description_content_type: _Validator[str | None]#: Description-Content-Type (validated)

keywords: _Validator[list[str] | None]#: Keywords

home_page: _Validator[str | None]#: Home-page

download_url: _Validator[str | None]#: Download-URL

author: _Validator[str | None]#: Author

author_email: _Validator[str | None]#: Author-email

maintainer: _Validator[str | None]#: Maintainer

maintainer_email: _Validator[str | None]#: Maintainer-email

license: _Validator[str | None]#: License

classifiers: _Validator[list[str] | None]#: Classifier (multiple use)

requires_dist: _Validator[list[requirements.Requirement] | None]#: Requires-Dist (multiple use)

requires_python: _Validator[specifiers.SpecifierSet | None]#: Requires-Python

requires_external: _Validator[list[str] | None]#: Requires-External (multiple use)

project_urls: _Validator[dict[str, str] | None]#: Project-URL (multiple-use)

provides_extra: _Validator[list[utils.NormalizedName] | None]#: Provides-Extra (multiple use)

provides_dist: _Validator[list[str] | None]#: Provides-Dist (multiple use)

obsoletes_dist: _Validator[list[str] | None]#: Obsoletes-Dist (multiple use)

requires: _Validator[list[str] | None]#: Requires (deprecated)

provides: _Validator[list[str] | None]#: Provides (deprecated)

obsoletes: _Validator[list[str] | None]#: Obsoletes (deprecated)

Low Level Interface#

class packaging.metadata.RawMetadata#

A dictionary of raw core metadata.

Each field in core metadata maps to a key of this dictionary (when data is provided). The key is lower-case and underscores are used instead of dashes compared to the equivalent core metadata field. Any core metadata field that can be specified multiple times or can hold multiple values in a single field have a key with a plural name. See Metadata whose attributes match the keys of this dictionary.

Core metadata fields that can be specified multiple times are stored as a list or dict depending on which is appropriate for the field. Any fields which hold multiple values in a single field are stored as a list.

packaging.metadata.parse_email(data)#

Parse a distribution’s metadata stored as email headers (e.g. from METADATA).

This function returns a two-item tuple of dicts. The first dict is of recognized fields from the core metadata specification. Fields that can be parsed and translated into Python’s built-in types are converted appropriately. All other fields are left as-is. Fields that are allowed to appear multiple times are stored as lists.

The second dict contains all other fields from the metadata. This includes any unrecognized fields. It also includes any fields which are expected to be parsed into a built-in type but were not formatted appropriately. Finally, any fields that are expected to appear only once but are repeated are included in this dict.

Parameters:: data (bytes | str) –
Return type:: tuple[RawMetadata, dict[str, list[str]]]

Exceptions#

class packaging.metadata.InvalidMetadata#

A metadata field contains invalid data.

__init__(field, message)#

Parameters:

field (str) –
message (str) –

Return type:

None

field: str#: The name of the field that contains invalid data.

class packaging.metadata.ExceptionGroup#

A minimal implementation of ExceptionGroup from Python 3.11.

If ExceptionGroup is already defined by Python itself, that version is used instead.

__init__(message, exceptions)#

Parameters:

message (str) –
exceptions (list[Exception]) –

Return type:

None