0
# Build Backend API
1

2
PEP 517/518 compliant build backend functions for modern Python packaging workflows, enabling setuptools to work with build tools like pip, build, and other PEP 517 frontends. This API provides a standardized interface for building wheels and source distributions.
3

4
## Capabilities
5

6
### Core Build Functions
7

8
The main functions that implement the PEP 517 build backend interface for creating distributable packages.
9

10
```python { .api }
11
def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
12
    """
13
    Build a wheel distribution from the current directory.
14

15
    This function builds a wheel (.whl) file that can be installed by pip
16
    or other installation tools. The wheel contains the built package.
17

18
    Parameters:
19
    - wheel_directory (str): Directory where the wheel file will be written
20
    - config_settings (dict, optional): Build configuration settings from frontend
21
    - metadata_directory (str, optional): Directory containing prepared metadata
22

23
    Returns:
24
    str: Filename of the built wheel file
25

26
    Raises:
27
    BackendUnavailable: If backend cannot build wheels
28
    CalledProcessError: If build process fails
29
    """
30

31
def build_sdist(sdist_directory, config_settings=None):
32
    """
33
    Build a source distribution from the current directory.
34

35
    This function creates a source distribution (.tar.gz) file containing
36
    the source code and build instructions.
37

38
    Parameters:
39
    - sdist_directory (str): Directory where the sdist file will be written
40
    - config_settings (dict, optional): Build configuration settings from frontend
41

42
    Returns:
43
    str: Filename of the built source distribution
44

45
    Raises:
46
    BackendUnavailable: If backend cannot build sdists
47
    CalledProcessError: If build process fails
48
    """
49

50
def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
51
    """
52
    Build an editable wheel distribution.
53

54
    Creates a wheel that installs the package in "editable" or "development"
55
    mode, where changes to the source code are immediately reflected without
56
    reinstallation.
57

58
    Parameters:
59
    - wheel_directory (str): Directory where the wheel file will be written
60
    - config_settings (dict, optional): Build configuration settings from frontend
61
    - metadata_directory (str, optional): Directory containing prepared metadata
62

63
    Returns:
64
    str: Filename of the built editable wheel file
65

66
    Raises:
67
    BackendUnavailable: If backend cannot build editable wheels
68
    CalledProcessError: If build process fails
69
    """
70
```
71

72
### Build Requirement Functions
73

74
Functions that return the dependencies needed for building packages, allowing frontends to install necessary tools before attempting builds.
75

76
```python { .api }
77
def get_requires_for_build_wheel(config_settings=None):
78
    """
79
    Get requirements for building a wheel.
80

81
    Returns a list of packages that must be installed before
82
    build_wheel() can be called successfully.
83

84
    Parameters:
85
    - config_settings (dict, optional): Build configuration settings
86

87
    Returns:
88
    list: List of requirement strings (e.g., ['wheel>=0.30.0', 'cython'])
89

90
    Example return value:
91
    ['wheel>=0.30.0']
92
    """
93

94
def get_requires_for_build_sdist(config_settings=None):
95
    """
96
    Get requirements for building a source distribution.
97

98
    Returns a list of packages that must be installed before
99
    build_sdist() can be called successfully.
100

101
    Parameters:
102
    - config_settings (dict, optional): Build configuration settings
103

104
    Returns:
105
    list: List of requirement strings
106

107
    Example return value:
108
    []  # Usually empty for setuptools
109
    """
110

111
def get_requires_for_build_editable(config_settings=None):
112
    """
113
    Get requirements for building an editable wheel.
114

115
    Returns a list of packages that must be installed before
116
    build_editable() can be called successfully.
117

118
    Parameters:
119
    - config_settings (dict, optional): Build configuration settings
120

121
    Returns:
122
    list: List of requirement strings
123

124
    Example return value:
125
    ['wheel>=0.30.0']
126
    """
127
```
128

129
### Metadata Preparation Functions
130

131
Functions for preparing package metadata separately from the build process, which can improve build performance by avoiding redundant metadata generation.
132

133
```python { .api }
134
def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
135
    """
136
    Prepare metadata for building a wheel.
137

138
    This function generates package metadata (like METADATA, WHEEL files)
139
    without building the complete wheel. This can speed up dependency
140
    resolution by frontends.
141

142
    Parameters:
143
    - metadata_directory (str): Directory where metadata files will be written
144
    - config_settings (dict, optional): Build configuration settings
145

146
    Returns:
147
    str: Name of the metadata directory created
148

149
    The created directory will contain:
150
    - METADATA file (package metadata)
151
    - WHEEL file (wheel metadata)
152
    - entry_points.txt (if entry points are defined)
153
    - Other metadata files as needed
154
    """
155

156
def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
157
    """
158
    Prepare metadata for building an editable wheel.
159

160
    Similar to prepare_metadata_for_build_wheel but for editable installations.
161

162
    Parameters:
163
    - metadata_directory (str): Directory where metadata files will be written
164
    - config_settings (dict, optional): Build configuration settings
165

166
    Returns:
167
    str: Name of the metadata directory created
168
    """
169
```
170

