{"library":"pyproject-metadata","title":"pyproject-metadata","description":"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.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/pypa/pyproject-metadata","tags":["packaging","metadata","PEP 621","pyproject.toml","validation"],"install":[{"cmd":"pip install pyproject-metadata","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Used for canonicalizing license expressions (METADATA 2.4+).","package":"packaging","optional":true}],"imports":[{"note":"The main class is directly importable from the top-level package.","wrong":"from pyproject_metadata.pyproject_metadata import StandardMetadata","symbol":"StandardMetadata","correct":"from pyproject_metadata import StandardMetadata"},{"note":"Specific errors are available from the `errors` submodule.","symbol":"ExtraKeyWarning","correct":"from pyproject_metadata.errors import ExtraKeyWarning"}],"quickstart":{"code":"import tomli\nfrom pyproject_metadata import StandardMetadata\n\n# Example pyproject.toml [project] data as a Python dictionary\n# In a real scenario, you'd load this from a pyproject.toml file using a TOML parser like 'tomli'\nproject_data = {\n    \"name\": \"my-project\",\n    \"version\": \"0.1.0\",\n    \"description\": \"A short description\",\n    \"requires-python\": \">=3.8\",\n    \"dependencies\": [\n        \"requests~=2.28\",\n        \"tomli>=1.1.0; python_version < \\\"3.11\\\"\"\n    ],\n    \"authors\": [\n        {\"name\": \"Your Name\", \"email\": \"your.email@example.com\"}\n    ],\n    \"license\": {\"file\": \"LICENSE\"},\n    \"readme\": \"README.md\",\n    \"classifiers\": [\n        \"Programming Language :: Python :: 3\",\n        \"License :: OSI Approved :: MIT License\"\n    ],\n    \"urls\": {\n        \"Homepage\": \"https://github.com/my-project\",\n        \"Bug Tracker\": \"https://github.com/my-project/issues\"\n    }\n}\n\n# Validate the project metadata\ntry:\n    metadata = StandardMetadata.from_pyproject(project_data, allow_extra_keys=False)\n\n    # Access validated fields\n    print(f\"Project Name: {metadata.name}\")\n    print(f\"Project Version: {metadata.version}\")\n    print(f\"Requires Python: {metadata.requires_python}\")\n    print(f\"Dependencies: {metadata.dependencies}\")\n\n    # Generate PEP 643-compliant Core Metadata (e.g., PKG-INFO content)\n    pkg_info = metadata.as_rfc822()\n    print(\"\\n--- Generated PKG-INFO ---\")\n    print(str(pkg_info))\n\nexcept Exception as e:\n    print(f\"Error validating metadata: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always parse your `pyproject.toml` into a dictionary using a TOML parser before passing it to `StandardMetadata.from_pyproject`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Integrate `packaging.licenses.canonicalize_license_expression` or a similar SPDX validation tool into your workflow for robust license field handling.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (by PEP 621 compliance)"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}