0
# Installation System
1
2
Package installation orchestration, dependency resolution, and operation management. Coordinates the installation of packages into environments with parallel processing and operation tracking.
3
4
## Capabilities
5
6
### Package Installer
7
8
Main installation orchestrator that coordinates dependency resolution, package downloading, building, and installation.
9
10
```python { .api }
11
class Installer:
12
"""
13
Main package installation orchestrator.
14
15
Coordinates dependency resolution, package operations, and
16
environment management for reliable package installation.
17
"""
18
19
def __init__(self, io: IO, env: Env, package: ProjectPackage,
20
locker: Locker, pool: RepositoryPool, config: Config,
21
installed: InstalledRepository | None = None,
22
executor: Executor | None = None,
23
disable_cache: bool = False):
24
"""
25
Initialize installer.
26
27
Args:
28
io: IO interface for output
29
env: Target environment
30
package: Project package instance
31
locker: Lock file handler
32
pool: Repository pool
33
config: Configuration
34
installed: Installed repository (optional)
35
executor: Optional custom executor
36
disable_cache: Whether to disable caching
37
"""
38
39
@property
40
def executor(self):
41
"""Installation executor for fine-grained control."""
42
43
def set_package(self, package) -> "Installer":
44
"""
45
Set project package.
46
47
Args:
48
package: Project package instance
49
50
Returns:
51
Self for method chaining
52
"""
53
54
def set_locker(self, locker: Locker) -> "Installer":
55
"""
56
Set lock file handler.
57
58
Args:
59
locker: Locker instance
60
61
Returns:
62
Self for method chaining
63
"""
64
65
def run(self) -> int:
66
"""
67
Execute installation process.
68
69
Returns:
70
Exit code (0 for success)
71
72
Raises:
73
InstallationError: If installation fails
74
"""
75
76
def dry_run(self, dry_run: bool = True) -> "Installer":
77
"""
78
Set dry run mode.
79
80
Args:
81
dry_run: Whether to enable dry run mode
82
83
Returns:
84
Self for method chaining
85
"""
86
87
def verbose(self, verbose: bool = True) -> "Installer":
88
"""
89
Set verbose output mode.
90
91
Args:
92
verbose: Whether to enable verbose output
93
94
Returns:
95
Self for method chaining
96
"""
97
98
def update(self, update: bool = True) -> "Installer":
99
"""
100
Set update mode for dependencies.
101
102
Args:
103
update: Whether to update dependencies
104
105
Returns:
106
Self for method chaining
107
"""
108
109
def only_groups(self, groups) -> "Installer":
110
"""
111
Install only specified dependency groups.
112
113
Args:
114
groups: Dependency groups to install
115
116
Returns:
117
Self for method chaining
118
"""
119
120
def execute_operations(self, execute: bool = True) -> "Installer":
121
"""
122
Control whether to execute operations or just plan them.
123
124
Args:
125
execute: Whether to execute operations
126
127
Returns:
128
Self for method chaining
129
"""
130
131
def install_directory(self, directory: Path) -> int:
132
"""
133
Install package from directory.
134
135
Args:
136
directory: Path to package directory
137
138
Returns:
139
Exit code (0 for success)
140
"""
141
```
142
143
#### Usage Example
144
145
```python
146
from poetry.installation.installer import Installer
147
from poetry.factory import Factory
148
from poetry.utils.env import EnvManager
149
150
# Create Poetry instance and components
151
poetry = Factory().create_poetry()
152
env_manager = EnvManager(poetry.file.parent)
153
env = env_manager.create_venv()
154
155
# Create installer
156
installer = Installer(
157
io=None,
158
env=env,
159
pool=poetry.pool,
160
config=poetry.config
161
)
162
163
# Configure installer
164
installer.set_package(poetry.package)
165
installer.set_locker(poetry.locker)
166
167
# Run installation
168
exit_code = installer.run()
169
if exit_code == 0:
170
print("Installation successful")
171
else:
172
print("Installation failed")
173
```
174
175
### Installation Operations
176
177
Individual installation operations representing different types of package operations.
178
179
```python { .api }
180
class Install:
181
"""
182
Package installation operation.
183
184
Represents installation of a new package with
185
dependency handling and rollback capabilities.
186
"""
187
188
def __init__(self, package, reason: str = None, priority: int = 0):
189
"""
190
Initialize install operation.
191
192
Args:
193
package: Package to install
194
reason: Installation reason
195
priority: Operation priority
196
"""
197
198
@property
199
def package(self):
200
"""Package being installed."""
201
202
@property
203
def job_type(self) -> str:
204
"""Operation type identifier."""
205
206
def execute(self, env: Env) -> None:
207
"""
208
Execute installation operation.
209
210
Args:
211
env: Target environment
212
213
Raises:
214
InstallationError: If installation fails
215
"""
216
217
class Uninstall:
218
"""
219
Package uninstallation operation.
220
221
Represents removal of an installed package with
222
dependency cleanup and validation.
223
"""
224
225
def __init__(self, package, reason: str = None, priority: int = 0):
226
"""
227
Initialize uninstall operation.
228
229
Args:
230
package: Package to uninstall
231
reason: Uninstallation reason
232
priority: Operation priority
233
"""
234
235
def execute(self, env: Env) -> None:
236
"""
237
Execute uninstallation operation.
238
239
Args:
240
env: Target environment
241
"""
242
243
class Update:
244
"""
245
Package update operation.
246
247
Represents updating a package from one version to another
248
with dependency resolution and compatibility checking.
249
"""
250
251
def __init__(self, initial_package, target_package,
252
reason: str = None, priority: int = 0):
253
"""
254
Initialize update operation.
255
256
Args:
257
initial_package: Currently installed package
258
target_package: Target package version
259
reason: Update reason
260
priority: Operation priority
261
"""
262
263
@property
264
def initial_package(self):
265
"""Currently installed package."""
266
267
@property
268
def target_package(self):
269
"""Target package version."""
270
271
def execute(self, env: Env) -> None:
272
"""
273
Execute update operation.
274
275
Args:
276
env: Target environment
277
"""
278
```
279
280
#### Usage Example
281
282
```python
283
from poetry.installation.operations import Install, Update, Uninstall
284
285
# Create installation operations
286
install_op = Install(package, reason="new dependency")
287
update_op = Update(old_package, new_package, reason="version update")
288
uninstall_op = Uninstall(package, reason="no longer needed")
289
290
# Execute operations in environment
291
operations = [install_op, update_op, uninstall_op]
292
for operation in operations:
293
try:
294
operation.execute(env)
295
print(f"Executed {operation.job_type} for {operation.package.name}")
296
except Exception as e:
297
print(f"Failed {operation.job_type}: {e}")
298
```
299
300
### Installation Executor
301
302
Low-level executor that handles parallel installation operations with progress tracking and error handling.
303
304
```python { .api }
305
class Executor:
306
"""
307
Installation operation executor.
308
309
Handles parallel execution of installation operations
310
with progress tracking, error handling, and rollback.
311
"""
312
313
def __init__(self, env: Env, pool: RepositoryPool,
314
config: Config, io = None):
315
"""
316
Initialize executor.
317
318
Args:
319
env: Target environment
320
pool: Repository pool
321
config: Configuration
322
io: IO interface
323
"""
324
325
def execute(self, operations: list) -> None:
326
"""
327
Execute list of operations.
328
329
Args:
330
operations: List of installation operations
331
332
Raises:
333
ExecutorError: If execution fails
334
"""
335
336
def install(self, package) -> None:
337
"""
338
Install single package.
339
340
Args:
341
package: Package to install
342
"""
343
344
def uninstall(self, package) -> None:
345
"""
346
Uninstall single package.
347
348
Args:
349
package: Package to uninstall
350
"""
351
352
def update(self, package) -> None:
353
"""
354
Update single package.
355
356
Args:
357
package: Package to update
358
"""
359
```
360
361
### Package Building
362
363
Build system integration for source distributions and wheel building.
364
365
```python { .api }
366
class PackageBuilder:
367
"""
368
Package building utilities.
369
370
Handles building packages from source with dependency
371
resolution and build environment management.
372
"""
373
374
def __init__(self, env: Env, io = None):
375
"""
376
Initialize package builder.
377
378
Args:
379
env: Build environment
380
io: IO interface
381
"""
382
383
def build_wheel(self, package, dist_dir: Path) -> Path:
384
"""
385
Build wheel distribution for package.
386
387
Args:
388
package: Package to build
389
dist_dir: Distribution output directory
390
391
Returns:
392
Path to built wheel file
393
"""
394
395
def build_sdist(self, package, dist_dir: Path) -> Path:
396
"""
397
Build source distribution for package.
398
399
Args:
400
package: Package to build
401
dist_dir: Distribution output directory
402
403
Returns:
404
Path to built source distribution
405
"""
406
407
def install_from_source(self, package, env: Env) -> None:
408
"""
409
Install package from source code.
410
411
Args:
412
package: Package to install
413
env: Target environment
414
"""
415
```
416
417
### Installation Utilities
418
419
Helper functions for installation operations and package management.
420
421
```python { .api }
422
def get_package_installer(package_type: str):
423
"""
424
Get installer for package type.
425
426
Args:
427
package_type: Type of package (wheel, sdist, etc.)
428
429
Returns:
430
Appropriate installer instance
431
"""
432
433
def validate_installation(package, env: Env) -> bool:
434
"""
435
Validate package installation in environment.
436
437
Args:
438
package: Package to validate
439
env: Environment to check
440
441
Returns:
442
True if installation is valid
443
"""
444
445
def resolve_installation_order(packages: list) -> list:
446
"""
447
Resolve installation order based on dependencies.
448
449
Args:
450
packages: List of packages to install
451
452
Returns:
453
Ordered list of packages for installation
454
"""
455
```
456
457
### Advanced Installation Patterns
458
459
#### Parallel Installation
460
461
```python
462
from poetry.installation.installer import Installer
463
from poetry.config.config import Config
464
465
def configure_parallel_installation():
466
"""Configure installer for parallel operations."""
467
config = Config.create()
468
469
# Set maximum workers for parallel installation
470
config.merge({
471
"installer.max-workers": 4,
472
"installer.modern-installation": True
473
})
474
475
return config
476
477
# Usage with installer
478
config = configure_parallel_installation()
479
installer = Installer(io=None, env=env, pool=pool, config=config)
480
```
481
482
#### Installation with Groups
483
484
```python
485
from poetry.installation.installer import Installer
486
487
def install_with_groups(poetry, groups=None):
488
"""Install dependencies with specific groups."""
489
env_manager = EnvManager(poetry.file.parent)
490
env = env_manager.create_venv()
491
492
installer = Installer(
493
io=None,
494
env=env,
495
pool=poetry.pool,
496
config=poetry.config
497
)
498
499
installer.set_package(poetry.package)
500
installer.set_locker(poetry.locker)
501
502
# Configure for specific groups
503
if groups:
504
installer.with_groups(groups)
505
506
return installer.run()
507
```
508
509
#### Development Installation
510
511
```python
512
def install_development_dependencies(poetry):
513
"""Install project with development dependencies."""
514
return install_with_groups(poetry, groups=["dev", "test", "docs"])
515
```
516
517
## Error Handling
518
519
Installation system exceptions and error conditions:
520
521
```python { .api }
522
class InstallationError(PoetryError):
523
"""Base installation error."""
524
525
class PackageNotFoundError(InstallationError):
526
"""Package not found during installation."""
527
528
class DependencyConflictError(InstallationError):
529
"""Dependency conflicts during installation."""
530
531
class BuildError(InstallationError):
532
"""Package building failures."""
533
534
class ExecutorError(InstallationError):
535
"""Installation executor errors."""
536
537
class OperationError(InstallationError):
538
"""Individual operation failures."""
539
```
540
541
Common installation errors:
542
- Network failures downloading packages
543
- Build dependencies missing or incompatible
544
- Permission errors installing to environment
545
- Dependency conflicts preventing installation
546
- Disk space insufficient for installation
547
- Package verification failures (checksums, signatures)