pyproject_hooks#

class pyproject_hooks.BuildBackendHookCaller(source_dir, build_backend, backend_path=None, runner=None, python_executable=None)#

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 – The source directory to invoke the build backend for

  • build_backend – The build backend spec

  • backend_path – Additional path entries for the build backend spec

  • runner – The subprocess runner to use

  • python_executable – The Python executable used to invoke the build backend

subprocess_runner(runner)#

A context manager for temporarily overriding the default subprocess runner.

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.

Returns

A list of dependency specifiers.

Return type

list[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.

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.

Returns

The name of the newly created wheel within wheel_directory.

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.

Returns

A list of dependency specifiers.

Return type

list[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.

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_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.

Returns

The name of the newly created wheel within wheel_directory.

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

list[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.

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, extra_environ)
Parameters

  • cmd (list[str]) – The command and arguments to execute, as would be passed to subprocess.run().

  • cwd (str) – The working directory that must be used for the subprocess.

  • extra_environ (dict[str, str]) – Mapping of environment variables (name to value) which must be set for the subprocess execution.

Return type

None

Exceptions#

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

exception pyproject_hooks.BackendInvalid(backend_name, backend_path, message)#

Will be raised if the backend is invalid.

exception pyproject_hooks.BackendUnavailable(traceback)#

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

exception pyproject_hooks.HookMissing(hook_name)#

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

exception pyproject_hooks.UnsupportedOperation(traceback)#

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