{"library":"pyproject-api","title":"pyproject-api","description":"pyproject-api is a Python library that provides an abstract API for interacting with `pyproject.toml`-based projects. It standardizes the communication with various build backends (like setuptools, Hatchling, Flit) as defined by PEP 517 and PEP 660, allowing tools to build, inspect, and manage Python packages without direct knowledge of the underlying build system. The library is actively maintained by the tox-dev team and is currently at version 1.10.0, with regular releases to support new Python versions and address issues.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/tox-dev/pyproject-api","tags":["packaging","build system","pyproject.toml","PEP 517","PEP 660","build backend"],"install":[{"cmd":"pip install pyproject-api","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"note":"The primary class for interacting with a pyproject.toml based project and its build backend.","symbol":"Frontend","correct":"from pyproject_api import Frontend"},{"note":"Exception raised when the underlying build backend fails.","symbol":"BackendFailed","correct":"from pyproject_api import BackendFailed"}],"quickstart":{"code":"import sys\nfrom pathlib import Path\nimport tempfile\nimport shutil\n\n# Create a temporary project directory\ntemp_dir = Path(tempfile.mkdtemp())\nproject_root = temp_dir / \"my_project\"\nproject_root.mkdir()\n\n# Create a minimal pyproject.toml\npyproject_toml_content = '''\n[build-system]\nrequires = [\"my-dummy-backend\"]\nbuild-backend = \"my_dummy_backend:MyDummyBackend\"\n\n[project]\nname = \"my-example-package\"\nversion = \"0.0.1\"\n'''\n(project_root / \"pyproject.toml\").write_text(pyproject_toml_content)\n\n# Create a dummy build backend module (my_dummy_backend.py)\nbackend_module_content = '''\nfrom pathlib import Path\n\nclass MyDummyBackend:\n    def __init__(self, directory): # pyproject-api passes the project directory\n        self.directory = Path(directory)\n        self.name = \"my-example-package\"\n\n    def get_requires_for_build_wheel(self, config_settings=None):\n        return []\n\n    def build_wheel(self, wheel_directory, config_settings=None, metadata_directory=None):\n        # Simulate building a wheel file\n        wheel_name = f\"{self.name}-0.0.1-py3-none-any.whl\"\n        (Path(wheel_directory) / wheel_name).touch()\n        return wheel_name\n'''\n(project_root / \"my_dummy_backend.py\").write_text(backend_module_content)\n\nfrom pyproject_api import Frontend, BackendFailed\n\nprint(f\"Created temporary project at: {project_root}\")\n\ntry:\n    # Initialize the Frontend to interact with our dummy project\n    # backend_paths is crucial to make 'my_dummy_backend' importable\n    frontend = Frontend(\n        root=project_root,\n        backend_paths=[project_root],\n        backend_module=\"my_dummy_backend\",\n        backend_obj=\"MyDummyBackend\", # The class name to instantiate\n        requires=[], # Our dummy backend doesn't have build requirements itself\n        reuse_backend=False\n    )\n\n    # Get build requirements (should be empty for our dummy backend)\n    build_requirements = frontend.get_requires_for_build_wheel()\n    print(f\"Build requirements reported by backend: {build_requirements.requires}\")\n\n    # Build a wheel\n    build_dir = temp_dir / \"dist\"\n    build_dir.mkdir()\n    print(f\"Attempting to build wheel into: {build_dir}\")\n    wheel_result = frontend.build_wheel(build_dir)\n    print(f\"Successfully built wheel: {wheel_result.path.name}\")\n    print(f\"Wheel file location: {wheel_result.path}\")\n\nexcept BackendFailed as e:\n    print(f\"Backend operation failed: {e.exc_msg}\")\n    print(f\"Backend stdout: {e.out}\")\n    print(f\"Backend stderr: {e.err}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up the temporary directory\n    if temp_dir.exists():\n        shutil.rmtree(temp_dir)\n        print(f\"Cleaned up temporary directory: {temp_dir}\")","lang":"python","description":"This quickstart demonstrates how to use `pyproject_api.Frontend` to programmatically interact with a project structured around `pyproject.toml`. It sets up a minimal project with a dummy build backend, then uses `Frontend` to query build requirements and simulate building a wheel. The `backend_paths` argument is essential for `pyproject-api` to locate and import your custom build backend module."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or higher. For older Python versions, use pyproject-api <1.9.0 for Python 3.9, or pyproject-api <1.8.0 for Python 3.8.","message":"Python 3.9 support was dropped in version 1.10.0. Python 3.8 support was dropped in version 1.9.0. The library now requires Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Always include the necessary build backend in your `pyproject.toml`'s `[build-system] requires` section. If an operation fails with `BackendFailed`, verify the backend's presence and functionality.","message":"pyproject-api provides an API to interact with build backends, but it does not include the build backends themselves. You must ensure that the build backend specified in `pyproject.toml` (e.g., `setuptools`, `hatchling`, `flit_core`) is correctly declared in `build-system.requires` and is installable/provisionable within the environment where `pyproject-api` operates.","severity":"gotcha","affected_versions":"all"},{"fix":"Thoroughly validate your `pyproject.toml` content against PEP specifications (PEP 517, PEP 518, PEP 621) and the requirements of your chosen build backend. Use tools like `validate-pyproject` or `check-wheel-contents` for pre-build validation.","message":"Misconfigured or invalid `pyproject.toml` files can lead to obscure errors, as the issues might originate from the build backend and be re-reported through `pyproject-api` without clear context on the initial problem within the TOML structure itself.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}