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

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

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

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

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

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.

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