Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# API Documentation

## `build` module

build - A simple, correct Python build frontend

exception build.BuildBackendException(exception, description=None, exc_info=(None, None, None))

  Bases: `Exception`

  Exception raised when a backend operation fails.

exception build.BuildException

  Bases: `Exception`

  Exception raised by `build.ProjectBuilder`.

exception build.BuildSystemTableValidationError

  Bases: `BuildException`

  Exception raised when the `[build-system]` table in pyproject.toml is invalid.

exception build.FailedProcessError(exception, description)

  Bases: `Exception`

  Exception raised when a setup or preparation operation fails.

class build.ProjectBuilder(source_dir, python_executable='/usr/bin/python3.12', runner=<function default_subprocess_runner>)

  Bases: `object`

  The PEP 517 consumer API.

  Parameters:

    - source_dir (`Union`[`str`, `PathLike`[`str`]]) – The source directory

    - python_executable (`str`) – The python executable where the backend lives

    - runner (`Callable`[[`Sequence`[`str`], `Optional`[`str`], `Optional`[`Mapping`[`str`, `str`]]], `None`]) – Runner for backend subprocesses

  The `runner`, if provided, must accept the following arguments:

  - `cmd`: a list of strings representing the command and arguments to execute, as would be passed to e.g. ‘subprocess.check_call’.

  - `cwd`: a string representing the working directory that must be used for the subprocess. Corresponds to the provided source_dir.

  - `extra_environ`: a dict mapping environment variable names to values which must be set for the subprocess execution.

  The default runner simply calls the backend hooks in a subprocess, writing backend output to stdout/stderr.

  build(distribution, output_directory, config_settings=None, metadata_directory=None)

    Build a distribution.

    Parameters:

      - distribution (`Literal`[`'sdist'`, `'wheel'`, `'editable'`]) – Distribution to build (`sdist` or `wheel`)

      - output_directory (`Union`[`str`, `PathLike`[`str`]]) – Directory to put the built distribution in

      - config_settings (`Optional`[`Mapping`[`str`, `Union`[`str`, `Sequence`[`str`]]]]) – Config settings for the build backend

      - metadata_directory (`str` | `None`) – If provided, should be the return value of a previous `prepare` call on the same `distribution` kind

    Return type:

      `str`

    Returns:

      The full path to the built distribution

  property build_system_requires: set[str]

    The dependencies defined in the `pyproject.toml`’s `build-system.requires` field or the default build dependencies if `pyproject.toml` is missing or `build-system` is undefined.

  check_dependencies(distribution, config_settings=None)

    Return the dependencies which are not satisfied from the combined set of `build_system_requires` and `get_requires_for_build()` for a given distribution.

    Parameters:

      - distribution (`Literal`[`'sdist'`, `'wheel'`, `'editable'`]) – Distribution to check (`sdist` or `wheel`)

      - config_settings (`Optional`[`Mapping`[`str`, `Union`[`str`, `Sequence`[`str`]]]]) – Config settings for the build backend

    Return type:

      `set`[`tuple`[`str`, `...`]]

    Returns:

      Set of variable-length unmet dependency tuples

  classmethod from_isolated_env(env, source_dir, runner=<function default_subprocess_runner>)
    Return type:

      `TypeVar`(`_TProjectBuilder`, bound= ProjectBuilder)

  get_requires_for_build(distribution, config_settings=None)

    Return the dependencies defined by the backend in addition to `build_system_requires` for a given distribution.

    Parameters:

      - distribution (`Literal`[`'sdist'`, `'wheel'`, `'editable'`]) – Distribution to get the dependencies of (`sdist` or `wheel`)

      - config_settings (`Optional`[`Mapping`[`str`, `Union`[`str`, `Sequence`[`str`]]]]) – Config settings for the build backend

    Return type:

      `set`[`str`]

  metadata_path(output_directory)

    Generate the metadata directory of a distribution and return its path.

    If the backend does not support the `prepare_metadata_for_build_wheel` hook, a wheel will be built and the metadata will be extracted from it.

    Parameters:

      output_directory (`Union`[`str`, `PathLike`[`str`]]) – Directory to put the metadata distribution in

    Return type:

      `str`

    Returns:

      The path of the metadata directory

  prepare(distribution, output_directory, config_settings=None)

    Prepare metadata for a distribution.

    Parameters:

      - distribution (`Literal`[`'sdist'`, `'wheel'`, `'editable'`]) – Distribution to build (must be `wheel`)

      - output_directory (`Union`[`str`, `PathLike`[`str`]]) – Directory to put the prepared metadata in

      - config_settings (`Optional`[`Mapping`[`str`, `Union`[`str`, `Sequence`[`str`]]]]) – Config settings for the build backend

    Return type:

      `str` | `None`

    Returns:

      The full path to the prepared metadata directory

  property python_executable: str

    The Python executable used to invoke the backend.

  property source_dir: str

    Project source directory.

exception build.TypoWarning

  Bases: `Warning`

  Warning raised when a possible typo is found.

build.check_dependency(req_string, ancestral_req_strings=(), parent_extras=frozenset({}))

  Verify that a dependency and all of its dependencies are met.

  Parameters:

    - req_string (`str`) – Requirement string

    - parent_extras (`Set`[`str`]) – Extras (eg. “test” in myproject[test])

  Yields:

    Unmet dependencies

  Return type:

    `Iterator`[`tuple`[`str`, `...`]]

## `build.env` module

class build.env.DefaultIsolatedEnv(*, installer='pip')

  Bases: `IsolatedEnv`

  Isolated environment which supports several different underlying implementations.

  install(requirements)

    Install packages from PEP 508 requirements in the isolated build environment.

    Parameters:

      requirements (`Collection`[`str`]) – PEP 508 requirement specification to install

    Note:

      Passing non-PEP 508 strings will result in undefined behavior, you should not rely on it. It is merely an implementation detail, it may change any time without warning.

    Return type:

      `None`

  make_extra_environ()

    Generate additional env vars specific to the isolated environment.

    Return type:

      `dict`[`str`, `str`]

  property path: str

    The location of the isolated build environment.

  property python_executable: str

    The python executable of the isolated build environment.

class build.env.IsolatedEnv(*args, **kwargs)

  Bases: `Protocol`

  Isolated build environment ABC.

  abstract make_extra_environ()

    Generate additional env vars specific to the isolated environment.

    Return type:

      `Mapping`[`str`, `str`] | `None`

  abstract property python_executable: str

    The Python executable of the isolated environment.

## `build.util` module

build.util.project_wheel_metadata(source_dir, isolated=True, *, runner=<function quiet_subprocess_runner>)

  Return the wheel metadata for a project.

  Uses the `prepare_metadata_for_build_wheel` hook if available, otherwise `build_wheel`.

  Parameters:

    - source_dir (`Union`[`str`, `PathLike`[`str`]]) – Project source directory

    - isolated (`bool`) – Whether or not to run invoke the backend in the current environment or to create an isolated one and invoke it there.

    - runner (`Callable`[[`Sequence`[`str`], `Optional`[`str`], `Optional`[`Mapping`[`str`, `str`]]], `None`]) – An alternative runner for backend subprocesses

  Return type:

    `PackageMetadata`