0
# Builder System
1

2
Comprehensive builder classes for creating different types of Python distributions with extensible configuration and plugin support. The builder system provides programmatic access to hatchling's build functionality.
3

4
## Capabilities
5

6
### Source Distribution Builder
7

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

10
```python { .api }
11
class SdistBuilder(BuilderInterface):
12
    def __init__(
13
        self,
14
        root: str,
15
        plugin_manager: PluginManager | None = None,
16
        config: dict | None = None,
17
        metadata: ProjectMetadata | None = None,
18
        app: Application | None = None
19
    ):
20
        """
21
        Initialize source distribution builder.
22
        
23
        Args:
24
            root: Project root directory path
25
            plugin_manager: Optional plugin manager instance
26
            config: Optional builder configuration
27
            metadata: Optional project metadata instance
28
            app: Optional application context
29
        """
30
    
31
    def build(
32
        self, 
33
        *, 
34
        directory: str | None = None, 
35
        versions: list[str] | None = None,
36
        hooks_only: bool | None = None,
37
        clean: bool | None = None,
38
        clean_hooks_after: bool | None = None,
39
        clean_only: bool | None = False
40
    ) -> Generator[str, None, None]:
41
        """
42
        Build source distributions.
43
        
44
        Args:
45
            directory: Output directory for built distributions (default: "dist")
46
            versions: List of version types to build (default: ["standard"])
47
            hooks_only: Whether to run only build hooks
48
            clean: Whether to clean build directory before building
49
            clean_hooks_after: Whether to clean hooks after building
50
            clean_only: Whether to only clean without building
51
            
52
        Yields:
53
            str: Paths to built distribution files
54
        """
55
    
56
    def get_version_api(self) -> dict[str, Callable]:
57
        """Get version API mapping of version names to callable builders."""
58
```
59

60
### Wheel Builder
61

62
Creates wheel distributions (.whl files) containing compiled bytecode and data files.
63

64
```python { .api }
65
class WheelBuilder(BuilderInterface):
66
    def __init__(
67
        self,
68
        root: str,
69
        plugin_manager: PluginManager | None = None,
70
        config: dict | None = None,
71
        metadata: ProjectMetadata | None = None,
72
        app: Application | None = None
73
    ):
74
        """
75
        Initialize wheel builder.
76
        
77
        Args:
78
            root: Project root directory path
79
            plugin_manager: Optional plugin manager instance
80
            config: Optional builder configuration
81
            metadata: Optional project metadata instance
82
            app: Optional application context
83
        """
84
    
85
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]:
86
        """
87
        Build wheel distributions.
88
        
89
        Args:
90
            directory: Output directory for built distributions
91
            versions: List of version types to build (["standard", "editable"])
92
            
93
        Yields:
94
            str: Paths to built distribution files
95
        """
96
    
97
    def get_version_api(self) -> dict[str, Callable]:
98
        """Get version API mapping of version names to callable builders."""
99
    
100
    def get_version_tags(self) -> list[str]:
101
        """Get wheel version tags for this builder."""
102
```
103

104
### Binary Builder
105

106
Base class for binary distribution builders with cross-platform support.
107

108
```python { .api }
109
class BinaryBuilder(BuilderInterface):
110
    def __init__(
111
        self,
112
        root: str,
113
        plugin_manager: PluginManager | None = None,
114
        config: dict | None = None,
115
        metadata: ProjectMetadata | None = None,
116
        app: Application | None = None
117
    ):
118
        """
119
        Initialize binary builder.
120
        
121
        Args:
122
            root: Project root directory path
123
            plugin_manager: Optional plugin manager instance
124
            config: Optional builder configuration
125
            metadata: Optional project metadata instance
126
            app: Optional application context
127
        """
128
    
129
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]:
130
        """
131
        Build binary distributions.
132
        
133
        Args:
134
            directory: Output directory for built distributions
135
            versions: List of version types to build
136
            
137
        Yields:
138
            str: Paths to built distribution files
139
        """
140
```
141

142
### Application Builder
143

144
Specialized builder for creating standalone application distributions.
145

146
```python { .api }
147
class AppBuilder(BinaryBuilder):
148
    """Application builder extending binary builder functionality."""
149
```
150

151
### Custom Builder
152

153
Generic custom builder for plugin-defined builders.
154

155
```python { .api }
156
class CustomBuilder(Generic[PluginManagerBound]):
157
    def __init__(self, builder: type[BuilderInterface], plugin_manager: PluginManagerBound):
158
        """
159
        Initialize custom builder with plugin-defined builder class.
160
        
161
        Args:
162
            builder: Builder class from plugin
163
            plugin_manager: Plugin manager instance
164
        """
165
```
166

167
## Builder Configuration
168

169
### Builder Config Base Class
170

171
```python { .api }
172
class BuilderConfig:
173
    def __init__(
174
        self,
175
        root: str,
176
        plugin_name: str,
177
        config: dict,
178
        metadata: ProjectMetadata,
179
        plugin_manager: PluginManager,
180
        target_config: dict | None = None,
181
        app: Application | None = None
182
    ):
183
        """
184
        Base configuration class for all builders.
185
        
186
        Args:
187
            root: Project root directory
188
            plugin_name: Name of the builder plugin
189
            config: Builder configuration dictionary
190
            metadata: Project metadata instance
191
            plugin_manager: Plugin manager instance
192
            target_config: Optional target-specific configuration
193
            app: Optional application context
194
        """
195
    
196
    @property
197
    def root(self) -> str:
198
        """Project root directory."""
199
    
200
    @property
201
    def plugin_name(self) -> str:
202
        """Builder plugin name."""
203
    
204
    @property
205
    def config(self) -> dict:
206
        """Builder configuration."""
207
    
208
    @property
209
    def metadata(self) -> ProjectMetadata:
210
        """Project metadata."""
211
    
212
    @property
213
    def dependencies(self) -> list[str]:
214
        """Builder dependencies."""
215
```
216

