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: build.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='/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

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

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