0
# Hatchling
1

2
A modern, extensible Python build backend that implements PEP 517 and PEP 660 standards. Hatchling serves as the core packaging infrastructure for Python projects, providing comprehensive build system functionality with support for plugins, custom build hooks, and flexible configuration.
3

4
## Package Information
5

6
- **Package Name**: hatchling
7
- **Language**: Python
8
- **Installation**: `pip install hatchling`
9
- **Build Backend**: Use as `build-backend = "hatchling.build"` in pyproject.toml
10

11
## Core Imports
12

13
```python
14
# PEP 517/660 build backend API
15
from hatchling.build import build_sdist, build_wheel, build_editable
16
from hatchling.build import get_requires_for_build_sdist, get_requires_for_build_wheel, get_requires_for_build_editable
17

18
# Builder classes for programmatic use
19
from hatchling.builders.sdist import SdistBuilder  
20
from hatchling.builders.wheel import WheelBuilder
21

22
# Plugin system
23
from hatchling.plugin.manager import PluginManager
24

25
# Metadata handling
26
from hatchling.metadata.core import ProjectMetadata
27

28
# CLI interface
29
from hatchling.cli import hatchling
30

31
# Plugin registration
32
from hatchling.plugin import hookimpl
33
```
34

35
## Basic Usage
36

37
### As Build Backend
38

39
Configure in `pyproject.toml`:
40

41
```toml
42
[build-system]
43
requires = ["hatchling"]
44
build-backend = "hatchling.build"
45
```
46

47
### Programmatic Usage
48

49
```python
50
import os
51
from hatchling.builders.wheel import WheelBuilder
52
from hatchling.builders.sdist import SdistBuilder
53

54
# Build a wheel
55
wheel_builder = WheelBuilder(os.getcwd())
56
wheel_path = next(wheel_builder.build(directory="dist", versions=["standard"]))
57
print(f"Built wheel: {wheel_path}")
58

59
# Build a source distribution
60
sdist_builder = SdistBuilder(os.getcwd())
61
sdist_path = next(sdist_builder.build(directory="dist", versions=["standard"]))
62
print(f"Built sdist: {sdist_path}")
63
```
64

65
### CLI Usage
66

67
```bash
68
# Build distributions
69
hatchling build
70

71
# Show metadata
72
hatchling metadata
73

74
# Version management
75
hatchling version
76

77
# Dependency analysis
78
hatchling dep
79
```
80

81
## Architecture
82

83
Hatchling is built around a plugin architecture with several key components:
84

85
- **Build Backend API**: PEP 517/660 compliant functions for build tools like pip
86
- **Builder System**: Extensible builders for different distribution types (wheel, sdist, binary)
87
- **Plugin Manager**: Centralized plugin discovery and management system
88
- **Metadata System**: Project metadata parsing, validation, and core metadata generation
89
- **Version Management**: Pluggable version sources and schemes
90
- **Build Hooks**: Pre/post-build customization points
91
- **CLI Interface**: Command-line tools for development and debugging
92

93
## Capabilities
94

95
### PEP 517/660 Build Backend
96

97
Core build backend functions implementing Python packaging standards for integration with build frontends like pip and build.
98

99
```python { .api }
100
def build_sdist(sdist_directory: str, config_settings: dict | None = None) -> str: ...
101
def build_wheel(wheel_directory: str, config_settings: dict | None = None, metadata_directory: str | None = None) -> str: ...
102
def build_editable(wheel_directory: str, config_settings: dict | None = None, metadata_directory: str | None = None) -> str: ...
103
def get_requires_for_build_sdist(config_settings: dict | None = None) -> list[str]: ...
104
def get_requires_for_build_wheel(config_settings: dict | None = None) -> list[str]: ...
105
def get_requires_for_build_editable(config_settings: dict | None = None) -> list[str]: ...
106
def prepare_metadata_for_build_wheel(metadata_directory: str, config_settings: dict | None = None) -> str: ...
107
def prepare_metadata_for_build_editable(metadata_directory: str, config_settings: dict | None = None) -> str: ...
108
```
109

110
[PEP 517/660 Build Backend](./build-backend.md)
111

112
### Builder System
113

114
Comprehensive builder classes for creating different types of Python distributions with extensible configuration and plugin support.
115

116
```python { .api }
117
class SdistBuilder(BuilderInterface):
118
    def __init__(self, root: str, plugin_manager: PluginManager | None = None, config: dict | None = None, metadata: ProjectMetadata | None = None, app: Application | None = None): ...
119
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]: ...
120

121
class WheelBuilder(BuilderInterface):
122
    def __init__(self, root: str, plugin_manager: PluginManager | None = None, config: dict | None = None, metadata: ProjectMetadata | None = None, app: Application | None = None): ...
123
    def build(self, *, directory: str = "dist", versions: list[str] | None = None) -> Iterator[str]: ...
124
```
125

