0
# Project Management
1

2
Core project representation and manipulation capabilities including project discovery, metadata access, configuration management, and project initialization.
3

4
## Capabilities
5

6
### Project Class
7

8
Central class for representing and managing Python projects with metadata, configuration, and file system operations.
9

10
```python { .api }
11
class Project:
12
    """
13
    Represents a Python project with its configuration and metadata.
14
    
15
    Args:
16
        path (Path): Path to the project directory
17
        name (str, optional): Override project name
18
        config (optional): Configuration object
19
    """
20
    
21
    def __init__(self, path: Path, *, name: str | None = None, config=None):
22
        """Initialize project instance."""
23
    
24
    @classmethod
25
    def from_config(cls, config, project: str) -> Project | None:
26
        """
27
        Create project from configuration entry.
28
        
29
        Args:
30
            config: Root configuration object
31
            project (str): Project name from configuration
32
            
33
        Returns:
34
            Project instance or None if not found
35
        """
36
    
37
    @property
38
    def root(self) -> Path | None:
39
        """
40
        Project root directory containing pyproject.toml.
41
        
42
        Returns:
43
            Path to project root or None if not found
44
        """
45
    
46
    @property
47
    def location(self) -> Path:
48
        """
49
        Current project location.
50
        
51
        Returns:
52
            Path to project directory
53
        """
54
    
55
    @property
56
    def metadata(self):
57
        """
58
        Project metadata from pyproject.toml.
59
        
60
        Returns:
61
            Project metadata object with name, version, dependencies, etc.
62
        """
63
    
64
    @property
65
    def config(self):
66
        """
67
        Project configuration.
68
        
69
        Returns:
70
            Project configuration object
71
        """
72
    
73
    @property
74
    def plugin_manager(self):
75
        """
76
        Plugin manager for this project.
77
        
78
        Returns:
79
            PluginManager instance
80
        """
81
    
82
    def find_project_root(self) -> Path | None:
83
        """
84
        Find project root by searching for pyproject.toml.
85
        
86
        Returns:
87
            Path to project root or None if not found
88
        """
89
    
90
    def ensure_cwd(self) -> Generator[Path, None, None]:
91
        """
92
        Context manager ensuring commands run in project directory.
93
        
94
        Yields:
95
            Path: Current working directory
96
        """
97
    
98
    @staticmethod
99
    def canonicalize_name(name: str, *, strict=True) -> str:
100
        """
101
        Canonicalize project name according to PEP 508.
102
        
103
        Args:
104
            name (str): Project name to canonicalize
105
            strict (bool): Whether to apply strict canonicalization
106
            
107
        Returns:
108
            Canonicalized project name
109
        """
110
    
111
    @staticmethod
112
    def initialize(project_file_path, template_config):
113
        """
114
        Initialize new project with template configuration.
115
        
116
        Args:
117
            project_file_path: Path to pyproject.toml
118
            template_config: Template configuration data
119
        """
120
```
121

122
### Project Discovery
123

124
Utilities for discovering and validating Python projects in the file system.
125

126
```python { .api }
127
def find_project_root(start_path: Path) -> Path | None:
128
    """
129
    Find project root by searching for pyproject.toml.
130
    
131
    Args:
132
        start_path (Path): Starting directory for search
133
        
134
    Returns:
135
        Path to project root or None if not found
136
    """
137

138
def is_project_directory(path: Path) -> bool:
139
    """
140
    Check if directory contains a valid Python project.
141
    
142
    Args:
143
        path (Path): Directory to check
144
        
145
    Returns:
146
        True if directory contains pyproject.toml
147
    """
148
```
149

150
### Project Metadata
151

152
Access and manipulation of project metadata from pyproject.toml including name, version, dependencies, and build configuration.
153

154
```python { .api }
155
class ProjectMetadata:
156
    """Project metadata from pyproject.toml."""
157
    
158
    @property
159
    def name(self) -> str:
160
        """Project name."""
161
    
162
    @property
163
    def version(self) -> str:
164
        """Project version."""
165
    
166
    @property
167
    def description(self) -> str:
168
        """Project description."""
169
    
170
    @property
171
    def authors(self) -> list[str]:
172
        """Project authors."""
173
    
174
    @property
175
    def dependencies(self) -> list[str]:
176
        """Project dependencies."""
177
    
178
    @property
179
    def optional_dependencies(self) -> dict[str, list[str]]:
180
        """Optional dependencies by group."""
181
    
182
    @property
183
    def scripts(self) -> dict[str, str]:
184
        """Console scripts."""
185
    
186
    @property
187
    def entry_points(self) -> dict[str, dict[str, str]]:
188
        """Entry points by group."""
189
    
190
    @property
191
    def license(self) -> str:
192
        """Project license."""
193
    
194
    @property
195
    def readme(self) -> str:
196
        """README file path."""
197
    
198
    @property
199
    def urls(self) -> dict[str, str]:
200
        """Project URLs."""
201
    
202
    @property
203
    def classifiers(self) -> list[str]:
204
        """Trove classifiers."""
205
    
206
    @property
207
    def keywords(self) -> list[str]:
208
        """Project keywords."""
209
    
210
    @property
211
    def requires_python(self) -> str:
212
        """Required Python version."""
213
```
214

