pyproject-api

pyproject-api aims to abstract away interaction with pyproject.toml style projects in a flexible way.

API

pyproject_api.__version__ = '0.1.2.dev15+gf5fff98'

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

Return type:

str

Returns:

backend key

property backend_args

Return type:

list[str]

Returns:

startup arguments for a backend

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

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

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 source distribution (per PEP-517).

Parameters:

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

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

• metadata_directory (Optional[Path]) – wheel metadata folder

Return type:

WheelResult

Returns:

wheel build result

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

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

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

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.

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 (Optional[str]) – 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