126
[Builder System](./builders.md)
127

128
### Plugin System
129

130
Extensible plugin architecture supporting custom builders, build hooks, version sources, version schemes, and metadata hooks.
131

132
```python { .api }
133
class PluginManager:
134
    def __init__(self, project_metadata: ProjectMetadata, plugin_manager: PluginManager | None = None): ...
135
    @property
136
    def builders(self) -> dict[str, type[BuilderInterface]]: ...
137
    @property
138
    def build_hooks(self) -> dict[str, type[BuildHookInterface]]: ...
139
    @property
140
    def version_sources(self) -> dict[str, type[VersionSourceInterface]]: ...
141
    @property
142
    def version_schemes(self) -> dict[str, type[VersionSchemeInterface]]: ...
143
    @property
144
    def metadata_hooks(self) -> dict[str, type[MetadataHookInterface]]: ...
145
```
146

147
[Plugin System](./plugins.md)
148

149
### Metadata System
150

151
Project metadata parsing, validation, and core metadata generation following Python packaging standards.
152

153
```python { .api }
154
class ProjectMetadata:
155
    def __init__(self, root: str, plugin_manager: PluginManager | None = None, config: dict | None = None): ...
156
    @property
157
    def name(self) -> str: ...
158
    @property
159
    def version(self) -> str: ...
160
    @property
161
    def description(self) -> str: ...
162
    @property
163
    def dependencies(self) -> list[str]: ...
164
    @property
165
    def optional_dependencies(self) -> dict[str, list[str]]: ...
166
```
167

168
[Metadata System](./metadata.md)
169

170
### CLI Interface
171

172
Command-line interface providing build, metadata inspection, version management, and dependency analysis functionality.
173

174
```python { .api }
175
def hatchling() -> int: ...
176
```
177

178
[CLI Interface](./cli.md)
179

180
### Version Management
181

182
Pluggable version sources and schemes for flexible version handling across different project structures and workflows.
183

184
```python { .api }
185
class VersionSourceInterface:
186
    def get_version_data(self) -> dict: ...
187
    def set_version(self, version: str, version_data: dict) -> None: ...
188

189
class VersionSchemeInterface:
190
    def update(self, version: str, **kwargs) -> str: ...
191
    def parse(self, version: str) -> dict: ...
192
    def normalize(self, version: str) -> str: ...
193
```
194

195
[Version Management](./version.md)
196

197
## Types
198

199
```python { .api }
200
# Core build backend types
201
from typing import Any, Generator, Callable, TypeVar, Generic
202
from pathlib import Path
203

204
ConfigSettings = dict[str, Any] | None
205

206
# Generic type variables for plugin system
207
BuilderConfigBound = TypeVar('BuilderConfigBound')
208
PluginManagerBound = TypeVar('PluginManagerBound')
209

210
# Builder interfaces
211
class BuilderInterface:
212
    def build(
213
        self, *, 
214
        directory: str | None = None, 
215
        versions: list[str] | None = None,
216
        hooks_only: bool | None = None,
217
        clean: bool | None = None,
218
        clean_hooks_after: bool | None = None,
219
        clean_only: bool | None = False
220
    ) -> Generator[str, None, None]: ...
221
    def get_version_api(self) -> dict[str, Callable]: ...
222

223
class BuildHookInterface:
224
    def clean(self, versions: list[str]) -> None: ...
225
    def initialize(self, version: str, build_data: dict[str, Any]) -> None: ...
226
    def finalize(self, version: str, build_data: dict[str, Any], artifact_path: str) -> None: ...
227

228
# Plugin interfaces
229
class VersionSourceInterface:
230
    def get_version_data(self) -> dict: ...
231
    def set_version(self, version: str, version_data: dict) -> None: ...
232

233
class VersionSchemeInterface:
234
    def update(self, version: str, **kwargs) -> str: ...
235
    def parse(self, version: str) -> dict: ...
236
    def normalize(self, version: str) -> str: ...
237

238
class MetadataHookInterface:
239
    def update(self, metadata: dict[str, Any]) -> None: ...
240

241
# File and archive types
242
class IncludedFile:
243
    def __init__(self, path: str, source_path: str, distribution_path: str): ...
244
    path: str
245
    source_path: str  
246
    distribution_path: str
247
```