pyproject-metadata

0.11.0 · active · verified Sun Apr 05

pyproject-metadata is a Python library that provides a dataclass for parsing and validating project metadata according to PEP 621. It takes an already parsed Python dictionary (representing the `[project]` table from `pyproject.toml`) and validates it against the PEP 621 specification, subsequently generating PEP 643-compliant metadata (e.g., PKG-INFO). The current version is 0.11.0, and it generally follows a release cadence tied to advancements in Python packaging standards.

Warnings

gotcha pyproject-metadata does NOT parse `pyproject.toml` files directly. It expects a pre-parsed Python dictionary corresponding to the `[project]` table. You must use a separate TOML parser (e.g., `tomli` for Python < 3.11 or `tomllib` for Python 3.11+) to read the `.toml` file first.
Fix: Always parse your `pyproject.toml` into a dictionary using a TOML parser before passing it to `StandardMetadata.from_pyproject`.
gotcha By default, extra (non-standard) fields in the `[project]` table will issue a `pyproject_metadata.errors.ExtraKeyWarning`. If unhandled, this might be unexpected. You can configure this behavior during instantiation.
Fix: Pass `allow_extra_keys=True` to ignore extra keys, or `allow_extra_keys=False` to raise a hard error for any extra keys, when calling `StandardMetadata.from_pyproject`.
gotcha When using `project.license` as a string (representing an SPDX expression) or `project.license-files`, it's recommended to additionally validate and normalize the license expression using a dedicated tool, such as `packaging.licenses.canonicalize_license_expression` (requires `packaging` 24.2+), as `pyproject-metadata` itself does not perform full SPDX validation.
Fix: Integrate `packaging.licenses.canonicalize_license_expression` or a similar SPDX validation tool into your workflow for robust license field handling.
breaking The `project.dynamic` field requires careful handling by build backends. If a field is listed in `dynamic` but also specified statically, `pyproject-metadata` (following PEP 621) will raise an error. Also, build backends *must* provide data for dynamic fields and *must* raise an error if they fail to do so.
Fix: Ensure that any fields listed in `dynamic` are *not* statically defined. Build backends must be prepared to dynamically provide the data for these fields or report an error if they cannot.

Install

pip install pyproject-metadata PyPI

Imports

StandardMetadata
```
from pyproject_metadata import StandardMetadata
```
The main class is directly importable from the top-level package.
ExtraKeyWarning
```
from pyproject_metadata.errors import ExtraKeyWarning
```
Specific errors are available from the `errors` submodule.

Quickstart

This quickstart demonstrates how to use `pyproject-metadata` to validate a Python dictionary representing `pyproject.toml`'s `[project]` table and then generate a PEP 643-compliant PKG-INFO string. It highlights the use of `StandardMetadata.from_pyproject` for validation and `as_rfc822` for output. Note that `tomli` (or another TOML parser) is needed to initially parse a `pyproject.toml` file into a dictionary.

import tomli
from pyproject_metadata import StandardMetadata

# Example pyproject.toml [project] data as a Python dictionary
# In a real scenario, you'd load this from a pyproject.toml file using a TOML parser like 'tomli'
project_data = {
    "name": "my-project",
    "version": "0.1.0",
    "description": "A short description",
    "requires-python": ">=3.8",
    "dependencies": [
        "requests~=2.28",
        "tomli>=1.1.0; python_version < \"3.11\""
    ],
    "authors": [
        {"name": "Your Name", "email": "your.email@example.com"}
    ],
    "license": {"file": "LICENSE"},
    "readme": "README.md",
    "classifiers": [
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License"
    ],
    "urls": {
        "Homepage": "https://github.com/my-project",
        "Bug Tracker": "https://github.com/my-project/issues"
    }
}

# Validate the project metadata
try:
    metadata = StandardMetadata.from_pyproject(project_data, allow_extra_keys=False)

    # Access validated fields
    print(f"Project Name: {metadata.name}")
    print(f"Project Version: {metadata.version}")
    print(f"Requires Python: {metadata.requires_python}")
    print(f"Dependencies: {metadata.dependencies}")

    # Generate PEP 643-compliant Core Metadata (e.g., PKG-INFO content)
    pkg_info = metadata.as_rfc822()
    print("\n--- Generated PKG-INFO ---")
    print(str(pkg_info))

except Exception as e:
    print(f"Error validating metadata: {e}")

view raw JSON →