0
# Core Management
1
2
Central coordination system managing projects, plugins, configuration, and global PDM operations. The core module provides the main entry point for both CLI and programmatic usage.
3
4
## Capabilities
5
6
### Core Manager Class
7
8
The primary coordination class that manages PDM's global state, plugin system, and project creation.
9
10
```python { .api }
11
class Core:
12
"""
13
Main high-level manager and plugin coordinator.
14
15
Attributes:
16
- version: Current PDM version
17
- ui: Terminal user interface
18
- state: Current core state
19
- uv_cmd: UV command availability
20
"""
21
22
def create_project(
23
self,
24
root_path: str | Path | None = None,
25
is_global: bool = False,
26
global_config: str | None = None,
27
) -> Project:
28
"""
29
Create or load a PDM project from the specified path.
30
31
Args:
32
root_path: Path to project directory (default: auto-detect)
33
is_global: Whether to create a global project
34
global_config: Path to global config file
35
36
Returns:
37
Project instance for the specified path
38
"""
39
40
def register_command(self, command: type[BaseCommand], name: str | None = None) -> None:
41
"""
42
Register a custom CLI command.
43
44
Args:
45
command: Command class (not instance) implementing BaseCommand
46
name: Optional custom name for the command
47
"""
48
49
def add_config(self, name: str, config_item: ConfigItem) -> None:
50
"""
51
Add a configuration option to PDM's global configuration.
52
53
Args:
54
name: Configuration option name
55
config_item: Configuration item definition
56
"""
57
58
def load_plugins(self) -> None:
59
"""
60
Load and initialize all registered plugins.
61
"""
62
63
@property
64
def version(self) -> str:
65
"""Current PDM version string"""
66
67
@property
68
def ui(self) -> UI:
69
"""Terminal user interface instance"""
70
71
@property
72
def state(self) -> State:
73
"""Current core state"""
74
```
75
76
### Core State Management
77
78
State dataclass managing core configuration and operational flags.
79
80
```python { .api }
81
@dataclass
82
class State:
83
"""
84
State of the core object managing configuration and operational flags.
85
86
Attributes:
87
- config_settings: Global configuration overrides
88
- exclude_newer: Exclude packages newer than timestamp
89
- build_isolation: Use isolated build environments
90
- enable_cache: Enable package caching
91
- overrides: Dependency override specifications
92
"""
93
config_settings: dict[str, str] = field(default_factory=dict)
94
exclude_newer: str | None = None
95
build_isolation: bool = True
96
enable_cache: bool = True
97
overrides: dict[str, str] = field(default_factory=dict)
98
```
99
100
### Main Entry Point
101
102
Primary CLI entry function that coordinates command parsing and execution.
103
104
```python { .api }
105
def main(args: list[str] | None = None) -> None:
106
"""
107
Main CLI entry point for PDM commands.
108
109
Args:
110
args: Command line arguments (default: sys.argv[1:])
111
112
Raises:
113
PdmArgumentError: Invalid command line arguments
114
PdmUsageError: Usage errors during command execution
115
"""
116
```
117
118
### Plugin System
119
120
PDM's extensible plugin system allows custom commands, configuration options, and functionality extensions.
121
122
#### Plugin Registration
123
124
Plugins are registered via Python entry points:
125
126
```python
127
# In setup.py or pyproject.toml
128
entry_points = {
129
"pdm": [
130
"my_plugin = my_package.plugin:plugin_function"
131
]
132
}
133
```
134
135
#### Plugin Function
136
137
```python { .api }
138
def plugin_function(core: Core) -> None:
139
"""
140
Plugin entry point function.
141
142
Args:
143
core: PDM Core instance for registration and configuration
144
145
Example:
146
def my_plugin(core: Core) -> None:
147
# Register custom command
148
core.register_command(MyCommand(), "mycmd")
149
150
# Add configuration option
151
from pdm.project.config import ConfigItem
152
core.add_config("my_option", ConfigItem(
153
"My custom option",
154
"string",
155
default="default_value"
156
))
157
"""
158
```
159
160
### Usage Examples
161
162
#### Basic Core Usage
163
164
```python
165
from pdm.core import Core
166
167
# Create core manager
168
core = Core()
169
170
# Create project
171
project = core.create_project("./my-project")
172
173
# Load plugins
174
core.load_plugins()
175
```
176
177
#### Custom Plugin Development
178
179
```python
180
from pdm.core import Core
181
from pdm.cli.commands.base import BaseCommand
182
from pdm.project.config import ConfigItem
183
184
class MyCustomCommand(BaseCommand):
185
"""Custom PDM command"""
186
187
def add_arguments(self, parser):
188
parser.add_argument("--my-flag", action="store_true")
189
190
def handle(self, project, options):
191
print(f"Executing custom command in {project.root}")
192
193
def my_plugin(core: Core) -> None:
194
"""Plugin registration function"""
195
# Register custom command
196
core.register_command(MyCustomCommand(), "mycmd")
197
198
# Add custom configuration
199
core.add_config("my_setting", ConfigItem(
200
"My custom setting",
201
"string",
202
default="value"
203
))
204
```
205
206
#### Programmatic Project Creation
207
208
```python
209
from pdm.core import Core
210
import os
211
212
# Create core instance
213
core = Core()
214
215
# Create projects in different directories
216
projects = []
217
for project_dir in ["./app", "./lib", "./tools"]:
218
os.makedirs(project_dir, exist_ok=True)
219
project = core.create_project(project_dir)
220
projects.append(project)
221
222
# Configure each project
223
for project in projects:
224
# Project-specific configuration
225
project.pyproject.setdefault("tool", {})["pdm"] = {
226
"version": {"source": "scm"}
227
}
228
```