"""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)
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 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)
@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 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",
]