0
# PEP 517/660 Build Backend
1

2
Core build backend functions implementing Python packaging standards (PEP 517 and PEP 660) for integration with build frontends like pip, build, and other packaging tools.
3

4
## Capabilities
5

6
### Source Distribution Building
7

8
Creates source distributions (sdist) containing all source files needed to build the project.
9

10
```python { .api }
11
def build_sdist(sdist_directory: str, config_settings: dict[str, Any] | None = None) -> str:
12
    """
13
    Build a source distribution.
14
    
15
    Args:
16
        sdist_directory: Directory where the sdist will be written
17
        config_settings: Optional configuration settings from build frontend
18
        
19
    Returns:
20
        str: Basename of the built sdist file
21
        
22
    PEP Reference:
23
        https://peps.python.org/pep-0517/#build-sdist
24
    """
25
```
26

27
### Wheel Building
28

29
Creates wheel distributions (.whl files) containing compiled bytecode and data files for installation.
30

31
```python { .api }
32
def build_wheel(
33
    wheel_directory: str,
34
    config_settings: dict[str, Any] | None = None,
35
    metadata_directory: str | None = None
36
) -> str:
37
    """
38
    Build a wheel distribution.
39
    
40
    Args:
41
        wheel_directory: Directory where the wheel will be written
42
        config_settings: Optional configuration settings from build frontend
43
        metadata_directory: Optional directory containing prepared metadata
44
        
45
    Returns:
46
        str: Basename of the built wheel file
47
        
48
    PEP Reference:
49
        https://peps.python.org/pep-0517/#build-wheel
50
    """
51
```
52

53
### Editable Wheel Building
54

55
Creates editable wheels for development installations that link to source code rather than copying files.
56

57
```python { .api }
58
def build_editable(
59
    wheel_directory: str,
60
    config_settings: dict[str, Any] | None = None,
61
    metadata_directory: str | None = None
62
) -> str:
63
    """
64
    Build an editable wheel distribution.
65
    
66
    Args:
67
        wheel_directory: Directory where the editable wheel will be written
68
        config_settings: Optional configuration settings from build frontend
69
        metadata_directory: Optional directory containing prepared metadata
70
        
71
    Returns:
72
        str: Basename of the built editable wheel file
73
        
74
    PEP Reference:
75
        https://peps.python.org/pep-0660/#build-editable
76
    """
77
```
78

79
### Build Dependencies
80

81
Functions to determine build-time dependencies before building distributions.
82

83
```python { .api }
84
def get_requires_for_build_sdist(config_settings: dict[str, Any] | None = None) -> list[str]:
85
    """
86
    Get build dependencies for source distribution.
87
    
88
    Args:
89
        config_settings: Optional configuration settings from build frontend
90
        
91
    Returns:
92
        list[str]: List of build dependency specifications
93
        
94
    PEP Reference:
95
        https://peps.python.org/pep-0517/#get-requires-for-build-sdist
96
    """
97

98
def get_requires_for_build_wheel(config_settings: dict[str, Any] | None = None) -> list[str]:
99
    """
100
    Get build dependencies for wheel distribution.
101
    
102
    Args:
103
        config_settings: Optional configuration settings from build frontend
104
        
105
    Returns:
106
        list[str]: List of build dependency specifications
107
        
108
    PEP Reference:
109
        https://peps.python.org/pep-0517/#get-requires-for-build-wheel
110
    """
111

112
def get_requires_for_build_editable(config_settings: dict[str, Any] | None = None) -> list[str]:
113
    """
114
    Get build dependencies for editable wheel distribution.
115
    
116
    Args:
117
        config_settings: Optional configuration settings from build frontend
118
        
119
    Returns:
120
        list[str]: List of build dependency specifications (includes editables requirement)
121
        
122
    PEP Reference:
123
        https://peps.python.org/pep-0660/#get-requires-for-build-editable
124
    """
125
```
126

127
### Metadata Preparation (Optional)
128

129
These functions are only available when not running under pip to avoid dependency resolution issues.
130

131
```python { .api }
132
def prepare_metadata_for_build_wheel(
133
    metadata_directory: str,
134
    config_settings: dict[str, Any] | None = None
135
) -> str:
136
    """
137
    Prepare wheel metadata without building the full wheel.
138
    
139
    Args:
140
        metadata_directory: Directory where metadata will be written
141
        config_settings: Optional configuration settings from build frontend
142
        
143
    Returns:
144
        str: Basename of the metadata directory
145
        
146
    PEP Reference:
147
        https://peps.python.org/pep-0517/#prepare-metadata-for-build-wheel
148
        
149
    Note:
150
        Only available when PIP_BUILD_TRACKER environment variable is not set
151
    """
152

153
def prepare_metadata_for_build_editable(
154
    metadata_directory: str,
155
    config_settings: dict[str, Any] | None = None
156
) -> str:
157
    """
158
    Prepare editable wheel metadata without building the full wheel.
159
    
160
    Args:
161
        metadata_directory: Directory where metadata will be written
162
        config_settings: Optional configuration settings from build frontend
163
        
164
    Returns:
165
        str: Basename of the metadata directory
166
        
167
    PEP Reference:
168
        https://peps.python.org/pep-0660/#prepare-metadata-for-build-editable
169
        
170
    Note:
171
        Only available when PIP_BUILD_TRACKER environment variable is not set
172
    """
173
```
174

175
## Usage Examples
176

177
### Basic Build Backend Configuration
178

179
```python
180
# pyproject.toml
181
[build-system]
182
requires = ["hatchling"]
183
build-backend = "hatchling.build"
184
```
185

186
### Programmatic Usage
187

188
```python
189
import os
190
from hatchling.build import build_wheel, build_sdist, get_requires_for_build_wheel
191

192
# Get build dependencies
193
deps = get_requires_for_build_wheel()
194
print(f"Build dependencies: {deps}")
195

196
# Build a wheel
197
wheel_name = build_wheel("dist")
198
print(f"Built wheel: {wheel_name}")
199

200
# Build a source distribution
201
sdist_name = build_sdist("dist")
202
print(f"Built sdist: {sdist_name}")
203
```
204

205
### With Configuration Settings
206

207
```python
208
# Configuration settings can be passed by build frontends
209
config_settings = {
210
    "build-dir": "custom_build",
211
    "skip-binary-deps": "true"
212
}
213

214
wheel_name = build_wheel("dist", config_settings=config_settings)
215
```
216

217
## Error Handling
218

219
Build backend functions may raise various exceptions:
220

221
- `ValueError`: Invalid configuration or settings
222
- `FileNotFoundError`: Missing required files or directories
223
- `PermissionError`: Insufficient permissions for file operations
224
- `RuntimeError`: Build failures or internal errors
225

226
Build frontends should handle these exceptions appropriately and provide meaningful error messages to users.
227

228
## Integration Notes
229

230
### Build Frontend Integration
231

232
Hatchling integrates with build frontends through the standardized PEP 517/660 interface:
233

234
1. Frontend calls `get_requires_for_build_*` to determine dependencies
235
2. Frontend installs dependencies in build environment
236
3. Frontend calls `build_*` functions to create distributions
237
4. Optional: Frontend may call `prepare_metadata_for_build_*` for metadata-only operations
238

239
### Bootstrap Building
240

241
Hatchling includes a special `ouroboros.py` module for self-building that provides the same PEP 517/660 interface but with minimal dependencies for bootstrapping the build process.