# PEPs
* [PEP 517](https://peps.python.org/pep-0517/) — A build-system independent format for source trees
* [PEP 660](https://peps.python.org/pep-0660/) — Editable installs for pyproject.toml base builds (wheel based)
# Infrastructure Projects
* [pyproject_hooks](https://pyproject-hooks.readthedocs.io/en/latest/index.html)
# Build Backend Hooks
```ad-note
All hooks run from within the top of the source tree.
This is confirmed by running `pip install` at different directories, all pointing to the source tree, and inspecting log output.
```
## Required Hooks
### build_sdist
* **Docs:** [PEP-517 — build_sdist](https://peps.python.org/pep-0517/#build-sdist)
```python
def build_sdist(
sdist_directory: str,
config_settings: _ConfigSettings = None,
) -> str:
```
* Builds a `.tar.gz` and places it in `sdist_directory`.
* Returns the basename of that `.tar.gz` path.
### build_wheel
* **Docs:** [PEP-517 — build_wheel](https://peps.python.org/pep-0517/#build-wheel)
```python
def build_wheel(
wheel_directory: str,
config_settings: _ConfigSettings = None,
metadata_directory: Optional[str] = None,
) -> str:
...
```
* Builds a `.whl` file and places it in `wheel_directory`.
* Returns the basename of that `.whl` path.
* If [[#prepare_metadata_for_build_wheel]] is not provided by the backend, `meta_directory` can either be ignored or an exception can be raised.
## Optional Hooks
### build_editable
* **Docs:** [PEP 660 — build_editable](https://peps.python.org/pep-0660/#build-editable)
```python
def build_editable(
wheel_directory: str,
config_settings: _ConfigSettings = None,
metadata_directory: Optional[str] = None,
) -> str:
...
```
* Builds a `.whl` file and places it in `wheel_directory`.
* Returns the basename of that `.whl` path.
* May do an in-place build as a side effect, to prepare extension modules or other built artifacts.
* Filename must be [PEP 427](https://peps.python.org/pep-0427/)-compliant.
* If [[#prepare_metadata_for_build_editable]] is not provided by the backend, `metadata_directory` can either be ignored or an exception can be raised.
### get_requires_for_build_editable
* **Docs:** [PEP-660 — get_requires_for_build_editable](https://peps.python.org/pep-0660/#get-requires-for-build-editable)
```python
def get_requires_for_build_editable(
config_settings: _ConfigSettings = None,
) -> List[str]:
...
```
* Returns an additional list of dependency specs.
* Not ones already specified in `pyproject.toml`.
* For example: `['foo~=1.0', 'bar']`
### get_requires_for_build_sdist
* **Docs:** [PEP-517 — get_requires_for_build_sdist](https://peps.python.org/pep-0517/#get-requires-for-build-sdist)
```python
def get_requires_for_build_sdist(
config_settings: _ConfigSettings = None,
) -> List[str]:
...
```
* Returns an additional list of dependency specs.
* Not ones already specified in `pyproject.toml`.
* For example: `['foo~=1.0', 'bar']`
### get_requires_for_build_wheel
* **Docs:** [PEP-517 — get_requires_for_build_wheel](https://peps.python.org/pep-0517/#get-requires-for-build-wheel)
```python
def get_requires_for_build_wheel(
config_settings: _ConfigSettings = None,
) -> List[str]:
...
```
* Returns a list of dependency spec strings.
* Not ones already specified in `pyproject.toml`.
* For example: `['foo~=1.0', 'bar']`
### prepare_metadata_for_build_editable
* **Docs:** [PEP-660 — prepare_metadata_for_build_editable](https://peps.python.org/pep-0660/#prepare-metadata-for-build-editable)
```python
def prepare_metadata_for_build_editable(
metadata_directory: str,
config_settings: _ConfigSettings = None,
) -> str:
...
```
* Creates a `.dist-info` directory with wheel metadata under `metadata_directory`:
* `{metadata_directory}/{package}-{version}.dist-info/`
* May create other (custom) files in that directory.
* Returns the basename of the `.dist-info` directory.
### prepare_metadata_for_build_wheel
* **Docs:** [PEP-517 — prepare_metadata_for_build_wheel](https://peps.python.org/pep-0517/#prepare-metadata-for-build-wheel)
```python
def prepare_metadata_for_build_wheel(
metadata_directory: str,
config_settings: _ConfigSettings = None,
) -> str:
...
```
* Creates a `.dist-info` directory with wheel metadata under `metadata_directory`:
* `{metadata_directory}/{package}-{version}.dist-info/`
* May create other (custom) files in that directory.
* Returns the basename of the `.dist-info` directory.
# Configuration
## Configuration Loading
There's no mechanism for providing a backend with configuration data. It's the responsibility of the backend to figure out the path to the file, to parse it, and to load information.
Seems wasteful, but there it is.
Setuptools has their parsing code in `setuptools.config.pyprojecttoml`. *This is a private module.*
```ad-important
Setuptools strictly validates `project`. Derivative backends cannot place keys there.
```
## config_settings parameter
This is based solely on command line arguments. It does not contain the settings from `pyproject.toml`.
Typing (courtesy of `setuptools.build_meta`):
```python
_ConfigSettings: TypeAlias = Optional[Dict[str, Union[str, List[str], None]]]
```