API¶
- pyproject_api.__version__¶
The semantic version of the project.
Frontend¶
- class pyproject_api.Frontend(root, backend_paths, backend_module, backend_obj, requires, reuse_backend=True)[source]¶
Bases:
ABCAbstract base class for a pyproject frontend.
Create a new frontend.
- Parameters:
root (
Path) – the root path of the projectbackend_paths (
tuple[Path,...]) – paths to provision as available to import from for the build backendbackend_module (
str) – the module where the backend livesbackend_obj (
str|None) – the backend object key (will be lookup up within the backend module)requires (
tuple[Requirement,...]) – build requirements for the backendreuse_backend (
bool) – a flag indicating if the communication channel should be kept alive between messages
- LEGACY_BUILD_BACKEND = 'setuptools.build_meta:__legacy__'¶
backend key when the
pyproject.tomldoes not specify it
- LEGACY_REQUIRES = (<Requirement('setuptools>=40.8.0')>,)¶
backend requirements when the
pyproject.tomldoes not specify it
- property backend_args¶
Startup arguments for a backend.
- classmethod create_args_from_folder(folder)[source]¶
Frontend creation arguments from a python project folder (should have a
pyproject.tomlfile per PEP-518).- Parameters:
folder (
Path) – the python project folder- Return type:
tuple[Path,tuple[Path,...],str,str|None,tuple[Requirement,...],bool]- Returns:
the frontend creation args
- Raises:
ValueError – if
build-systemis not a table, one of its keys has a type PEP-518 rules out, or abackend-pathentry does not resolve inside the project (PEP-517 in-tree backends)
E.g., to create a frontend from a python project folder:
from pyproject_api import SubprocessFrontend frontend = SubprocessFrontend(*SubprocessFrontend.create_args_from_folder(project_folder)[:-1])
- get_requires_for_build_sdist(config_settings=None)[source]¶
Get build requirements for a source distribution (per PEP-517).
- Parameters:
config_settings (
dict[str,Any] |None) – run arguments- Return type:
- Returns:
outcome
- property optional_hooks¶
A dictionary indicating if the optional hook is supported or not.
- property backend¶
Backend key.
- get_requires_for_build_wheel(config_settings=None)[source]¶
Get build requirements for a wheel (per PEP-517).
- Parameters:
config_settings (
dict[str,Any] |None) – run arguments- Return type:
- Returns:
outcome
- get_requires_for_build_editable(config_settings=None)[source]¶
Get build requirements for an editable wheel build (per PEP-660).
- Parameters:
config_settings (
dict[str,Any] |None) – run arguments- Return type:
- Returns:
outcome
- prepare_metadata_for_build_wheel(metadata_directory, config_settings=None)[source]¶
Build wheel metadata (per PEP-517).
- Parameters:
metadata_directory (
Path) – where to generate the metadataconfig_settings (
dict[str,Any] |None) – build arguments
- Return type:
MetadataForBuildWheelResult|None- Returns:
metadata generation result
- prepare_metadata_for_build_editable(metadata_directory, config_settings=None)[source]¶
Build editable wheel metadata (per PEP-660).
- Parameters:
metadata_directory (
Path) – where to generate the metadataconfig_settings (
dict[str,Any] |None) – build arguments
- Return type:
- Returns:
metadata generation result
- build_sdist(sdist_directory, config_settings=None)[source]¶
Build a source distribution (per PEP-517).
- Parameters:
sdist_directory (
Path) – the folder where to build the source distributionconfig_settings (
dict[str,Any] |None) – build arguments
- Return type:
- Returns:
source distribution build result
- build_wheel(wheel_directory, config_settings=None, metadata_directory=None)[source]¶
Build a wheel file (per PEP-517).
- Parameters:
wheel_directory (
Path) – the folder where to build the wheelconfig_settings (
dict[str,Any] |None) – build argumentsmetadata_directory (
Path|None) – wheel metadata folder
- Return type:
- Returns:
wheel build result
- build_editable(wheel_directory, config_settings=None, metadata_directory=None)[source]¶
Build an editable wheel file (per PEP-660).
- Parameters:
wheel_directory (
Path) – the folder where to build the editable wheelconfig_settings (
dict[str,Any] |None) – build argumentsmetadata_directory (
Path|None) – wheel metadata folder
- Return type:
- Returns:
wheel build result
- metadata_from_built(metadata_directory, target, config_settings=None)[source]¶
Create metadata from building the wheel (use when the prepare endpoints are not present or don’t work).
- Parameters:
metadata_directory (
Path) – directory where to put the metadatatarget (
Literal['wheel','editable']) – the type of wheel metadata to buildconfig_settings (
dict[str,Any] |None) – config settings to pass in to the build endpoint
- Return type:
tuple[Path,str,str]- Returns:
the metadata directory path, with the standard output and standard error text of the build
- Raises:
RuntimeError – if the built wheel is missing or holds no
.dist-infodirectory
Build and metadata directory arguments may be relative to the caller’s current working directory. They are passed to the backend as absolute paths, since the backend runs from the project directory. Result paths retain the spelling of the directory argument. Configuration settings and generic command arguments are passed through unchanged.
Metadata preparation replaces a symlink used as the output directory with a real directory, leaving the link target untouched. Dangling links are replaced too. Paths resolving to the project root or one of its ancestors are still rejected before cleanup.
Metadata preparation clears the output directory before calling the metadata hook. If cleanup fails, the filesystem error propagates and the hook is not called. When extracting metadata from a built wheel, cleanup errors stop extraction after the wheel has been built.
- class pyproject_api.OptionalHooks[source]¶
Bases:
TypedDictA flag indicating if the backend supports the optional hook or not.
- Variables:
get_requires_for_build_sdist – the backend implements
get_requires_for_build_sdistprepare_metadata_for_build_wheel – the backend implements
prepare_metadata_for_build_wheelget_requires_for_build_wheel – the backend implements
get_requires_for_build_wheelbuild_editable – the backend implements
build_editableget_requires_for_build_editable – the backend implements
get_requires_for_build_editableprepare_metadata_for_build_editable – the backend implements
prepare_metadata_for_build_editable
- get_requires_for_build_sdist¶
- prepare_metadata_for_build_wheel¶
- get_requires_for_build_wheel¶
- build_editable¶
- get_requires_for_build_editable¶
- prepare_metadata_for_build_editable¶
Exceptions¶
Backend failed¶
- class pyproject_api.BackendFailed(result, out, err)[source]¶
Bases:
RuntimeErrorAn error of the build backend.
- Parameters:
result (
dict[str,Any]) – the backend response, with thecode,exc_typeandexc_msgkeysout (
str) – standard output collected while running the commanderr (
str) – standard error collected while running the command
- out¶
standard output collected while running the command
- err¶
standard error collected while running the command
- code¶
exit code of the command
- exc_type¶
the type of exception thrown
- exc_msg¶
the string representation of the exception thrown
Results¶
Build source distribution requires¶
- class pyproject_api.RequiresBuildSdistResult(requires, out, err)[source]¶
Bases:
NamedTupleInformation collected while acquiring the source distribution build dependencies.
- Parameters:
requires (
tuple[Requirement,...]) – source distribution build dependenciesout (
str) – backend standard output while acquiring the source distribution build dependencieserr (
str) – backend standard error while acquiring the source distribution build dependencies
Create new instance of RequiresBuildSdistResult(requires, out, err)
- requires¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Build wheel requires¶
- class pyproject_api.RequiresBuildWheelResult(requires, out, err)[source]¶
Bases:
NamedTupleInformation collected while acquiring the wheel build dependencies.
- Parameters:
requires (
tuple[Requirement,...]) – wheel build dependenciesout (
str) – backend standard output while acquiring the wheel build dependencieserr (
str) – backend standard error while acquiring the wheel build dependencies
Create new instance of RequiresBuildWheelResult(requires, out, err)
- requires¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Editable requires¶
- class pyproject_api.RequiresBuildEditableResult(requires, out, err)[source]¶
Bases:
NamedTupleInformation collected while acquiring the editable wheel build dependencies.
- Parameters:
requires (
tuple[Requirement,...]) – editable wheel build dependenciesout (
str) – backend standard output while acquiring the editable wheel build dependencieserr (
str) – backend standard error while acquiring the editable wheel build dependencies
Create new instance of RequiresBuildEditableResult(requires, out, err)
- requires¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Wheel metadata¶
- class pyproject_api.MetadataForBuildWheelResult(metadata, out, err)[source]¶
Bases:
NamedTupleInformation collected while acquiring the wheel metadata.
- Parameters:
metadata (
Path) – path to the wheel metadataout (
str) – backend standard output while generating the wheel metadataerr (
str) – backend standard error while generating the wheel metadata
Create new instance of MetadataForBuildWheelResult(metadata, out, err)
- metadata¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Editable metadata¶
- class pyproject_api.MetadataForBuildEditableResult(metadata, out, err)[source]¶
Bases:
NamedTupleInformation collected while acquiring the editable metadata.
- Parameters:
metadata (
Path) – path to the wheel metadataout (
str) – backend standard output while generating the editable wheel metadataerr (
str) – backend standard error while generating the editable wheel metadata
Create new instance of MetadataForBuildEditableResult(metadata, out, err)
- metadata¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Source distribution¶
- class pyproject_api.SdistResult(sdist, out, err)[source]¶
Bases:
NamedTupleInformation collected while building a source distribution.
- Parameters:
sdist (
Path) – path to the built source distributionout (
str) – backend standard output while building the source distributionerr (
str) – backend standard error while building the source distribution
Create new instance of SdistResult(sdist, out, err)
- sdist¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Editable¶
- class pyproject_api.EditableResult(wheel, out, err)[source]¶
Bases:
NamedTupleInformation collected while building an editable wheel.
- Parameters:
wheel (
Path) – path to the built wheel artifactout (
str) – backend standard output while building the wheelerr (
str) – backend standard error while building the wheel
Create new instance of EditableResult(wheel, out, err)
- wheel¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Wheel¶
- class pyproject_api.WheelResult(wheel, out, err)[source]¶
Bases:
NamedTupleInformation collected while building a wheel.
- Parameters:
wheel (
Path) – path to the built wheel artifactout (
str) – backend standard output while building the wheelerr (
str) – backend standard error while building the wheel
Create new instance of WheelResult(wheel, out, err)
- wheel¶
Alias for field number 0
- out¶
Alias for field number 1
- err¶
Alias for field number 2
Fresh subprocess frontend¶
- class pyproject_api.SubprocessFrontend(root, backend_paths, backend_module, backend_obj, requires)[source]¶
Bases:
FrontendA frontend that creates fresh subprocess at every call to communicate with the backend.
- Variables:
executable – the interpreter that runs the backend in a subprocess
Create a subprocess frontend.
- Parameters:
root (
Path) – the root path to the built projectbackend_paths (
tuple[Path,...]) – paths that are available on the python path for the backendbackend_module (
str) – module where the backend is locatedbackend_obj (
str|None) – object within the backend module identifying the backendrequires (
tuple[Requirement,...]) – seed requirements for the backend