`pyproject_hooks`#

class pyproject_hooks.BuildBackendHookCaller#

A wrapper to call the build backend hooks for a source directory.

__init__(source_dir, build_backend, backend_path=None, runner=None, python_executable=None)#

Parameters:

source_dir (str) – The source directory to invoke the build backend for
build_backend (str) – The build backend spec
backend_path (Sequence[str] | None) – Additional path entries for the build backend spec
runner (SubprocessRunner | None) – The subprocess runner to use
python_executable (str | None) – The Python executable used to invoke the build backend

subprocess_runner(runner)#

A context manager for temporarily overriding the default subprocess runner.

Parameters:: runner (SubprocessRunner) – The new subprocess runner to use within the context.
Return type:: Iterator[None]

hook_caller = BuildBackendHookCaller(...)
with hook_caller.subprocess_runner(quiet_subprocess_runner):
    ...

get_requires_for_build_wheel(config_settings=None)#

Get additional dependencies required for building a wheel.

Parameters:: config_settings (Mapping[str, Any] | None) – The configuration settings for the build backend
Returns:: A list of dependency specifiers.
Return type:: Sequence[str]

Fallback

If the build backend does not defined a hook with this name, an empty list will be returned.

prepare_metadata_for_build_wheel(metadata_directory, config_settings=None, _allow_fallback=True)#

Prepare a *.dist-info folder with metadata for this project.

Parameters:

metadata_directory (str) – The directory to write the metadata to
config_settings (Mapping[str, Any] | None) – The configuration settings for the build backend
_allow_fallback (bool) – Whether to allow the fallback to building a wheel and extracting the metadata from it. Should be passed as a keyword argument only.

Returns:

Name of the newly created subfolder within metadata_directory, containing the metadata.

Return type:

str

Fallback

If the build backend does not define a hook with this name and _allow_fallback is truthy, the backend will be asked to build a wheel via the build_wheel hook and the dist-info extracted from that will be returned.

build_wheel(wheel_directory, config_settings=None, metadata_directory=None)#

Build a wheel from this project.

Parameters:

wheel_directory (str) – The directory to write the wheel to
config_settings (Mapping[str, Any] | None) – The configuration settings for the build backend
metadata_directory (str | None) – The directory to reuse existing metadata from

Returns:

The name of the newly created wheel within wheel_directory.

Return type:

str

Interaction with fallback

If the build_wheel hook was called in the fallback for prepare_metadata_for_build_wheel(), the build backend would not be invoked. Instead, the previously built wheel will be copied to wheel_directory and the name of that file will be returned.

get_requires_for_build_editable(config_settings=None)#

Get additional dependencies required for building an editable wheel.

Parameters:: config_settings (Mapping[str, Any] | None) – The configuration settings for the build backend
Returns:: A list of dependency specifiers.
Return type:: Sequence[str]

Fallback

If the build backend does not defined a hook with this name, an empty list will be returned.

prepare_metadata_for_build_editable(metadata_directory, config_settings=None, _allow_fallback=True)#

Prepare a *.dist-info folder with metadata for this project.

Parameters:

metadata_directory (str) – The directory to write the metadata to
config_settings (Mapping[str, Any] | None) – The configuration settings for the build backend
_allow_fallback (bool) – Whether to allow the fallback to building a wheel and extracting the metadata from it. Should be passed as a keyword argument only.

Returns:

Name of the newly created subfolder within metadata_directory, containing the metadata.

Return type:

str | None

Fallback

If the build backend does not define a hook with this name and _allow_fallback is truthy, the backend will be asked to build a wheel via the build_editable hook and the dist-info extracted from that will be returned.

build_editable(wheel_directory, config_settings=None, metadata_directory=None)#

Build an editable wheel from this project.

Parameters:

wheel_directory (str) – The directory to write the wheel to
config_settings (Mapping[str, Any] | None) – The configuration settings for the build backend
metadata_directory (str | None) – The directory to reuse existing metadata from

Returns:

The name of the newly created wheel within wheel_directory.

Return type:

str

Interaction with fallback

If the build_editable hook was called in the fallback for prepare_metadata_for_build_editable(), the build backend would not be invoked. Instead, the previously built wheel will be copied to wheel_directory and the name of that file will be returned.

get_requires_for_build_sdist(config_settings=None)#

Get additional dependencies required for building an sdist.

Returns:: A list of dependency specifiers.
Return type:: Sequence[str]

build_sdist(sdist_directory, config_settings=None)#

Build an sdist from this project.

Returns:: The name of the newly created sdist within wheel_directory.
Return type:: str

Subprocess Runners#

A subprocess runner is a function that is expected to execute the subprocess. They are typically used for controlling how output is presented from the subprocess.

The subprocess runners provided out-of-the-box with this library are:

pyproject_hooks.default_subprocess_runner(...)#

The default method of calling the wrapper subprocess.

This uses subprocess.check_call() under the hood.

pyproject_hooks.quiet_subprocess_runner(...)#

Call the subprocess while suppressing output.

This uses subprocess.check_output() under the hood.

Custom Subprocess Runners#

It is possible to provide a custom subprocess runner, that behaves differently. The expected protocol for subprocess runners is as follows:

subprocess_runner_protocol(cmd, cwd=None, extra_environ=None)

Parameters:

cmd (Sequence[str]) – The command and arguments to execute, as would be passed to subprocess.run().
cwd (Optional[str]) – The working directory that must be used for the subprocess.
extra_environ (Optional[Mapping[str, str]]) – Mapping of environment variables (name to value) which must be set for the subprocess execution.

Return type:

None

Since this codebase is currently Python 3.7-compatible, the type annotation for this protocol is only available to type checkers. To annotate a variable as a subprocess runner, you can do something along the lines of:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
   from pyproject_hooks import SubprocessRunner

# Example usage
def build(awesome_runner: "SubprocessRunner") -> None:
   ...

Exceptions#

Each exception has public attributes with the same name as their constructors.

exception pyproject_hooks.BackendUnavailable#

Will be raised if the backend cannot be imported in the hook process.

__init__(traceback, message=None, backend_name=None, backend_path=None)#

__new__()#

exception pyproject_hooks.HookMissing#

Will be raised on missing hooks (if a fallback can’t be used).

__init__(hook_name)#

__new__()#

exception pyproject_hooks.UnsupportedOperation#

May be raised by build_sdist if the backend indicates that it can’t.

__init__(traceback)#

__new__()#

pyproject_hooks#

Subprocess Runners#

Custom Subprocess Runners#

Exceptions#

`pyproject_hooks`#