PEP 517 Build Frontend

0.13.1 · active · verified Thu Apr 09

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.

Warnings

gotcha 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.
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 .`.
gotcha 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.
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`.
gotcha 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.
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.

Install

pip install pep517 Install pep517

Imports

Pep517HookCaller

from pep517.wrappers import Pep517HookCaller

BuildBackendException

from pep517.wrappers import BuildBackendException

Quickstart

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.

import os
import tempfile
from pathlib import Path
import shutil

from pep517.wrappers import Pep517HookCaller, BuildBackendException

# Create a dummy project directory with a pyproject.toml
# In a real scenario, this would be an existing project.
project_dir = Path(tempfile.mkdtemp())

try:
    (project_dir / "pyproject.toml").write_text("""
[build-system]
requires = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"
""")
    (project_dir / "src").mkdir()
    (project_dir / "src" / "__init__.py").write_text("")
    (project_dir / "src" / "my_module.py").write_text("VERSION = '0.1.0'")

    # Instantiate a Pep517HookCaller to interact with the backend
    # For setuptools.build_meta, backend_path is typically empty, 
    # meaning it's expected to be importable directly.
    caller = Pep517HookCaller(
        source_dir=project_dir,
        build_backend="setuptools.build_meta",
        backend_path=[]
    )

    # Example: Get build requirements for a wheel
    # config_settings can be an empty dict if no specific settings are needed
    requires = caller.get_requires_for_build_wheel(config_settings={})
    print(f"Build requires for wheel: {requires}")

except BuildBackendException as e:
    print(f"Backend error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    # Clean up temporary directory
    if project_dir.exists():
        shutil.rmtree(project_dir)

view raw JSON →