171
### Build Backend Error Classes
172

173
Exception classes specific to the build backend functionality.
174

175
```python { .api }
176
class SetupRequirementsError(Exception):
177
    """
178
    Exception raised when setup requirements cannot be satisfied.
179

180
    This error is raised when the build backend cannot install or find
181
    the dependencies needed for building the package.
182

183
    Attributes:
184
    - specifiers: List of requirement specifiers that failed
185
    """
186

187
    def __init__(self, specifiers):
188
        """
189
        Initialize with failed requirement specifiers.
190

191
        Parameters:
192
        - specifiers (list): Requirements that could not be satisfied
193
        """
194
```
195

196
## Usage Examples
197

198
### Using with pyproject.toml
199

200
The build backend is typically configured in `pyproject.toml`:
201

202
```toml
203
[build-system]
204
requires = ["setuptools>=61.0", "wheel"]
205
build-backend = "setuptools.build_meta"
206
```
207

208
### Custom Build Configuration
209

210
```toml
211
[build-system]
212
requires = ["setuptools>=61.0", "wheel", "cython"]
213
build-backend = "setuptools.build_meta"
214

215
[tool.setuptools]
216
# Setuptools-specific configuration
217
zip-safe = false
218

219
[tool.setuptools.packages.find]
220
where = ["src"]
221
include = ["mypackage*"]
222
exclude = ["tests*"]
223
```
224

225
### Building with pip
226

227
```bash
228
# Build wheel using the build backend
229
pip wheel .
230

231
# Install in editable mode (uses build_editable)
232
pip install -e .
233

234
# Build source distribution
235
pip sdist .
236
```
237

238
### Building with build tool
239

240
```bash
241
# Install the build frontend
242
pip install build
243

244
# Build both wheel and sdist
245
python -m build
246

247
# Build only wheel
248
python -m build --wheel
249

250
# Build only sdist
251
python -m build --sdist
252
```
253

254
### Configuration Settings
255

256
Build frontends can pass configuration settings to the backend:
257

258
```python
259
# Example of what a frontend might do internally
260
config_settings = {
261
    'global-option': ['--verbose'],
262
    'build-option': ['--build-base', '/tmp/build'],
263
}
264

265
wheel_filename = build_wheel(
266
    wheel_directory='dist',
267
    config_settings=config_settings
268
)
269
```
270

271
### Custom Build Backend
272

273
You can create a custom build backend that wraps setuptools:
274

275
```python
276
# custom_backend.py
277
from setuptools import build_meta as _orig
278

279
# Re-export most functions unchanged
280
build_wheel = _orig.build_wheel
281
build_sdist = _orig.build_sdist
282
get_requires_for_build_wheel = _orig.get_requires_for_build_wheel
283
get_requires_for_build_sdist = _orig.get_requires_for_build_sdist
284

285
def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
286
    """Custom editable build logic."""
287
    print("Custom editable build logic")
288
    return _orig.build_editable(wheel_directory, config_settings, metadata_directory)
289

290
# Use in pyproject.toml:
291
# [build-system]
292
# requires = ["setuptools>=61.0", "wheel"]
293
# build-backend = "custom_backend"
294
```
295

296
### Error Handling
297

298
```python
299
from setuptools.build_meta import build_wheel, SetupRequirementsError
300

301
try:
302
    wheel_file = build_wheel('dist')
303
    print(f"Built wheel: {wheel_file}")
304
except SetupRequirementsError as e:
305
    print(f"Missing requirements: {e.specifiers}")
306
    # Install missing requirements and retry
307
except Exception as e:
308
    print(f"Build failed: {e}")
309
```
310

311
### Metadata Preparation
312

313
```python
314
from setuptools.build_meta import prepare_metadata_for_build_wheel
315
import os
316

317
# Prepare metadata without building the full wheel
318
metadata_dir = prepare_metadata_for_build_wheel('build/metadata')
319

320
# Read the prepared metadata
321
metadata_path = os.path.join('build/metadata', metadata_dir, 'METADATA')
322
with open(metadata_path) as f:
323
    metadata_content = f.read()
324
    print("Package metadata:", metadata_content)
325
```