API Documentation

This project exposes 2 modules:

build module

build - A simple, correct PEP 517 package builder

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

Bases: Exception

Exception raised when the backend fails

exception build.BuildException

Bases: Exception

Exception raised by ProjectBuilder

class build.ProjectBuilder(srcdir, python_executable='/home/docs/checkouts/readthedocs.org/user_builds/pypa-build/envs/stable/bin/python', scripts_dir=None, runner=<function default_subprocess_runner>)

Bases: object

The PEP 517 consumer API.

Parameters

  • srcdir (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 (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

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
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
Return type

Set[str]

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

metadata_path(output_directory)

Generates the metadata directory of a distribution and returns its path.

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

Parameters

output_directory (str) – Directory to put the metadata distribution in

Return type

str

prepare(distribution, output_directory, config_settings=None)

Prepare metadata for a distribution.

Parameters

  • distribution (str) – Distribution to build (must be wheel)

  • output_directory (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

The Python executable used to invoke the backend.

Return type

str

property scripts_dir

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

Return type

Optional[str]

exception build.TypoWarning

Bases: Warning

Warning raised when a potential 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 (AbstractSet[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

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 (Iterable[str]) – PEP 508 requirements

Return type

None

abstract property scripts_dir

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