Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# `pyproject-api`

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

## API

pyproject_api.__version__ = '1.6.1'

  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 (`UnionType`[`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`, `UnionType`[`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
    Return type:

      `str`

    Returns:

      backend key

  property backend_args
    Return type:

      `list`[`str`]

    Returns:

      startup arguments for a backend

  property optional_hooks
    Return type:

      `OptionalHooks`

    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`], `None`]) – 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`], `None`]) – 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`], `None`]) – 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`], `None`]) – build arguments

    Return type:

      `UnionType`[`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`], `None`]) – build arguments

    Return type:

      `UnionType`[`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`], `None`]) – 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`], `None`]) – build arguments

      - metadata_directory (`UnionType`[`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`], `None`]) – build arguments

      - metadata_directory (`UnionType`[`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`], `None`]) – 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