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
scripts_dir (
Optional
[str
]) – The location of the scripts dir (defaults to the folder where the python executable lives)python_executable (
str
) – The python executable where the backend livesrunner (
Callable
[[Sequence
[str
],Optional
[str
],Optional
[Mapping
[str
,str
]]],None
]) – An alternative 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 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
orwheel
)output_directory (
Union
[str
,PathLike
[str
]]) – Directory to put the built distribution inconfig_settings (
Optional
[Mapping
[str
,Union
[str
,Sequence
[str
]]]]) – Config settings for the build backendmetadata_directory (
Optional
[str
]) – If provided, should be the return value of a previousprepare
call on the samedistribution
kind
- Return type
- Returns
The full path to the built distribution
- property build_system_requires: set[str]#
The dependencies defined in the
pyproject.toml
’sbuild-system.requires
field or the default build dependencies ifpyproject.toml
is missing orbuild-system
is undefined.
- check_dependencies(distribution, config_settings=None)#
Return the dependencies which are not satisfied from the combined set of
build_system_requires
andget_requires_for_build()
for a given distribution.
- 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.
- 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.
- 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.
- 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
- build.check_dependency(req_string, ancestral_req_strings=(), parent_extras=frozenset({}))#
Verify that a dependency and all of its dependencies are met.
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 install(requirements)#
Install packages from PEP 508 requirements in the isolated build environment.
- Parameters
requirements (
Collection
[str
]) – PEP 508 requirements- Return type
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, otherwisebuild_wheel
.