API reference

Calling the build system

class pep517.Pep517HookCaller(source_dir, build_backend, backend_path=None, runner=None, python_executable=None)

A wrapper around a source directory to be built with a PEP 517 backend.

Parameters:

  • source_dir – The path to the source directory, containing pyproject.toml.

  • build_backend – The build backend spec, as per PEP 517, from pyproject.toml.

  • backend_path – The backend path, as per PEP 517, from pyproject.toml.

  • runner – A callable that invokes the wrapper subprocess.

  • python_executable – The Python executable used to invoke the backend

The ‘runner’, if provided, must expect the following:

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

get_requires_for_build_sdist(config_settings=None)

Identify packages required for building a wheel

Returns a list of dependency specifications, e.g.:

["setuptools >= 26"]

This does not include requirements specified in pyproject.toml. It returns the result of calling the equivalently named hook in a subprocess.

get_requires_for_build_wheel(config_settings=None)

Identify packages required for building a wheel

Returns a list of dependency specifications, e.g.:

["wheel >= 0.25", "setuptools"]

This does not include requirements specified in pyproject.toml. It returns the result of calling the equivalently named hook in a subprocess.

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

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

Returns the name of the newly created folder.

If the build backend defines a hook with this name, it will be called in a subprocess. If not, the backend will be asked to build a wheel, and the dist-info extracted from that (unless _allow_fallback is False).

build_sdist(sdist_directory, config_settings=None)

Build an sdist from this project.

Returns the name of the newly created file.

This calls the ‘build_sdist’ backend hook in a subprocess.

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

Build a wheel from this project.

Returns the name of the newly created file.

In general, this will call the ‘build_wheel’ hook in the backend. However, if that was previously called by ‘prepare_metadata_for_build_wheel’, and the same metadata_directory is used, the previously built wheel will be copied to wheel_directory.

subprocess_runner(runner)

A context manager for temporarily overriding the default subprocess runner.

Subprocess runners

These functions may be provided when creating Pep517HookCaller, or to Pep517HookCaller.subprocess_runner().

pep517.default_subprocess_runner(cmd, cwd=None, extra_environ=None)

The default method of calling the wrapper subprocess.

pep517.quiet_subprocess_runner(cmd, cwd=None, extra_environ=None)

A method of calling the wrapper subprocess while suppressing output.

Exceptions

exception pep517.BackendUnavailable(traceback)

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

exception pep517.BackendInvalid(backend_name, backend_path, message)

Will be raised if the backend is invalid.

exception pep517.HookMissing(hook_name)

Will be raised on missing hooks.

exception pep517.UnsupportedOperation(traceback)

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