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