Source code for pyproject_api._frontend

"""Build frontend for PEP-517."""

from __future__ import annotations

import json
import tomllib
from abc import ABC, abstractmethod
from contextlib import contextmanager
from datetime import date, datetime, time
from pathlib import Path
from tempfile import NamedTemporaryFile, TemporaryDirectory
from time import sleep
from typing import TYPE_CHECKING, Any, Final, Literal, NamedTuple, NoReturn, TypeAlias, TypedDict, cast
from zipfile import ZipFile

from packaging.requirements import Requirement

from ._util import ensure_empty_dir

if TYPE_CHECKING:
    from collections.abc import Generator, Iterator


_HERE: Final[Path] = Path(__file__).parent
ConfigSettings = dict[str, Any] | None  # simplint: ignore[missing-from-all]  # used only in this module's annotations
# the backend answers over a JSON protocol, so every value it returns is one of these
JsonValue: TypeAlias = str | int | float | bool | list["JsonValue"] | dict[str, "JsonValue"] | None
# tomllib yields these types for every value in a parsed document
_TomlValue: TypeAlias = str | int | float | bool | datetime | date | time | list["_TomlValue"] | dict[str, "_TomlValue"]


[docs] class OptionalHooks(TypedDict, total=True): """ A flag indicating if the backend supports the optional hook or not. :ivar get_requires_for_build_sdist: the backend implements ``get_requires_for_build_sdist`` :ivar prepare_metadata_for_build_wheel: the backend implements ``prepare_metadata_for_build_wheel`` :ivar get_requires_for_build_wheel: the backend implements ``get_requires_for_build_wheel`` :ivar build_editable: the backend implements ``build_editable`` :ivar get_requires_for_build_editable: the backend implements ``get_requires_for_build_editable`` :ivar prepare_metadata_for_build_editable: the backend implements ``prepare_metadata_for_build_editable`` """ get_requires_for_build_sdist: bool prepare_metadata_for_build_wheel: bool get_requires_for_build_wheel: bool build_editable: bool get_requires_for_build_editable: bool prepare_metadata_for_build_editable: bool
class CmdStatus(ABC): """Tracks a backend command until it finishes, then gives its output.""" @property @abstractmethod def done(self) -> bool: """Truthful when the command finished running.""" raise NotImplementedError @abstractmethod def out_err(self) -> tuple[str, str]: """ Get the standard output and standard error text. :returns: the output and error text """ raise NotImplementedError
[docs] class Frontend(ABC): """Abstract base class for a pyproject frontend.""" #: backend key when the ``pyproject.toml`` does not specify it LEGACY_BUILD_BACKEND: str = "setuptools.build_meta:__legacy__" #: backend requirements when the ``pyproject.toml`` does not specify it LEGACY_REQUIRES: tuple[Requirement, ...] = (Requirement("setuptools >= 40.8.0"),) def __init__( # ruff:ignore[too-many-arguments, too-many-positional-arguments] # public constructor signature self, root: Path, backend_paths: tuple[Path, ...], backend_module: str, backend_obj: str | None, requires: tuple[Requirement, ...], reuse_backend: bool = True, # ruff:ignore[boolean-type-hint-positional-argument, boolean-default-value-positional-argument] # public keyword parameter ) -> None: """ Create a new frontend. :param root: the root path of the project :param backend_paths: paths to provision as available to import from for the build backend :param backend_module: the module where the backend lives :param backend_obj: the backend object key (will be lookup up within the backend module) :param requires: build requirements for the backend :param reuse_backend: a flag indicating if the communication channel should be kept alive between messages """ self._root = root self._backend_paths = backend_paths self._backend_module = backend_module self._backend_obj = backend_obj self.requires: tuple[Requirement, ...] = requires self._reuse_backend = reuse_backend self._optional_hooks: OptionalHooks | None = None @property def backend_args(self) -> list[str]: """Startup arguments for a backend.""" result: list[str] = [str(_HERE / "_backend.py"), str(self._reuse_backend), self._backend_module] if self._backend_obj: result.append(self._backend_obj) return result
[docs] @classmethod def create_args_from_folder( cls, folder: Path, ) -> tuple[Path, tuple[Path, ...], str, str | None, tuple[Requirement, ...], bool]: """ Frontend creation arguments from a python project folder (should have a ``pyproject.toml`` file per PEP-518). :param folder: the python project folder :returns: the frontend creation args :raises ValueError: if ``build-system`` is not a table, one of its keys has a type PEP-518 rules out, or a ``backend-path`` entry does not resolve inside the project (PEP-517 in-tree backends) E.g., to create a frontend from a python project folder: .. code:: python from pyproject_api import SubprocessFrontend frontend = SubprocessFrontend(*SubprocessFrontend.create_args_from_folder(project_folder)[:-1]) """ folder = folder.absolute() py_project_toml = folder / "pyproject.toml" if py_project_toml.exists(): with py_project_toml.open("rb") as file_handler: py_project: dict[str, _TomlValue] = tomllib.load(file_handler) if not isinstance(build_system := py_project.get("build-system", {}), dict): msg = f"build-system must be a table, got {build_system!r}" raise ValueError(msg) if "backend-path" in build_system: backend_paths: tuple[Path, ...] = tuple( _in_tree_path(folder, entry) for entry in _str_list(build_system, "backend-path") ) else: backend_paths = () if "requires" in build_system: requires: tuple[Requirement, ...] = tuple(Requirement(r) for r in _str_list(build_system, "requires")) else: requires = cls.LEGACY_REQUIRES if not isinstance(build_backend := build_system.get("build-backend", cls.LEGACY_BUILD_BACKEND), str): msg = f"build-system.build-backend must be a string, got {build_backend!r}" raise ValueError(msg) else: backend_paths = () requires = cls.LEGACY_REQUIRES build_backend = cls.LEGACY_BUILD_BACKEND paths = build_backend.split(":") backend_module: str = paths[0] backend_obj: str | None = paths[1] if len(paths) > 1 else None return ( # simplint: ignore[long-tuple-return] # preserve plain tuple API folder, backend_paths, backend_module, backend_obj, requires, True, )
[docs] def get_requires_for_build_sdist(self, config_settings: ConfigSettings | None = None) -> RequiresBuildSdistResult: """ Get build requirements for a source distribution (per PEP-517). :param config_settings: run arguments :returns: outcome """ if self.optional_hooks["get_requires_for_build_sdist"]: result, out, err = self._send(cmd="get_requires_for_build_sdist", config_settings=config_settings) else: result, out, err = [], "", "" if not isinstance(result, list) or not all(isinstance(i, str) for i in result): self._unexpected_response("get_requires_for_build_sdist", result, "list of string", out, err) return RequiresBuildSdistResult(tuple(Requirement(r) for r in cast("list[str]", result)), out, err)
@property def optional_hooks(self) -> OptionalHooks: """A dictionary indicating if the optional hook is supported or not.""" if self._optional_hooks is None: result, _, __ = self._send("_optional_hooks") self._optional_hooks = cast("OptionalHooks", result) return self._optional_hooks def _send(self, cmd: str, **kwargs: Path | ConfigSettings) -> _SendResult: with NamedTemporaryFile(prefix=f"pep517_{cmd}-") as result_file_marker: result_file = Path(result_file_marker.name).with_suffix(".json") msg = json.dumps( { "cmd": cmd, "kwargs": {k: (str(v) if isinstance(v, Path) else v) for k, v in kwargs.items()}, "result": str(result_file), }, ) with self._send_msg(cmd, result_file, msg) as status: while not status.done: # pragma: no branch # the wait loop body depends on thread timing sleep(0.001) # wait a bit for things to happen if result_file.exists(): try: with result_file.open("rt") as result_handler: result = json.load(result_handler) finally: result_file.unlink() else: result = { "code": 1, "exc_type": "RuntimeError", "exc_msg": f"Backend response file {result_file} is missing", } out, err = status.out_err() if "return" in result: return _SendResult(result["return"], out, err) raise BackendFailed(result, out, err) @abstractmethod @contextmanager def _send_msg(self, cmd: str, result_file: Path, msg: str) -> Iterator[CmdStatus]: raise NotImplementedError def _unexpected_response( self, cmd: str, got: JsonValue, expected_type: str | type[str], out: str, err: str, ) -> NoReturn: msg = f"{cmd!r} on {self.backend!r} returned {got!r} but expected type {expected_type!r}" raise BackendFailed({"code": None, "exc_type": TypeError.__name__, "exc_msg": msg}, out, err) @property def backend(self) -> str: """Backend key.""" return f"{self._backend_module}{f':{self._backend_obj}' if self._backend_obj else ''}"
[docs] def get_requires_for_build_wheel(self, config_settings: ConfigSettings | None = None) -> RequiresBuildWheelResult: """ Get build requirements for a wheel (per PEP-517). :param config_settings: run arguments :returns: outcome """ if self.optional_hooks["get_requires_for_build_wheel"]: result, out, err = self._send(cmd="get_requires_for_build_wheel", config_settings=config_settings) else: result, out, err = [], "", "" if not isinstance(result, list) or not all(isinstance(i, str) for i in result): self._unexpected_response("get_requires_for_build_wheel", result, "list of string", out, err) return RequiresBuildWheelResult(tuple(Requirement(r) for r in cast("list[str]", result)), out, err)
[docs] def get_requires_for_build_editable( self, config_settings: ConfigSettings | None = None, ) -> RequiresBuildEditableResult: """ Get build requirements for an editable wheel build (per PEP-660). :param config_settings: run arguments :returns: outcome """ if self.optional_hooks["get_requires_for_build_editable"]: result, out, err = self._send(cmd="get_requires_for_build_editable", config_settings=config_settings) else: result, out, err = [], "", "" if not isinstance(result, list) or not all(isinstance(i, str) for i in result): self._unexpected_response("get_requires_for_build_editable", result, "list of string", out, err) return RequiresBuildEditableResult(tuple(Requirement(r) for r in cast("list[str]", result)), out, err)
[docs] def prepare_metadata_for_build_wheel( self, metadata_directory: Path, config_settings: ConfigSettings | None = None, ) -> MetadataForBuildWheelResult | None: """ Build wheel metadata (per PEP-517). :param metadata_directory: where to generate the metadata :param config_settings: build arguments :returns: metadata generation result """ self._check_metadata_dir(metadata_directory) basename: JsonValue = None if self.optional_hooks["prepare_metadata_for_build_wheel"]: basename, out, err = self._send( cmd="prepare_metadata_for_build_wheel", metadata_directory=metadata_directory.absolute(), config_settings=config_settings, ) if basename is None: return None if not isinstance(basename, str): self._unexpected_response("prepare_metadata_for_build_wheel", basename, str, out, err) return MetadataForBuildWheelResult(metadata_directory / basename, out, err)
def _check_metadata_dir(self, metadata_directory: Path) -> None: metadata_path: Final[Path] = metadata_directory.resolve() project_root: Final[Path] = self._root.resolve() if metadata_path == project_root: same_root_message: Final[str] = ( f"the project root and the metadata directory can't be the same {self._root}" ) raise RuntimeError(same_root_message) if metadata_path in project_root.parents: ancestor_message: Final[str] = f"the metadata directory can't contain the project root {self._root}" raise RuntimeError(ancestor_message) if metadata_directory.is_symlink() or metadata_directory.exists(): ensure_empty_dir(metadata_directory) metadata_directory.mkdir(parents=True, exist_ok=True)
[docs] def prepare_metadata_for_build_editable( self, metadata_directory: Path, config_settings: ConfigSettings | None = None, ) -> MetadataForBuildEditableResult | None: """ Build editable wheel metadata (per PEP-660). :param metadata_directory: where to generate the metadata :param config_settings: build arguments :returns: metadata generation result """ self._check_metadata_dir(metadata_directory) basename: JsonValue = None if self.optional_hooks["prepare_metadata_for_build_editable"]: basename, out, err = self._send( cmd="prepare_metadata_for_build_editable", metadata_directory=metadata_directory.absolute(), config_settings=config_settings, ) if basename is None: return None if not isinstance(basename, str): self._unexpected_response("prepare_metadata_for_build_editable", basename, str, out, err) return MetadataForBuildEditableResult(metadata_directory / basename, out, err)
[docs] def build_sdist(self, sdist_directory: Path, config_settings: ConfigSettings | None = None) -> SdistResult: """ Build a source distribution (per PEP-517). :param sdist_directory: the folder where to build the source distribution :param config_settings: build arguments :returns: source distribution build result """ sdist_directory.mkdir(parents=True, exist_ok=True) basename, out, err = self._send( cmd="build_sdist", sdist_directory=sdist_directory.absolute(), config_settings=config_settings, ) if not isinstance(basename, str): self._unexpected_response("build_sdist", basename, str, out, err) return SdistResult(sdist_directory / basename, out, err)
[docs] def build_wheel( self, wheel_directory: Path, config_settings: ConfigSettings | None = None, metadata_directory: Path | None = None, ) -> WheelResult: """ Build a wheel file (per PEP-517). :param wheel_directory: the folder where to build the wheel :param config_settings: build arguments :param metadata_directory: wheel metadata folder :returns: wheel build result """ wheel_directory.mkdir(parents=True, exist_ok=True) basename, out, err = self._send( cmd="build_wheel", wheel_directory=wheel_directory.absolute(), config_settings=config_settings, metadata_directory=None if metadata_directory is None else metadata_directory.absolute(), ) if not isinstance(basename, str): self._unexpected_response("build_wheel", basename, str, out, err) return WheelResult(wheel_directory / basename, out, err)
[docs] def build_editable( self, wheel_directory: Path, config_settings: ConfigSettings | None = None, metadata_directory: Path | None = None, ) -> EditableResult: """ Build an editable wheel file (per PEP-660). :param wheel_directory: the folder where to build the editable wheel :param config_settings: build arguments :param metadata_directory: wheel metadata folder :returns: wheel build result """ wheel_directory.mkdir(parents=True, exist_ok=True) basename, out, err = self._send( cmd="build_editable", wheel_directory=wheel_directory.absolute(), config_settings=config_settings, metadata_directory=None if metadata_directory is None else metadata_directory.absolute(), ) if not isinstance(basename, str): self._unexpected_response("build_editable", basename, str, out, err) return EditableResult(wheel_directory / basename, out, err)
[docs] def metadata_from_built( self, metadata_directory: Path, target: Literal["wheel", "editable"], config_settings: ConfigSettings | None = None, ) -> tuple[Path, str, str]: """ Create metadata from building the wheel (use when the prepare endpoints are not present or don't work). :param metadata_directory: directory where to put the metadata :param target: the type of wheel metadata to build :param config_settings: config settings to pass in to the build endpoint :returns: the metadata directory path, with the standard output and standard error text of the build :raises RuntimeError: if the built wheel is missing or holds no ``.dist-info`` directory """ hook = getattr(self, f"build_{target}") with self._wheel_directory() as wheel_directory: result: EditableResult | WheelResult = hook(wheel_directory, config_settings) wheel = result.wheel if not wheel.exists(): msg = f"missing wheel file return by backed {wheel!r}" raise RuntimeError(msg) out, err = result.out, result.err extract_to = str(metadata_directory) basename = None with ZipFile(str(wheel), "r") as zip_file: for name in zip_file.namelist(): # pragma: no branch # the loop always finishes the archive root = Path(name).parts[0] if not root.endswith(".dist-info"): continue if basename is None: ensure_empty_dir(metadata_directory / root) basename = root zip_file.extract(name, extract_to) if basename is None: # pragma: no branch # the missing-dist-info arm is covered by a separate test msg = f"no .dist-info found inside generated wheel {wheel}" raise RuntimeError(msg) return metadata_directory / basename, out, err # simplint: ignore[long-tuple-return] # preserve tuple API
@contextmanager def _wheel_directory(self) -> Generator[Path, None, None]: # ruff:ignore[no-self-use] # shared with the build helpers that call it with TemporaryDirectory() as wheel_directory: yield Path(wheel_directory)
def _in_tree_path(folder: Path, entry: str) -> Path: path = folder / entry # Python 3.15 on Windows resolves a path containing NUL instead of raising try: inside = "\0" not in entry and not Path(entry).is_absolute() and path.resolve().is_relative_to(folder.resolve()) except (OSError, RuntimeError): # RuntimeError: symlink loop before Python 3.13 inside = False if not inside: msg = f"build-system.backend-path entry {entry!r} must be a relative path inside the project {folder}" raise ValueError(msg) return path def _str_list(build_system: dict[str, _TomlValue], key: str) -> list[str]: if not isinstance(value := build_system[key], list) or not all(isinstance(entry, str) for entry in value): msg = f"build-system.{key} must be a list of strings, got {value!r}" raise ValueError(msg) return value
[docs] class RequiresBuildSdistResult(NamedTuple): """ Information collected while acquiring the source distribution build dependencies. :param requires: source distribution build dependencies :param out: backend standard output while acquiring the source distribution build dependencies :param err: backend standard error while acquiring the source distribution build dependencies """ requires: tuple[Requirement, ...] out: str err: str
class _SendResult(NamedTuple): value: JsonValue out: str err: str
[docs] class BackendFailed(RuntimeError): # ruff:ignore[error-suffix-on-exception-name] # public exception name, kept for users """ An error of the build backend. :param result: the backend response, with the ``code``, ``exc_type`` and ``exc_msg`` keys :param out: standard output collected while running the command :param err: standard error collected while running the command """ def __init__(self, result: dict[str, Any], out: str, err: str) -> None: super().__init__() #: standard output collected while running the command self.out = out #: standard error collected while running the command self.err = err #: exit code of the command self.code: int | None = result.get("code", -2) #: the type of exception thrown self.exc_type: str = result.get("exc_type", "missing Exception type") #: the string representation of the exception thrown self.exc_msg: str = result.get("exc_msg", "missing Exception message") def __reduce__( self, ) -> tuple[ type[BackendFailed], tuple[dict[str, Any], str, str], # simplint: ignore[imprecise-annotation] # public pickle type dict[str, Any], # simplint: ignore[imprecise-annotation] # public pickle type ]: result: dict[str, JsonValue] = {"code": self.code, "exc_type": self.exc_type, "exc_msg": self.exc_msg} return self.__class__, (result, self.out, self.err), self.__dict__ def __str__(self) -> str: return ( f"packaging backend failed{'' if self.code is None else f' (code={self.code})'}, " f"with {self.exc_type}: {self.exc_msg}\n{self.err}{self.out}" ).rstrip() def __repr__(self) -> str: return ( f"{self.__class__.__name__}(" f"result=dict(code={self.code}, exc_type={self.exc_type!r},exc_msg={self.exc_msg!r})," f" out={self.out!r}, err={self.err!r})" )
[docs] class RequiresBuildWheelResult(NamedTuple): """ Information collected while acquiring the wheel build dependencies. :param requires: wheel build dependencies :param out: backend standard output while acquiring the wheel build dependencies :param err: backend standard error while acquiring the wheel build dependencies """ requires: tuple[Requirement, ...] out: str err: str
[docs] class RequiresBuildEditableResult(NamedTuple): """ Information collected while acquiring the editable wheel build dependencies. :param requires: editable wheel build dependencies :param out: backend standard output while acquiring the editable wheel build dependencies :param err: backend standard error while acquiring the editable wheel build dependencies """ requires: tuple[Requirement, ...] out: str err: str
[docs] class MetadataForBuildWheelResult(NamedTuple): """ Information collected while acquiring the wheel metadata. :param metadata: path to the wheel metadata :param out: backend standard output while generating the wheel metadata :param err: backend standard error while generating the wheel metadata """ metadata: Path out: str err: str
[docs] class MetadataForBuildEditableResult(NamedTuple): """ Information collected while acquiring the editable metadata. :param metadata: path to the wheel metadata :param out: backend standard output while generating the editable wheel metadata :param err: backend standard error while generating the editable wheel metadata """ metadata: Path out: str err: str
[docs] class SdistResult(NamedTuple): """ Information collected while building a source distribution. :param sdist: path to the built source distribution :param out: backend standard output while building the source distribution :param err: backend standard error while building the source distribution """ sdist: Path out: str err: str
[docs] class WheelResult(NamedTuple): """ Information collected while building a wheel. :param wheel: path to the built wheel artifact :param out: backend standard output while building the wheel :param err: backend standard error while building the wheel """ wheel: Path out: str err: str
[docs] class EditableResult(NamedTuple): """ Information collected while building an editable wheel. :param wheel: path to the built wheel artifact :param out: backend standard output while building the wheel :param err: backend standard error while building the wheel """ wheel: Path out: str err: str
__all__ = [ "BackendFailed", "CmdStatus", "EditableResult", "Frontend", "MetadataForBuildEditableResult", "MetadataForBuildWheelResult", "OptionalHooks", "RequiresBuildEditableResult", "RequiresBuildSdistResult", "RequiresBuildWheelResult", "SdistResult", "WheelResult", ]