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 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.11', 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 (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.

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

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

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(*args, **kwargs)#

Bases: IsolatedEnv

An isolated environment which combines venv and virtualenv with pip.

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

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

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:: Optional[Mapping[str, str]]

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

API Documentation#

build module#

build.env module#

build.util module#

`build` module#

`build.env` module#

`build.util` module#