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 directorypython_executable (
str
) – The python executable where the backend livesrunner (
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
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:
str
- 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.- Parameters:
distribution (
str
) – Distribution to check (sdist
orwheel
)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
orwheel
)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 bewheel
)output_directory (
Union
[str
,PathLike
[str
]]) – Directory to put the prepared metadata inconfig_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 stringparent_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, otherwisebuild_wheel
.- Parameters:
source_dir (
Union
[str
,PathLike
[str
]]) – Project source directoryisolated (
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