215
### Project Configuration
216

217
Access and management of hatch-specific project configuration including environments, build settings, and tool configuration.
218

219
```python { .api }
220
class ProjectConfig:
221
    """Hatch project configuration from pyproject.toml [tool.hatch] section."""
222
    
223
    @property
224
    def environments(self) -> dict[str, dict]:
225
        """Environment configurations."""
226
    
227
    @property
228
    def build(self) -> dict:
229
        """Build configuration."""
230
    
231
    @property
232
    def version(self) -> dict:
233
        """Version configuration."""
234
    
235
    @property
236
    def metadata(self) -> dict:
237
        """Metadata configuration."""
238
    
239
    @property
240
    def publish(self) -> dict:
241
        """Publishing configuration."""
242
    
243
    @property
244
    def envs(self) -> dict[str, dict]:
245
        """Legacy environment configurations."""
246
```
247

248
### Project Initialization
249

250
Create and initialize new Python projects with proper structure, configuration, and template support.
251

252
```python { .api }
253
def initialize_project(
254
    location: Path,
255
    name: str,
256
    template: str = "default",
257
    author: str | None = None,
258
    email: str | None = None,
259
    license: str = "MIT",
260
    python_version: str = ">=3.8"
261
) -> Project:
262
    """
263
    Initialize new Python project.
264
    
265
    Args:
266
        location (Path): Project directory
267
        name (str): Project name
268
        template (str): Template to use
269
        author (str, optional): Author name
270
        email (str, optional): Author email
271
        license (str): License identifier
272
        python_version (str): Required Python version
273
        
274
    Returns:
275
        Initialized Project instance
276
    """
277

278
def create_pyproject_toml(
279
    location: Path,
280
    name: str,
281
    version: str = "0.0.1",
282
    description: str = "",
283
    author: str | None = None,
284
    email: str | None = None,
285
    license: str = "MIT",
286
    python_version: str = ">=3.8",
287
    dependencies: list[str] | None = None
288
) -> None:
289
    """
290
    Create pyproject.toml file with basic configuration.
291
    
292
    Args:
293
        location (Path): Directory to create file in
294
        name (str): Project name
295
        version (str): Initial version
296
        description (str): Project description
297
        author (str, optional): Author name
298
        email (str, optional): Author email
299
        license (str): License identifier
300
        python_version (str): Required Python version
301
        dependencies (list[str], optional): Initial dependencies
302
    """
303
```
304

305
### Project Validation
306

307
Validate project structure, configuration, and metadata for correctness and compliance with standards.
308

309
```python { .api }
310
def validate_project(project: Project) -> list[str]:
311
    """
312
    Validate project configuration and structure.
313
    
314
    Args:
315
        project (Project): Project to validate
316
        
317
    Returns:
318
        List of validation errors (empty if valid)
319
    """
320

321
def validate_pyproject_toml(path: Path) -> list[str]:
322
    """
323
    Validate pyproject.toml file format and content.
324
    
325
    Args:
326
        path (Path): Path to pyproject.toml file
327
        
328
    Returns:
329
        List of validation errors (empty if valid)
330
    """
331

332
def check_project_structure(project: Project) -> list[str]:
333
    """
334
    Check project directory structure for standard layout.
335
    
336
    Args:
337
        project (Project): Project to check
338
        
339
    Returns:
340
        List of structure issues (empty if valid)
341
    """
342
```
343

344
## Usage Examples
345

346
### Basic Project Operations
347

348
```python
349
from hatch.project.core import Project
350
from pathlib import Path
351

352
# Create project instance
353
project = Project(Path("/path/to/project"))
354

355
# Check if project exists
356
if project.root:
357
    print(f"Project found at: {project.root}")
358
    print(f"Project name: {project.metadata.name}")
359
    print(f"Project version: {project.metadata.version}")
360
else:
361
    print("No project found")
362

363
# Work in project directory
364
with project.ensure_cwd():
365
    # Commands here run in project directory
366
    print(f"Working in: {Path.cwd()}")
367
```
368

369
### Project Configuration Access
370

371
```python
372
from hatch.project.core import Project
373

374
project = Project(Path.cwd())
375

376
# Access metadata
377
print(f"Name: {project.metadata.name}")
378
print(f"Version: {project.metadata.version}")
379
print(f"Dependencies: {project.metadata.dependencies}")
380

381
# Access hatch configuration
382
config = project.config
383
environments = config.environments
384
build_config = config.build
385

386
# Check environment configuration
387
if "test" in environments:
388
    test_env = environments["test"]
389
    print(f"Test dependencies: {test_env.get('dependencies', [])}")
390
```
391

392
### Project Creation
393

394
```python
395
from hatch.project.core import Project
396
from pathlib import Path
397

398
# Initialize new project
399
location = Path("./my-new-project")
400
location.mkdir(exist_ok=True)
401

402
# Create project with template
403
project = initialize_project(
404
    location=location,
405
    name="my-new-project",
406
    author="Your Name",
407
    email="your@email.com",
408
    template="default"
409
)
410

411
print(f"Created project: {project.metadata.name}")
412
```