217
### Specialized Configuration Classes
218

219
```python { .api }
220
class SdistBuilderConfig(BuilderConfig):
221
    """Configuration for source distribution builder."""
222

223
class WheelBuilderConfig(BuilderConfig):
224
    """Configuration for wheel builder."""
225

226
class BinaryBuilderConfig(BuilderConfig):
227
    """Configuration for binary builders."""
228
```
229

230
## File Handling
231

232
### Included Files
233

234
```python { .api }
235
class IncludedFile:
236
    def __init__(self, path: str, source_path: str, distribution_path: str):
237
        """
238
        Represents a file included in distributions.
239
        
240
        Args:
241
            path: Relative path within distribution
242
            source_path: Absolute path to source file
243
            distribution_path: Path within distribution archive
244
        """
245
    
246
    path: str
247
    source_path: str
248
    distribution_path: str
249
```
250

251
### Archive Management
252

253
```python { .api }
254
class SdistArchive:
255
    def __init__(self, name: str, *, reproducible: bool):
256
        """
257
        Source distribution archive creation.
258
        
259
        Args:
260
            name: Archive name
261
            reproducible: Whether to create reproducible archives
262
        """
263
    
264
    def create_file(self, contents: str | bytes, *relative_paths: str) -> None:
265
        """Create a file in the archive."""
266
    
267
    def add_file(self, path: str, *, uname: str = "root", gname: str = "root") -> None:
268
        """Add an existing file to the archive."""
269

270
class WheelArchive:
271
    def __init__(self, path: str, *, reproducible: bool):
272
        """
273
        Wheel archive creation.
274
        
275
        Args:
276
            path: Path to wheel file
277
            reproducible: Whether to create reproducible archives
278
        """
279
    
280
    def write_file(self, path: str, contents: str | bytes) -> None:
281
        """Write a file to the wheel."""
282
    
283
    def add_file(self, path: str, archive_path: str) -> None:
284
        """Add an existing file to the wheel."""
285
```
286

287
## Usage Examples
288

289
### Basic Builder Usage
290

291
```python
292
import os
293
from hatchling.builders.wheel import WheelBuilder
294
from hatchling.builders.sdist import SdistBuilder
295

296
# Create builders
297
project_root = os.getcwd()
298
wheel_builder = WheelBuilder(project_root)
299
sdist_builder = SdistBuilder(project_root)
300

301
# Build distributions
302
wheel_paths = list(wheel_builder.build(directory="dist"))
303
sdist_paths = list(sdist_builder.build(directory="dist"))
304

305
print(f"Built wheels: {wheel_paths}")
306
print(f"Built sdists: {sdist_paths}")
307
```
308

309
### With Custom Configuration
310

311
```python
312
from hatchling.builders.wheel import WheelBuilder
313
from hatchling.metadata.core import ProjectMetadata
314
from hatchling.plugin.manager import PluginManager
315

316
# Load project metadata
317
metadata = ProjectMetadata(os.getcwd())
318

319
# Create plugin manager
320
plugin_manager = PluginManager(metadata)
321

322
# Custom configuration
323
config = {
324
    "include": ["src/**/*.py"],
325
    "exclude": ["**/*test*.py"],
326
    "dev-mode-dirs": ["src"]
327
}
328

329
# Create builder with custom config
330
builder = WheelBuilder(
331
    root=os.getcwd(),
332
    plugin_manager=plugin_manager,
333
    config=config,
334
    metadata=metadata
335
)
336

337
# Build with specific versions
338
wheel_paths = list(builder.build(
339
    directory="dist",
340
    versions=["standard", "editable"]
341
))
342
```
343

344
### Accessing Builder Information
345

346
```python
347
# Get version API information
348
version_api = builder.get_version_api()
349
print(f"Supported versions: {version_api}")
350

351
# For wheel builders, get version tags
352
if hasattr(builder, 'get_version_tags'):
353
    tags = builder.get_version_tags()
354
    print(f"Wheel tags: {tags}")
355

356
# Access builder configuration
357
config = builder.config
358
print(f"Dependencies: {config.dependencies}")
359
print(f"Root directory: {config.root}")
360
```
361

362
## Builder Interface
363

364
All builders implement the `BuilderInterface` protocol:
365

366
```python { .api }
367
class BuilderInterface(ABC, Generic[BuilderConfigBound, PluginManagerBound]):
368
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]:
369
        """Build distributions and yield paths to built files."""
370
    
371
    def get_version_api(self) -> dict[str, Callable]:
372
        """Get version API mapping of version names to callable builders."""
373
    
374
    def iter_build_targets(self, versions: list[str]) -> Iterator[tuple[str, str]]:
375
        """Iterate over build targets for given versions."""
376
```
377

378
## Platform-Specific Features
379

380
### macOS Platform Tags
381

382
```python { .api }
383
def process_macos_plat_tag(plat: str, /, *, compat: bool) -> str:
384
    """
385
    Process macOS platform tags for wheel compatibility.
386
    
387
    Args:
388
        plat: Platform tag string
389
        compat: Whether to use compatibility mode
390
        
391
    Returns:
392
        str: Processed platform tag
393
    """
394
```
395

396
This builder system provides the foundation for hatchling's flexible and extensible build functionality, supporting various distribution types and custom build workflows through its plugin architecture.