This class can read and write metadata files complying with any of the defined versions: 1.0 (PEP 241), 1.1 (PEP 314) and 1.2 (PEP 345). It implements methods to parse Metadata files and write them, and a mapping interface to its contents.
The PEP 345 implementation supports the micro-language for the environment markers, and displays warnings when versions that are supposed to be PEP 386-compliant are violating the specification.
The Metadata class can be instantiated with the path of the metadata file, and provides a dict-like interface to the values:
>>> from packaging.metadata import Metadata
>>> metadata = Metadata('PKG-INFO')
>>> metadata.keys()[:5]
('Metadata-Version', 'Name', 'Version', 'Platform', 'Supported-Platform')
>>> metadata['Name']
'CLVault'
>>> metadata['Version']
'0.5'
>>> 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. Metadata 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 Metadata
>>> metadata = Metadata('PKG-INFO', platform_dependent=True)
>>> metadata['Requires-Dist']
['Sphinx']
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 Metadata
>>> context = {'sys.platform': 'win32'}
>>> metadata = Metadata('PKG-INFO', platform_dependent=True,
... execution_context=context)
...
>>> metadata['Requires-Dist'] = ["pywin32; sys.platform == 'win32'",
... "Sphinx"]
...
>>> metadata['Requires-Dist']
['pywin32', 'Sphinx']
Writing metadata can be done using the write method:
>>> 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 PKG_INFO_PREFERRED_VERSION. It is set by default to 1.0, the most widespread version.
Some fields in PEP 345 have to comply with the version number specification defined in PEP 386. When they don’t comply, a warning is emitted:
>>> from packaging.metadata import Metadata
>>> metadata = Metadata()
>>> metadata['Requires-Dist'] = ['Funky (Groovie)']
"Funky (Groovie)" is not a valid predicate
>>> metadata['Requires-Dist'] = ['Funky (1.2)']
See also packaging.version.
This is an implementation of environment markers as defined in PEP 345. It is used for some metadata fields.
Interpret a marker and return a boolean result depending on the environment. Example:
>>> interpret("python_version > '1.0'")
True