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: build._exceptions.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 (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

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
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 source_dir: 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#

class build.env.DefaultIsolatedEnv(*args, **kwargs)#

Bases: build.env.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.

Return type

str

property python_executable: str#

The python executable of the isolated build environment.

Return type

str

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.

Return type

str

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