pyproject-api
#
pyproject-api
aims to abstract away interaction with pyproject.toml
style projects in a flexible way.
API#
- pyproject_api.__version__ = '1.5.4'#
semantic version of the project
Frontend#
- class pyproject_api.Frontend(root, backend_paths, backend_module, backend_obj, requires, reuse_backend=True)[source]#
Bases:
ABC
Abstract 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 (
UnionType
[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.toml
does not specify it
- LEGACY_REQUIRES = (<Requirement('setuptools>=40.8.0')>, <Requirement('wheel')>)#
backend requirements when the
pyproject.toml
does not specify it
- classmethod create_args_from_folder(folder)[source]#
Frontend creation arguments from a python project folder (thould have a
pypyproject.toml
file per PEP-518).- Parameters:
folder (
Path
) – the python project folder- Return type:
tuple
[Path
,tuple
[Path
, …],str
,UnionType
[str
,None
],tuple
[Requirement
, …],bool
]- Returns:
the frontend creation args
E.g., to create a frontend from a python project folder:
frontend = Frontend(*Frontend.create_args_from_folder(project_folder))
- property backend#
- Return type:
str
- Returns:
backend key
- property backend_args#
- Return type:
list
[str
]- Returns:
startup arguments for a backend
- property optional_hooks#
- Return type:
- Returns:
a dictionary indicating if the optional hook is supported or not
- get_requires_for_build_sdist(config_settings=None)[source]#
Get build requirements for a source distribution (per PEP-517).
- Parameters:
config_settings (
Optional
[Dict
[str
,Any
],None
]) – run arguments- Return type:
- Returns:
outcome
- get_requires_for_build_wheel(config_settings=None)[source]#
Get build requirements for a wheel (per PEP-517).
- Parameters:
config_settings (
Optional
[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 (
Optional
[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 (
Optional
[Dict
[str
,Any
],None
]) – build arguments
- Return type:
- 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 (
Optional
[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 (
Optional
[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 (
Optional
[Dict
[str
,Any
],None
]) – build argumentsmetadata_directory (
UnionType
[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 (
Optional
[Dict
[str
,Any
],None
]) – build argumentsmetadata_directory (
UnionType
[Path
,None
]) – wheel metadata folder
- Return type:
- Returns:
wheel build result
- class pyproject_api.OptionalHooks[source]#
Bases:
TypedDict
A flag indicating if the backend supports the optional hook or not.
- 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:
RuntimeError
An error of the build backend.
- 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:
NamedTuple
Information collected while acquiring the source distribution build dependencies.
Create new instance of RequiresBuildSdistResult(requires, out, err)
- requires#
wheel build dependencies
- out#
backend standard output while acquiring the source distribution build dependencies
- err#
backend standard output while acquiring the source distribution build dependencies
Build wheel requires#
- class pyproject_api.RequiresBuildWheelResult(requires, out, err)[source]#
Bases:
NamedTuple
Information collected while acquiring the wheel build dependencies.
Create new instance of RequiresBuildWheelResult(requires, out, err)
- requires#
wheel build dependencies
- out#
backend standard output while acquiring the wheel build dependencies
- err#
backend standard error while acquiring the wheel build dependencies
Editable requires#
- class pyproject_api.RequiresBuildEditableResult(requires, out, err)[source]#
Bases:
NamedTuple
Information collected while acquiring the wheel build dependencies.
Create new instance of RequiresBuildEditableResult(requires, out, err)
- requires#
editable wheel build dependencies
- out#
backend standard output while acquiring the editable wheel build dependencies
- err#
backend standard error while acquiring the editable wheel build dependencies
Wheel metadata#
- class pyproject_api.MetadataForBuildWheelResult(metadata, out, err)[source]#
Bases:
NamedTuple
Information collected while acquiring the wheel metadata.
Create new instance of MetadataForBuildWheelResult(metadata, out, err)
- metadata#
path to the wheel metadata
- out#
backend standard output while generating the wheel metadata
- err#
backend standard output while generating the wheel metadata
Editable metadata#
- class pyproject_api.MetadataForBuildEditableResult(metadata, out, err)[source]#
Bases:
NamedTuple
Information collected while acquiring the editable metadata.
Create new instance of MetadataForBuildEditableResult(metadata, out, err)
- metadata#
path to the wheel metadata
- out#
backend standard output while generating the editable wheel metadata
- err#
backend standard output while generating the editable wheel metadata
Source distribution#
- class pyproject_api.SdistResult(sdist, out, err)[source]#
Bases:
NamedTuple
Information collected while building a source distribution.
Create new instance of SdistResult(sdist, out, err)
- sdist#
path to the built source distribution
- out#
backend standard output while building the source distribution
- err#
backend standard output while building the source distribution
Editable#
- class pyproject_api.EditableResult(wheel, out, err)[source]#
Bases:
NamedTuple
Information collected while building an editable wheel.
Create new instance of EditableResult(wheel, out, err)
- wheel#
path to the built wheel artifact
- out#
backend standard output while building the wheel
- err#
backend standard error while building the wheel
Wheel#
- class pyproject_api.WheelResult(wheel, out, err)[source]#
Bases:
NamedTuple
Information collected while building a wheel.
Create new instance of WheelResult(wheel, out, err)
- wheel#
path to the built wheel artifact
- out#
backend standard output while building the wheel
- err#
backend standard error while building the wheel
Fresh subprocess frontend#
- class pyproject_api.SubprocessFrontend(root, backend_paths, backend_module, backend_obj, requires)[source]#
Bases:
Frontend
A frontend that creates fresh subprocess at every call to communicate with the backend.
Create a subprocess frontend.
- Parameters:
root (Path) – the root path to the built project
backend_paths (tuple[Path, ...]) – paths that are available on the python path for the backend
backend_module (str) – module where the backend is located
backend_obj (str | None) – object within the backend module identifying the backend
requires (tuple[Requirement, ...]) – seed requirements for the backend