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)[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')>, <Requirement('wheel')>)¶: backend requirements when the pyproject.toml does not specify it

classmethod create_args_from_folder(folder)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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

Return type:

tuple[Path, str, str]

Returns:

class pyproject_api.OptionalHooks[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[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