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='/home/docs/checkouts/readthedocs.org/user_builds/pypa-build/envs/latest/bin/python', 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 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 (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:
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:
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:
Return type:

PackageMetadata