API

pyproject_api.__version__ = '1.9.0'

semantic version of the project

Frontend

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

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')>, <Requirement('wheel')>)

backend requirements when the pyproject.toml does not specify it

classmethod create_args_from_folder(folder)

Frontend creation arguments from a python project folder (thould have a pypyproject.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

E.g., to create a frontend from a python project folder:

frontend = Frontend(*Frontend.create_args_from_folder(project_folder))

property backend

Returns:

backend key

property backend_args

Returns:

startup arguments for a backend

property optional_hooks

Returns:

a dictionary indicating if the optional hook is supported or not

get_requires_for_build_sdist(config_settings=None)

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

Parameters:

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

Return type:

RequiresBuildSdistResult

Returns:

outcome

get_requires_for_build_wheel(config_settings=None)

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

Parameters:

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

Return type:

RequiresBuildWheelResult

Returns:

outcome

get_requires_for_build_editable(config_settings=None)

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

Parameters:

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

Return type:

RequiresBuildEditableResult

Returns:

outcome

prepare_metadata_for_build_wheel(metadata_directory, config_settings=None)

Build wheel metadata (per PEP-517).

Parameters:

• metadata_directory (Path) – where to generate the metadata

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

Return type:

MetadataForBuildWheelResult | None

Returns:

metadata generation result

prepare_metadata_for_build_editable(metadata_directory, config_settings=None)

Build editable wheel metadata (per PEP-660).

Parameters:

• metadata_directory (Path) – where to generate the metadata

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

Return type:

MetadataForBuildEditableResult | None

Returns:

metadata generation result

build_sdist(sdist_directory, config_settings=None)

Build a source distribution (per PEP-517).

Parameters:

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

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

Return type:

SdistResult

Returns:

source distribution build result

build_wheel(wheel_directory, config_settings=None, metadata_directory=None)

Build a wheel file (per PEP-517).

Parameters:

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

• config_settings (Optional[dict[str, Any]]) – 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)

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

Parameters:

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

• config_settings (Optional[dict[str, Any]]) – 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)

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 (Optional[dict[str, Any]]) – config settings to pass in to the build endpoint

Return type:

tuple[Path, str, str]

Returns:

class pyproject_api.OptionalHooks

Bases: TypedDict

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

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)

Bases: RuntimeError

An error of the build backend.

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)

Bases: NamedTuple

Information collected while acquiring the source distribution build dependencies.

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

requires

wheel build dependencies

out

backend standard output while acquiring the source distribution build dependencies

err

backend standard output while acquiring the source distribution build dependencies

Build wheel requires

class pyproject_api.RequiresBuildWheelResult(requires, out, err)

Bases: NamedTuple

Information collected while acquiring the wheel build dependencies.

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

requires

wheel build dependencies

out

backend standard output while acquiring the wheel build dependencies

err

backend standard error while acquiring the wheel build dependencies

Editable requires

class pyproject_api.RequiresBuildEditableResult(requires, out, err)

Bases: NamedTuple

Information collected while acquiring the wheel build dependencies.

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

requires

editable wheel build dependencies

out

backend standard output while acquiring the editable wheel build dependencies

err

backend standard error while acquiring the editable wheel build dependencies

Wheel metadata

class pyproject_api.MetadataForBuildWheelResult(metadata, out, err)

Bases: NamedTuple

Information collected while acquiring the wheel metadata.

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

metadata

path to the wheel metadata

out

backend standard output while generating the wheel metadata

err

backend standard output while generating the wheel metadata

Editable metadata

class pyproject_api.MetadataForBuildEditableResult(metadata, out, err)

Bases: NamedTuple

Information collected while acquiring the editable metadata.

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

metadata

path to the wheel metadata

out

backend standard output while generating the editable wheel metadata

err

backend standard output while generating the editable wheel metadata

Source distribution

class pyproject_api.SdistResult(sdist, out, err)

Bases: NamedTuple

Information collected while building a source distribution.

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

sdist

path to the built source distribution

out

backend standard output while building the source distribution

err

backend standard output while building the source distribution

Editable

class pyproject_api.EditableResult(wheel, out, err)

Bases: NamedTuple

Information collected while building an editable wheel.

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

wheel

path to the built wheel artifact

out

backend standard output while building the wheel

err

backend standard error while building the wheel

Wheel

class pyproject_api.WheelResult(wheel, out, err)

Bases: NamedTuple

Information collected while building a wheel.

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

wheel

path to the built wheel artifact

out

backend standard output while building the wheel

err

backend standard error while building the wheel

Fresh subprocess frontend

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

Bases: Frontend

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

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)

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