0
# Hatch
1

2
Modern, extensible Python project management tool that provides a comprehensive solution for Python package development, environment management, dependency handling, testing, and publishing. Hatch standardizes the development workflow with a plugin-based architecture and fast, reliable operations.
3

4
## Package Information
5

6
- **Package Name**: hatch
7
- **Language**: Python
8
- **Installation**: `pip install hatch`
9

10
## Core Imports
11

12
```python
13
from hatch.cli import main
14
from hatch.cli.application import Application
15
from hatch.project.core import Project
16
from hatch.config.user import ConfigFile
17
```
18

19
For plugin development:
20

21
```python
22
from hatch.env.plugin.interface import EnvironmentInterface
23
from hatch.publish.plugin.interface import PublisherInterface
24
from hatch.template.plugin.interface import TemplateInterface
25
```
26

27
## Basic Usage
28

29
```python
30
from hatch.project.core import Project
31
from hatch.cli.application import Application
32

33
# Initialize a project
34
project = Project("/path/to/project")
35

36
# Access project metadata
37
print(project.metadata.name)
38
print(project.metadata.version)
39

40
# Create application instance
41
app = Application(exit_func=lambda code: None)
42
app.project = project
43

44
# Get an environment
45
env = app.get_environment("default")
46
if not env.exists():
47
    env.create()
48

49
# Execute commands in the environment
50
context = app.get_execution_context()
51
app.run_shell_commands(context)
52
```
53

54
## Architecture
55

56
Hatch follows a layered architecture with clear separation of concerns:
57

58
- **CLI Layer**: Click-based command-line interface with 16+ commands
59
- **Application Layer**: Central coordinator managing project state and operations
60
- **Project Layer**: Project representation with metadata and configuration management
61
- **Plugin System**: Extensible architecture supporting environment, publisher, template, and collector plugins
62
- **Environment Management**: Virtual environment creation, dependency management, and command execution
63
- **Configuration System**: Hierarchical configuration with environment variable support
64

65
The plugin system enables extensibility through well-defined interfaces, allowing custom environments (Docker, Conda), publishers (private indices), and project templates.
66

67
## Capabilities
68

69
### CLI Commands
70

71
Command-line interface providing comprehensive project management operations including environment management, dependency handling, building, testing, publishing, and Python installation management.
72

73
```python { .api }
74
def main():
75
    """Main CLI entry point."""
76

77
# Core CLI commands available:
78
# hatch build - Build distributions
79
# hatch clean - Remove build artifacts  
80
# hatch config - Configuration management
81
# hatch dep - Dependency operations
82
# hatch env - Environment management
83
# hatch fmt - Code formatting
84
# hatch new - Project creation
85
# hatch project - Project operations
86
# hatch publish - Package publishing
87
# hatch python - Python management
88
# hatch run - Command execution
89
# hatch shell - Shell integration
90
# hatch status - Project status
91
# hatch test - Test execution
92
# hatch version - Version management
93
```
94

95
[CLI Commands](./cli-commands.md)
96

97
### Project Management
98

99
Core project representation and manipulation capabilities including project discovery, metadata access, configuration management, and project initialization.
100

101
```python { .api }
102
class Project:
103
    def __init__(self, path: Path, *, name: str | None = None, config=None): ...
104
    
105
    @classmethod
106
    def from_config(cls, config, project: str) -> Project | None: ...
107
    
108
    @property
109
    def root(self) -> Path | None: ...
110
    @property
111
    def metadata(self): ...
112
    @property
113
    def config(self): ...
114
    
115
    def find_project_root(self) -> Path | None: ...
116
    def ensure_cwd(self): ...
117
    
118
    @staticmethod
119
    def canonicalize_name(name: str, *, strict=True) -> str: ...
120
    @staticmethod
121
    def initialize(project_file_path, template_config): ...
122
```
123

124
[Project Management](./project-management.md)
125

126
### Application Controller
127

128
Central application controller that manages project state, configuration, environments, and command execution. Provides the main coordination layer for all hatch operations.
129

130
```python { .api }
131
class Application:
132
    @property
133
    def config(self): ...
134
    @property
135
    def plugins(self): ...
136
    @property
137
    def project(self): ...
138
    
139
    def get_environment(self, env_name: str | None = None): ...
140
    def prepare_environment(self, environment): ...
141
    def run_shell_commands(self, context): ...
142
    def get_python_manager(self, directory: str | None = None): ...
143
    def abort(self, text='', code=1, **kwargs): ...
144
```
145

146
[Application Controller](./application.md)
147

148
### Environment Management
149

150
Environment plugin system for creating, managing, and executing commands in isolated Python environments. Supports virtual environments, Docker containers, and custom environment types through plugins.
151

