API

pyproject_api.__version__

The semantic version of the project.

Frontend

class pyproject_api.Frontend(root, backend_paths, backend_module, backend_obj, requires, reuse_backend=True)[source]

Bases: ABC

Abstract base class for a pyproject frontend.

Create a new frontend.

Parameters:
  • root (Path) – the root path of the project

  • backend_paths (tuple[Path, ...]) – paths to provision as available to import from for the build backend

  • backend_module (str) – the module where the backend lives

  • backend_obj (str | None) – the backend object key (will be lookup up within the backend module)

  • requires (tuple[Requirement, ...]) – build requirements for the backend

  • reuse_backend (bool) – a flag indicating if the communication channel should be kept alive between messages

LEGACY_BUILD_BACKEND = 'setuptools.build_meta:__legacy__'

backend key when the pyproject.toml does not specify it

LEGACY_REQUIRES = (<Requirement('setuptools>=40.8.0')>,)

backend requirements when the pyproject.toml does not specify it

property backend_args

Startup arguments for a backend.

classmethod create_args_from_folder(folder)[source]

Frontend creation arguments from a python project folder (should have a pyproject.toml file per PEP-518).

Parameters:

folder (Path) – the python project folder

Return type:

tuple[Path, tuple[Path, ...], str, str | None, tuple[Requirement, ...], bool]

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:

from pyproject_api import SubprocessFrontend

frontend = SubprocessFrontend(*SubprocessFrontend.create_args_from_folder(project_folder)[:-1])
get_requires_for_build_sdist(config_settings=None)[source]

Get build requirements for a source distribution (per PEP-517).

Parameters:

config_settings (dict[str, Any] | None) – run arguments

Return type:

RequiresBuildSdistResult

Returns:

outcome

property optional_hooks

A dictionary indicating if the optional hook is supported or not.

property backend

Backend key.

get_requires_for_build_wheel(config_settings=None)[source]

Get build requirements for a wheel (per PEP-517).

Parameters:

config_settings (dict[str, Any] | None) – run arguments

Return type:

RequiresBuildWheelResult

Returns:

outcome

get_requires_for_build_editable(config_settings=None)[source]

Get build requirements for an editable wheel build (per PEP-660).

Parameters:

config_settings (dict[str, Any] | None) – run arguments

Return type:

RequiresBuildEditableResult

Returns:

outcome

prepare_metadata_for_build_wheel(metadata_directory, config_settings=None)[source]

Build wheel metadata (per PEP-517).

Parameters:
  • metadata_directory (Path) – where to generate the metadata

  • config_settings (dict[str, Any] | None) – build arguments

Return type:

MetadataForBuildWheelResult | None

Returns:

metadata generation result

prepare_metadata_for_build_editable(metadata_directory, config_settings=None)[source]

Build editable wheel metadata (per PEP-660).

Parameters:
  • metadata_directory (Path) – where to generate the metadata

  • config_settings (dict[str, Any] | None) – build arguments

Return type:

MetadataForBuildEditableResult | None

Returns:

metadata generation result

build_sdist(sdist_directory, config_settings=None)[source]

Build a source distribution (per PEP-517).

Parameters:
  • sdist_directory (Path) – the folder where to build the source distribution

  • config_settings (dict[str, Any] | None) – build arguments

Return type:

SdistResult

Returns:

source distribution build result

build_wheel(wheel_directory, config_settings=None, metadata_directory=None)[source]

Build a wheel file (per PEP-517).

Parameters:
  • wheel_directory (Path) – the folder where to build the wheel

  • config_settings (dict[str, Any] | None) – build arguments

  • metadata_directory (Path | None) – wheel metadata folder

Return type:

WheelResult

Returns:

wheel build result

build_editable(wheel_directory, config_settings=None, metadata_directory=None)[source]

Build an editable wheel file (per PEP-660).

Parameters:
  • wheel_directory (Path) – the folder where to build the editable wheel

  • config_settings (dict[str, Any] | None) – build arguments

  • metadata_directory (Path | None) – wheel metadata folder

Return type:

EditableResult

Returns:

wheel build result

metadata_from_built(metadata_directory, target, config_settings=None)[source]

Create metadata from building the wheel (use when the prepare endpoints are not present or don’t work).

Parameters:
  • metadata_directory (Path) – directory where to put the metadata

  • target (Literal['wheel', 'editable']) – the type of wheel metadata to build

  • config_settings (dict[str, Any] | None) – config settings to pass in to the build endpoint

Return type:

tuple[Path, str, str]

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

Build and metadata directory arguments may be relative to the caller’s current working directory. They are passed to the backend as absolute paths, since the backend runs from the project directory. Result paths retain the spelling of the directory argument. Configuration settings and generic command arguments are passed through unchanged.

Metadata preparation replaces a symlink used as the output directory with a real directory, leaving the link target untouched. Dangling links are replaced too. Paths resolving to the project root or one of its ancestors are still rejected before cleanup.

Metadata preparation clears the output directory before calling the metadata hook. If cleanup fails, the filesystem error propagates and the hook is not called. When extracting metadata from a built wheel, cleanup errors stop extraction after the wheel has been built.

class pyproject_api.OptionalHooks[source]

Bases: TypedDict

A flag indicating if the backend supports the optional hook or not.

