{"id":8756,"library":"validate-pyproject","title":"validate-pyproject","description":"validate-pyproject is a Python library and CLI tool designed for validating `pyproject.toml` files against various Python packaging standards (like PEP 517, PEP 518, PEP 621, PEP 639, and PEP 735) using JSON Schema. It is currently at version 0.25 and maintains an active development and release cadence.","status":"active","version":"0.25","language":"en","source_language":"en","source_url":"https://github.com/abravalheri/validate-pyproject","tags":["pyproject.toml","validation","json-schema","packaging","pep","cli"],"install":[{"cmd":"pip install validate-pyproject","lang":"bash","label":"Minimal Installation"},{"cmd":"pip install 'validate-pyproject[all]'","lang":"bash","label":"Full Features (includes tomli, packaging, trove-classifiers)"}],"dependencies":[{"reason":"Used for parsing TOML files (for Python < 3.11).","package":"tomli","optional":true},{"reason":"Used for validating aspects of PEP 621, required for full validation.","package":"packaging","optional":true},{"reason":"Used for validating project classifiers, can be bypassed by setting `NO_NETWORK` or `VALIDATE_PYPROJECT_NO_NETWORK` environment variables. ","package":"trove-classifiers","optional":true},{"reason":"Underlying JSON Schema validation engine.","package":"fastjsonschema","optional":false}],"imports":[{"note":"Main class for programmatic validation.","symbol":"api.Validator","correct":"from validate_pyproject import api"},{"note":"Exception raised for validation failures.","symbol":"errors.ValidationError","correct":"from validate_pyproject import errors"},{"note":"Entry point for the command-line interface, typically not imported directly in user code but executed via `validate-pyproject` command.","symbol":"cli.main","correct":"from validate_pyproject import cli"}],"quickstart":{"code":"import tomli\nfrom validate_pyproject import api, errors\nimport os\n\n# Example pyproject.toml content\nPYPROJECT_TOML_CONTENT = '''\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"my-package\"\nversion = \"1.0.0\"\ndescription = \"A simple Python package\"\nrequires-python = \">=3.8\"\nkeywords = [\"packaging\", \"example\"]\nclassifiers = [\n    \"Programming Language :: Python :: 3\",\n    \"License :: OSI Approved :: MIT License\",\n    \"Operating System :: OS Independent\",\n]\nauthors = [\n    {name = \"Example Author\", email = \"author@example.com\"},\n]\nmaintainers = [\n    {name = \"Example Maintainer\", email = \"maintainer@example.com\"},\n]\n'''\n\n# Parse the TOML string into a dictionary\npyproject_as_dict = tomli.loads(PYPROJECT_TOML_CONTENT)\n\n# Instantiate the validator (can be configured with extra schemas or plugins)\nvalidator = api.Validator()\n\ntry:\n    # Perform the validation\n    validator(pyproject_as_dict)\n    print(\"pyproject.toml is valid!\")\nexcept errors.ValidationError as ex:\n    print(f\"Invalid pyproject.toml: {ex.message}\")\n    # More detailed errors can be accessed via ex.details\n    for error in ex.details:\n        print(f\"  - {error.message} at {error.json_path}\")","lang":"python","description":"This example demonstrates how to programmatically validate a `pyproject.toml` file content using `validate-pyproject`. It uses `tomli` to parse the TOML string into a Python dictionary, then instantiates `api.Validator` to perform the checks."},"warnings":[{"fix":"If you were relying on the `tests` extra or `docs/requirements.txt` for dependency management, you'll need to update your CI/CD configurations or local setups to use `dependency-groups`. For general use, the `[all]` extra is recommended for full features.","message":"Starting from `v0.24`, the way `validate-pyproject` handles test and documentation dependencies changed. It no longer communicates these via `tests` or `docs/requirements.txt` files, adopting `dependency-groups` instead.","severity":"breaking","affected_versions":">=0.24"},{"fix":"Be aware that the validation process is now non-mutating. If your application previously relied on side effects from the validation (e.g., defaults being added to the dictionary), you will need to adjust your logic to handle the original, un-modified input.","message":"In `v0.22`, a change was introduced to prevent the validator from injecting default values or modifying the input dictionary in-place. This ensures that the original `pyproject.toml` data structure remains unaltered during validation.","severity":"gotcha","affected_versions":">=0.22"},{"fix":"To prevent network access, either install `validate-pyproject[all]` or set the `NO_NETWORK` or `VALIDATE_PYPROJECT_NO_NETWORK` environment variable to any value (e.g., `export VALIDATE_PYPROJECT_NO_NETWORK=1`).","message":"If `trove-classifiers` is not installed (e.g., using a minimal installation without `[all]` extra), `validate-pyproject` will attempt to download a list of valid classifiers from PyPI. This can lead to network requests during validation.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to `v0.25` or newer to benefit from fixes related to 'broken store loading if properties is nested' and 'more integer types' issues.","message":"Earlier versions (prior to `v0.25`) could have issues with nested properties in schema stores or incorrect handling of integer types, leading to validation failures for valid `pyproject.toml` files.","severity":"gotcha","affected_versions":"<0.25"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Review the error message details (`ex.message`, `ex.details` if using the API) to identify the specific validation failure. Consult the official `pyproject.toml` specifications (PEPs like 621) or `validate-pyproject` documentation for schema requirements. Example: `[project]` table might be missing `name` or `version`.","cause":"The `pyproject.toml` file contains data that does not conform to the expected JSON Schema for Python packaging metadata (e.g., missing required fields, incorrect types, invalid values).","error":"validate_pyproject.errors.ValidationError: Invalid Document: ..."},{"fix":"Install `validate-pyproject` with the `[all]` extra: `pip install 'validate-pyproject[all]'`. This ensures all necessary optional dependencies are included for full validation capabilities.","cause":"The `tomli` package (or `packaging`, `trove-classifiers`) is a conditional dependency for `validate-pyproject`'s full functionality. If you installed `validate-pyproject` without the `[all]` extra, these might be missing for Python versions that require them (e.g., `tomli` for Python < 3.11).","error":"ImportError: cannot import name 'tomli' from 'validate_pyproject.api' (or similar for other dependencies)"},{"fix":"Ensure your virtual environment is activated, or if installed via `pipx`, run `pipx ensurepath` to add pipx-managed executables to your PATH. Alternatively, you can run it directly: `python -m validate_pyproject.cli --help`.","cause":"The `validate-pyproject` CLI tool is not in your system's PATH, likely because it was installed into a virtual environment that isn't activated, or `pipx` was used without linking the executables globally.","error":"validate-pyproject --help\n... Command 'validate-pyproject' not found ..."}]}