API reference¶
Warning
The core of this package (the APIs described below) has been renamed to
pyproject-hooks. Please use that
package (low level) or build
(higher level) in place of pep517
.
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.
-
get_requires_for_build_editable
(config_settings=None)¶ Identify packages required for building an editable 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).
-
prepare_metadata_for_build_editable
(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 an editable 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.
-
build_editable
(wheel_directory, config_settings=None, metadata_directory=None)¶ Build an editable wheel from this project.
Returns the name of the newly created file.
In general, this will call the ‘build_editable’ hook in the backend. However, if that was previously called by ‘prepare_metadata_for_build_editable’, 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.