packaging_cpython / Doc / packaging / developer / packaging.metadata.rst


Packaging provides a :class:`~packaging.metadata.DistributionMetadata` class that can read and write metadata files. This class is compatible with all metadata versions:

The PEP 345 implementation supports the micro-language for the environment markers, and displays warnings when versions that are supposed to be PEP 386 are violating the scheme.

Reading metadata

The :class:`~packaging.metadata.DistributionMetadata` class can be instantiated with the path of the metadata file, and provides a dict-like interface to the values:

>>> from packaging.metadata import DistributionMetadata
>>> metadata = DistributionMetadata('PKG-INFO')
>>> metadata.keys()[:5]
('Metadata-Version', 'Name', 'Version', 'Platform', 'Supported-Platform')
>>> metadata['Name']
>>> metadata['Version']
>>> metadata['Requires-Dist']
["pywin32; sys.platform == 'win32'", "Sphinx"]

The fields that support environment markers can be automatically ignored if the object is instantiated using the platform_dependent option. :class:`~packaging.metadata.DistributionMetadata` will interpret in this case the markers and will automatically remove the fields that are not compliant with the running environment. Here's an example under Mac OS X. The win32 dependency we saw earlier is ignored:

>>> from packaging.metadata import DistributionMetadata
>>> metadata = DistributionMetadata('PKG-INFO', platform_dependent=True)
>>> metadata['Requires-Dist']

If you want to provide your own execution context, let's say to test the metadata under a particular environment that is not the current environment, you can provide your own values in the execution_context option, which is the dict that may contain one or more keys of the context the micro-language expects.

Here's an example, simulating a win32 environment:

>>> from packaging.metadata import DistributionMetadata
>>> context = {'sys.platform': 'win32'}
>>> metadata = DistributionMetadata('PKG-INFO', platform_dependent=True,
...                                 execution_context=context)
>>> metadata['Requires-Dist'] = ["pywin32; sys.platform == 'win32'",
...                              "Sphinx"]
>>> metadata['Requires-Dist']
['pywin32', 'Sphinx']

Writing metadata

Writing metadata can be done using the write API:

>>> metadata.write('/to/my/PKG-INFO')

The class will pick the best version for the metadata, depending on the values provided. If all the values provided exist in all versions, the class will use :attr:`metadata.PKG_INFO_PREFERRED_VERSION`. It is set by default to 1.0.

Conflict checking and best version

Some fields in PEP 345 have to follow a version scheme in their versions predicate. When the scheme is violated, a warning is emitted:

>>> from packaging.metadata import DistributionMetadata
>>> metadata = DistributionMetadata()
>>> metadata['Requires-Dist'] = ['Funky (Groovie)']
"Funky (Groovie)" is not a valid predicate
>>> metadata['Requires-Dist'] = ['Funky (1.2)']