0
# Project Management
1
2
Project configuration, metadata handling, and dependency management for PDM projects. This module manages pyproject.toml files, dependency specifications, and project-level operations.
3
4
## Capabilities
5
6
### Project Class
7
8
Core project management class that provides comprehensive project operations and metadata handling.
9
10
```python { .api }
11
class Project:
12
"""
13
Primary project management class for PDM projects.
14
15
Manages project configuration, dependencies, environments, and metadata
16
from pyproject.toml files following PEP 621 standards.
17
"""
18
19
@property
20
def root(self) -> Path:
21
"""Project root directory path"""
22
23
@property
24
def pyproject(self) -> dict:
25
"""
26
Project metadata and configuration from pyproject.toml.
27
28
Returns:
29
Dictionary containing pyproject.toml content
30
"""
31
32
@property
33
def pyproject_file(self) -> Path:
34
"""Path to pyproject.toml file"""
35
36
@property
37
def lockfile(self) -> Lockfile:
38
"""
39
Project lockfile instance.
40
41
Returns:
42
Lockfile object for reading/writing lock data
43
"""
44
45
@property
46
def lockfile_file(self) -> Path:
47
"""Path to pdm.lock file"""
48
49
@property
50
def environment(self) -> BaseEnvironment:
51
"""
52
Project environment instance.
53
54
Returns:
55
Environment object for package management
56
"""
57
58
@property
59
def python(self) -> PythonInfo:
60
"""
61
Python interpreter information.
62
63
Returns:
64
Python interpreter details and capabilities
65
"""
66
67
def add_dependencies(
68
self,
69
requirements: list[str],
70
group: str = "default",
71
dev: bool = False
72
) -> None:
73
"""
74
Add dependencies to project configuration.
75
76
Args:
77
requirements: List of requirement specifications
78
group: Dependency group name (default: "default")
79
dev: Add to development dependencies (deprecated, use group)
80
"""
81
82
def remove_dependencies(
83
self,
84
requirements: list[str],
85
group: str = "default",
86
dev: bool = False
87
) -> None:
88
"""
89
Remove dependencies from project configuration.
90
91
Args:
92
requirements: List of package names to remove
93
group: Dependency group name (default: "default")
94
dev: Remove from development dependencies (deprecated, use group)
95
"""
96
97
def get_dependencies(self, group: str = "default") -> dict[str, Requirement]:
98
"""
99
Get dependencies for a specific group.
100
101
Args:
102
group: Dependency group name
103
104
Returns:
105
Dictionary mapping package names to Requirement objects
106
"""
107
108
def iter_groups(self) -> Iterator[str]:
109
"""
110
Iterate over all dependency groups in the project.
111
112
Yields:
113
Group names including "default" and any optional-dependencies
114
"""
115
116
def write_pyproject(self) -> None:
117
"""
118
Write current project configuration to pyproject.toml file.
119
"""
120
121
def reload_pyproject(self) -> None:
122
"""
123
Reload project configuration from pyproject.toml file.
124
"""
125
```
126
127
### Configuration Management
128
129
Project-level configuration management supporting both global and project-specific settings.
130
131
```python { .api }
132
class Config:
133
"""
134
Configuration management system for PDM projects.
135
136
Handles configuration loading, validation, and hierarchical settings
137
from global, user, and project-specific sources.
138
"""
139
140
def add_config(self, name: str, config_item: ConfigItem) -> None:
141
"""
142
Add a configuration option definition.
143
144
Args:
145
name: Configuration option name
146
config_item: Configuration item specification
147
"""
148
149
def get_config(self, name: str) -> Any:
150
"""
151
Get configuration value by name.
152
153
Args:
154
name: Configuration option name
155
156
Returns:
157
Configuration value with proper type conversion
158
"""
159
160
def set_config(self, name: str, value: Any) -> None:
161
"""
162
Set configuration value.
163
164
Args:
165
name: Configuration option name
166
value: Configuration value to set
167
"""
168
169
@property
170
def config_file(self) -> Path:
171
"""Path to project configuration file"""
172
173
class ConfigItem:
174
"""
175
Individual configuration item definition.
176
177
Defines configuration schema, validation, and default values.
178
"""
179
180
def __init__(
181
self,
182
description: str,
183
config_type: str,
184
default: Any = None,
185
choices: list[str] | None = None,
186
env_var: str | None = None
187
):
188
"""
189
Initialize configuration item.
190
191
Args:
192
description: Human-readable description
193
config_type: Type specification ("string", "boolean", "integer", etc.)
194
default: Default value if not set
195
choices: Valid choices for the option
196
env_var: Environment variable name override
197
"""
198
```
199
200
### Project Creation and Initialization
201
202
Project creation utilities and initialization functions.
203
204
```python { .api }
205
def create_project(
206
project_dir: Path | str,
207
name: str | None = None,
208
version: str = "0.1.0",
209
description: str = "",
210
author: str | None = None,
211
license: str | None = None,
212
python_requires: str = ">=3.8"
213
) -> Project:
214
"""
215
Create a new PDM project with initial configuration.
216
217
Args:
218
project_dir: Directory for new project
219
name: Project name (default: directory name)
220
version: Initial version
221
description: Project description
222
author: Author name and email
223
license: License specification
224
python_requires: Python version requirement
225
226
Returns:
227
New Project instance
228
"""
229
230
def find_project_root(path: Path | str = ".") -> Path:
231
"""
232
Find project root by searching for pyproject.toml or pdm.lock.
233
234
Args:
235
path: Starting search path
236
237
Returns:
238
Path to project root directory
239
240
Raises:
241
ProjectError: No project root found
242
"""
243
```
244
245
### Dependency Group Management
246
247
Management of dependency groups including optional dependencies and development dependencies.
248
249
```python { .api }
250
class DependencyGroup:
251
"""
252
Represents a dependency group within a project.
253
"""
254
255
def __init__(self, name: str, dependencies: dict[str, Requirement]):
256
"""
257
Initialize dependency group.
258
259
Args:
260
name: Group name
261
dependencies: Mapping of package names to requirements
262
"""
263
264
@property
265
def name(self) -> str:
266
"""Group name"""
267
268
@property
269
def dependencies(self) -> dict[str, Requirement]:
270
"""Dependencies in this group"""
271
272
def add_requirement(self, requirement: Requirement) -> None:
273
"""Add requirement to group"""
274
275
def remove_requirement(self, name: str) -> None:
276
"""Remove requirement from group"""
277
```
278
279
### Usage Examples
280
281
#### Basic Project Operations
282
283
```python
284
from pdm.project import Project, create_project
285
286
# Create new project
287
project = create_project(
288
project_dir="./my-app",
289
name="my-app",
290
version="1.0.0",
291
description="My Python application",
292
python_requires=">=3.9"
293
)
294
295
# Load existing project
296
project = Project.find_project_root(".")
297
298
# Add dependencies
299
project.add_dependencies([
300
"requests>=2.25.0",
301
"click>=8.0.0"
302
])
303
304
# Add development dependencies
305
project.add_dependencies([
306
"pytest>=6.0.0",
307
"black",
308
"mypy"
309
], group="dev")
310
311
# Write changes
312
project.write_pyproject()
313
```
314
315
#### Working with Dependency Groups
316
317
```python
318
from pdm.project import Project
319
320
project = Project()
321
322
# Create custom dependency groups
323
project.add_dependencies([
324
"pytest>=6.0",
325
"pytest-cov"
326
], group="test")
327
328
project.add_dependencies([
329
"sphinx",
330
"sphinx-rtd-theme"
331
], group="docs")
332
333
# List all groups
334
for group_name in project.iter_groups():
335
deps = project.get_dependencies(group_name)
336
print(f"{group_name}: {list(deps.keys())}")
337
338
# Remove dependency from specific group
339
project.remove_dependencies(["pytest-cov"], group="test")
340
```
341
342
#### Configuration Management
343
344
```python
345
from pdm.project import Project
346
from pdm.project.config import ConfigItem
347
348
project = Project()
349
350
# Get configuration values
351
cache_dir = project.config.get_config("cache_dir")
352
python_path = project.config.get_config("python.path")
353
354
# Set project-specific configuration
355
project.config.set_config("install.parallel", True)
356
project.config.set_config("repository.url", "https://private.pypi.org")
357
358
# Add custom configuration option
359
project.config.add_config("custom.setting", ConfigItem(
360
"My custom project setting",
361
"string",
362
default="default_value"
363
))
364
```
365
366
#### Project Metadata Manipulation
367
368
```python
369
from pdm.project import Project
370
371
project = Project()
372
373
# Update project metadata
374
project.pyproject["project"]["description"] = "Updated description"
375
project.pyproject["project"]["keywords"] = ["python", "tool"]
376
377
# Add build system configuration
378
project.pyproject["build-system"] = {
379
"requires": ["pdm-backend"],
380
"build-backend": "pdm.backend"
381
}
382
383
# Add tool configuration
384
project.pyproject.setdefault("tool", {})["pdm"] = {
385
"version": {"source": "scm"},
386
"build": {
387
"includes": ["src/"],
388
"excludes": ["tests/"]
389
}
390
}
391
392
# Save changes
393
project.write_pyproject()
394
```