152
```python { .api }
153
class EnvironmentInterface:
154
    PLUGIN_NAME: str = ''
155
    
156
    @property
157
    def name(self) -> str: ...
158
    @property
159
    def config(self) -> dict: ...
160
    @property
161
    def dependencies(self) -> list: ...
162
    
163
    def exists(self) -> bool: ...
164
    def create(self) -> None: ...
165
    def remove(self) -> None: ...
166
    def install_project(self) -> None: ...
167
    def install_project_dev_mode(self) -> None: ...
168
    def sync_dependencies(self) -> None: ...
169
```
170

171
[Environment Management](./environment-management.md)
172

173
### Plugin System
174

175
Extensible plugin architecture supporting environment types, publishers, project templates, and environment collectors. Provides hook specifications and plugin manager for registration and discovery.
176

177
```python { .api }
178
# Hook specifications
179
def hatch_register_environment(): ...
180
def hatch_register_publisher(): ...
181
def hatch_register_template(): ...
182
def hatch_register_environment_collector(): ...
183

184
class PluginManager:
185
    def initialize(self): ...
186
    def hatch_register_environment(self): ...
187
    def hatch_register_publisher(self): ...
188
    def hatch_register_template(self): ...
189
```
190

191
[Plugin System](./plugin-system.md)
192

193
### Configuration Management
194

195
Hierarchical configuration system with lazy loading, environment variable support, and file-based persistence. Manages application settings, project configuration, and plugin configuration.
196

197
```python { .api }
198
class ConfigFile:
199
    def __init__(self, path: Path | None = None): ...
200
    
201
    @property
202
    def path(self): ...
203
    
204
    def save(self, content=None): ...
205
    def load(self): ...
206
    def read(self) -> str: ...
207
    def read_scrubbed(self) -> str: ...
208
    def restore(self): ...
209
    
210
    @classmethod
211
    def get_default_location(cls) -> Path: ...
212

213
class RootConfig:
214
    @property
215
    def mode(self): ...
216
    @property
217
    def project(self): ...
218
    @property
219
    def dirs(self): ...
220
    @property
221
    def publish(self): ...
222
```
223

224
[Configuration Management](./configuration.md)
225

226
### Python Installation Management
227

228
Automated Python distribution management including installation, version management, and distribution discovery. Supports multiple Python versions and provides integration with UV and other Python managers.
229

230
```python { .api }
231
class PythonManager:
232
    def __init__(self, directory: Path): ...
233
    
234
    def get_installed(self) -> dict: ...
235
    def install(self, identifier: str): ...
236

237
class InstalledDistribution:
238
    @property
239
    def path(self) -> Path: ...
240
    @property
241
    def name(self) -> str: ...
242
    @property
243
    def python_path(self) -> Path: ...
244
    @property
245
    def version(self) -> str: ...
246
    
247
    def needs_update(self) -> bool: ...
248
```
249

250
[Python Management](./python-management.md)
251

252
## Types
253

254
```python { .api }
255
# Core types used across the API
256
from pathlib import Path
257
from typing import Any, Dict, List, Optional, Union, Generator, Callable
258

259
# Hatch-specific types
260
class HatchError(Exception):
261
    """Base exception for hatch-specific errors."""
262

263
class PythonDistributionUnknownError(HatchError):
264
    """Raised when a Python distribution is unknown."""
265

266
class PythonDistributionResolutionError(HatchError):
267
    """Raised when Python distribution resolution fails."""
268

269
# Environment variables classes
270
class AppEnvVars:
271
    ENV: str = 'HATCH_ENV'
272
    ENV_ACTIVE: str = 'HATCH_ENV_ACTIVE'
273
    QUIET: str = 'HATCH_QUIET'
274
    VERBOSE: str = 'HATCH_VERBOSE'
275
    INTERACTIVE: str = 'HATCH_INTERACTIVE'
276
    PYTHON: str = 'HATCH_PYTHON'
277
    NO_COLOR: str = 'NO_COLOR'
278
    FORCE_COLOR: str = 'FORCE_COLOR'
279

280
class ConfigEnvVars:
281
    PROJECT: str = 'HATCH_PROJECT'
282
    DATA: str = 'HATCH_DATA_DIR'
283
    CACHE: str = 'HATCH_CACHE_DIR'
284
    CONFIG: str = 'HATCH_CONFIG'
285

286
class PublishEnvVars:
287
    USER: str = 'HATCH_INDEX_USER'
288
    AUTH: str = 'HATCH_INDEX_AUTH'
289
    REPO: str = 'HATCH_INDEX_REPO'
290
```