{"id":1619,"library":"pep517","title":"PEP 517 Build Frontend","description":"pep517 provides low-level wrappers to interact with Python package build backends that implement PEP 517 hooks. It is primarily used by build frontends like `pip` and `build` to orchestrate the build process (e.g., building source distributions, wheels). The current stable version is 0.13.1, and releases occur as needed to address issues or align with packaging standards, typically not on a strict cadence.","status":"active","version":"0.13.1","language":"en","source_language":"en","source_url":"https://github.com/pypa/pep517","tags":["build-system","packaging","pypa","pep517"],"install":[{"cmd":"pip install pep517","lang":"bash","label":"Install pep517"}],"dependencies":[],"imports":[{"symbol":"Pep517HookCaller","correct":"from pep517.wrappers import Pep517HookCaller"},{"symbol":"BuildBackendException","correct":"from pep517.wrappers import BuildBackendException"}],"quickstart":{"code":"import os\nimport tempfile\nfrom pathlib import Path\nimport shutil\n\nfrom pep517.wrappers import Pep517HookCaller, BuildBackendException\n\n# Create a dummy project directory with a pyproject.toml\n# In a real scenario, this would be an existing project.\nproject_dir = Path(tempfile.mkdtemp())\n\ntry:\n    (project_dir / \"pyproject.toml\").write_text(\"\"\"\n[build-system]\nrequires = [\"setuptools>=61.0.0\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\"\"\")\n    (project_dir / \"src\").mkdir()\n    (project_dir / \"src\" / \"__init__.py\").write_text(\"\")\n    (project_dir / \"src\" / \"my_module.py\").write_text(\"VERSION = '0.1.0'\")\n\n    # Instantiate a Pep517HookCaller to interact with the backend\n    # For setuptools.build_meta, backend_path is typically empty, \n    # meaning it's expected to be importable directly.\n    caller = Pep517HookCaller(\n        source_dir=project_dir,\n        build_backend=\"setuptools.build_meta\",\n        backend_path=[]\n    )\n\n    # Example: Get build requirements for a wheel\n    # config_settings can be an empty dict if no specific settings are needed\n    requires = caller.get_requires_for_build_wheel(config_settings={})\n    print(f\"Build requires for wheel: {requires}\")\n\nexcept BuildBackendException as e:\n    print(f\"Backend error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up temporary directory\n    if project_dir.exists():\n        shutil.rmtree(project_dir)","lang":"python","description":"This quickstart demonstrates how to programmatically use `pep517` to interact with a build backend. It creates a temporary project, defines a `pyproject.toml` using `setuptools.build_meta`, and then uses `Pep517HookCaller` to retrieve the build requirements for a wheel. This illustrates the low-level interaction pattern that build frontends employ."},"warnings":[{"fix":"If you want to build a Python package, use a higher-level tool like `python -m build` (from the `build` library) or `pip install .`.","message":"pep517 is a low-level library designed for build *frontends* (like `pip` or `build`). It is generally not intended for direct use by end-users looking to simply build a Python package.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the required build backend (e.g., `setuptools`, `hatchling`, `flit_core`) is installed in your virtual environment. If the backend is local or in a non-standard location, provide the correct directories in the `backend_path` argument to `Pep517HookCaller`.","message":"The `build-backend` specified in `pyproject.toml` must be importable in the Python environment where `pep517` is executed. Incorrect `backend_path` or an uninstalled backend will lead to `BackendUnavailable` or `BackendFailed` exceptions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the documentation of the specific build backend you are interacting with (e.g., `setuptools`, `hatchling`) to understand which `config_settings` it supports and their expected values.","message":"The `config_settings` dictionary passed to backend hooks (e.g., `build_wheel`, `get_requires_for_build_wheel`) is specific to each build backend. There is no universal standard for these settings, and passing unsupported options can lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}