API Documentation - build 0.10.0

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

# API Documentation

## `build` module

build - A simple, correct PEP 517 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 `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 an setup or prepration operation fails.

class build.ProjectBuilder(srcdir, python_executable='/usr/bin/python', scripts_dir=None, runner=<function default_subprocess_runner>)

  Bases: `object`

  The PEP 517 consumer API.

  Parameters:

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

    - scripts_dir (`Optional`[`str`]) – The location of the scripts dir (defaults to the folder where the python executable lives)

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

    - runner (`Callable`[[`Sequence`[`str`], `Optional`[`str`], `Optional`[`Mapping`[`str`, `str`]]], `None`]) – An alternative 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 srcdir.

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

    Return type:

      `set`[`str`]

  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 (`str`) – 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

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

  static log(message)

    Log a message.

    The default implementation uses the logging module but this function can be overridden by users to have a different implementation.

    Parameters:

      message (`str`) – Message to output

    Return type:

      `None`

  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 (`str`) – 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:

      `Optional`[`str`]

    Returns:

      The full path to the prepared metadata directory

  property python_executable: str

    The Python executable used to invoke the backend.

    Return type:

      `str`

  property scripts_dir: str | None

    The folder where the scripts are stored for the python executable.

    Return type:

      `Optional`[`str`]

  property srcdir: str

    Project source directory.

    Return type:

      `str`

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

Creates and manages isolated build environments.

class build.env.IsolatedEnv

  Bases: `object`

  Abstract base of isolated build environments, as required by the build project.

  abstract property executable: str

    The executable of the isolated build environment.

    Return type:

      `str`

  abstract install(requirements)

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

    Parameters:

      requirements (`Collection`[`str`]) – PEP 508 requirements

    Return type:

      `None`

  abstract property scripts_dir: str

    The scripts directory of the isolated build environment.

    Return type:

      `str`

class build.env.IsolatedEnvBuilder

  Bases: `object`

  Builder object for isolated environments.

  static log(message)

    Prints message

    The default implementation uses the logging module but this function can be overwritten by users to have a different implementation.

    Parameters:

      msg – Message to output

    Return type:

      `None`

## `build.util` module

build.util.project_wheel_metadata(srcdir, isolated=True)

  Return the wheel metadata for a project.

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

  Parameters:

    - srcdir (`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.

  Return type:

    `PackageMetadata`