Variables:
  • get_requires_for_build_sdist – the backend implements get_requires_for_build_sdist

  • prepare_metadata_for_build_wheel – the backend implements prepare_metadata_for_build_wheel

  • get_requires_for_build_wheel – the backend implements get_requires_for_build_wheel

  • build_editable – the backend implements build_editable

  • get_requires_for_build_editable – the backend implements get_requires_for_build_editable

  • prepare_metadata_for_build_editable – the backend implements prepare_metadata_for_build_editable

get_requires_for_build_sdist
prepare_metadata_for_build_wheel
get_requires_for_build_wheel
build_editable
get_requires_for_build_editable
prepare_metadata_for_build_editable

Exceptions

Backend failed

class pyproject_api.BackendFailed(result, out, err)[source]

Bases: RuntimeError

An error of the build backend.

Parameters:
  • result (dict[str, Any]) – the backend response, with the code, exc_type and exc_msg keys

  • out (str) – standard output collected while running the command

  • err (str) – standard error collected while running the command

out

standard output collected while running the command

err

standard error collected while running the command

code

exit code of the command

exc_type

the type of exception thrown

exc_msg

the string representation of the exception thrown

Results

Build source distribution requires

class pyproject_api.RequiresBuildSdistResult(requires, out, err)[source]

Bases: NamedTuple

Information collected while acquiring the source distribution build dependencies.

Parameters:
  • requires (tuple[Requirement, ...]) – source distribution build dependencies

  • out (str) – backend standard output while acquiring the source distribution build dependencies

  • err (str) – backend standard error while acquiring the source distribution build dependencies

Create new instance of RequiresBuildSdistResult(requires, out, err)

requires

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Build wheel requires

class pyproject_api.RequiresBuildWheelResult(requires, out, err)[source]

Bases: NamedTuple

Information collected while acquiring the wheel build dependencies.

Parameters:
  • requires (tuple[Requirement, ...]) – wheel build dependencies

  • out (str) – backend standard output while acquiring the wheel build dependencies

  • err (str) – backend standard error while acquiring the wheel build dependencies

Create new instance of RequiresBuildWheelResult(requires, out, err)

requires

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Editable requires

class pyproject_api.RequiresBuildEditableResult(requires, out, err)[source]

Bases: NamedTuple

Information collected while acquiring the editable wheel build dependencies.

Parameters:
  • requires (tuple[Requirement, ...]) – editable wheel build dependencies

  • out (str) – backend standard output while acquiring the editable wheel build dependencies

  • err (str) – backend standard error while acquiring the editable wheel build dependencies

Create new instance of RequiresBuildEditableResult(requires, out, err)

requires

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Wheel metadata

class pyproject_api.MetadataForBuildWheelResult(metadata, out, err)[source]

Bases: NamedTuple

Information collected while acquiring the wheel metadata.

Parameters:
  • metadata (Path) – path to the wheel metadata

  • out (str) – backend standard output while generating the wheel metadata

  • err (str) – backend standard error while generating the wheel metadata

Create new instance of MetadataForBuildWheelResult(metadata, out, err)

metadata

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Editable metadata

class pyproject_api.MetadataForBuildEditableResult(metadata, out, err)[source]

Bases: NamedTuple

Information collected while acquiring the editable metadata.

Parameters:
  • metadata (Path) – path to the wheel metadata

  • out (str) – backend standard output while generating the editable wheel metadata

  • err (str) – backend standard error while generating the editable wheel metadata

Create new instance of MetadataForBuildEditableResult(metadata, out, err)

metadata

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Source distribution

class pyproject_api.SdistResult(sdist, out, err)[source]

Bases: NamedTuple

Information collected while building a source distribution.

Parameters:
  • sdist (Path) – path to the built source distribution

  • out (str) – backend standard output while building the source distribution

  • err (str) – backend standard error while building the source distribution

Create new instance of SdistResult(sdist, out, err)

sdist

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Editable

class pyproject_api.EditableResult(wheel, out, err)[source]

Bases: NamedTuple

Information collected while building an editable wheel.

Parameters:
  • wheel (Path) – path to the built wheel artifact

  • out (str) – backend standard output while building the wheel

  • err (str) – backend standard error while building the wheel

Create new instance of EditableResult(wheel, out, err)

wheel

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Wheel

class pyproject_api.WheelResult(wheel, out, err)[source]

Bases: NamedTuple

Information collected while building a wheel.

Parameters:
  • wheel (Path) – path to the built wheel artifact

  • out (str) – backend standard output while building the wheel

  • err (str) – backend standard error while building the wheel

Create new instance of WheelResult(wheel, out, err)

wheel

Alias for field number 0

out

Alias for field number 1

err

Alias for field number 2

Fresh subprocess frontend

class pyproject_api.SubprocessFrontend(root, backend_paths, backend_module, backend_obj, requires)[source]

Bases: Frontend

A frontend that creates fresh subprocess at every call to communicate with the backend.

Variables:

executable – the interpreter that runs the backend in a subprocess

Create a subprocess frontend.

Parameters:
  • root (Path) – the root path to the built project

  • backend_paths (tuple[Path, ...]) – paths that are available on the python path for the backend

  • backend_module (str) – module where the backend is located

  • backend_obj (str | None) – object within the backend module identifying the backend

  • requires (tuple[Requirement, ...]) – seed requirements for the backend

send_cmd(cmd, **kwargs)[source]

Send a command to the backend.

Parameters:
  • cmd (str) – the command to send

  • kwargs (Any) – keyword arguments to the backend

Return type:

tuple[Any, str, str]

Returns:

a tuple of: backend response, standard output text, standard error text