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