0
# Poetry
1

2
Poetry is a comprehensive Python dependency management and packaging tool that modernizes Python project setup by replacing traditional files (setup.py, requirements.txt, setup.cfg, MANIFEST.in, Pipfile) with a single pyproject.toml configuration file. It provides declarative dependency management with semantic versioning support, automatic virtual environment handling, and integrated build system capabilities.
3

4
## Package Information
5

6
- **Package Name**: poetry
7
- **Language**: Python
8
- **Installation**: `pip install poetry`
9
- **CLI Tool**: `poetry` command available after installation
10

11
## Core Imports
12

13
```python
14
from poetry.factory import Factory
15
from poetry.poetry import Poetry
16
from poetry.config.config import Config
17
```
18

19
For environment management:
20

21
```python
22
from poetry.utils.env import EnvManager
23
```
24

25
For plugin development:
26

27
```python
28
from poetry.plugins.plugin import Plugin
29
from poetry.plugins.application_plugin import ApplicationPlugin
30
```
31

32
## Basic Usage
33

34
### Programmatic Poetry Instance Creation
35

36
```python
37
from poetry.factory import Factory
38
from pathlib import Path
39

40
# Create Poetry instance from project directory
41
poetry = Factory().create_poetry(cwd=Path("/path/to/project"))
42

43
# Access project configuration
44
print(f"Project: {poetry.package.name}")
45
print(f"Version: {poetry.package.version}")
46

47
# Access dependencies
48
for dependency in poetry.package.all_requires:
49
    print(f"Dependency: {dependency.name} {dependency.constraint}")
50
```
51

52
### Configuration Management
53

54
```python
55
from poetry.config.config import Config
56

57
# Access global configuration
58
config = Config.create()
59

60
# Get configuration values
61
cache_dir = config.get("cache-dir")
62
venv_path = config.get("virtualenvs.path")
63

64
# Configure package sources
65
config.merge({
66
    "repositories.my-repo": {
67
        "url": "https://my-package-repo.com/simple/"
68
    }
69
})
70
```
71

72
### Virtual Environment Management
73

74
```python
75
from poetry.utils.env import EnvManager
76
from pathlib import Path
77

78
# Create environment manager
79
env_manager = EnvManager(Path("/path/to/project"))
80

81
# Get or create virtual environment
82
env = env_manager.create_venv()
83

84
# Execute command in environment
85
env.execute("python", "-m", "pip", "list")
86
```
87

88
## Architecture
89

90
Poetry's architecture consists of several core components:
91

92
- **Poetry Class**: Central project representation providing access to configuration, dependencies, and build system
93
- **Factory**: Creates and configures Poetry instances and related components  
94
- **Configuration System**: Manages global and project-specific settings
95
- **Package Management**: Handles dependency resolution, lock files, and repository access
96
- **Installation System**: Orchestrates package installation and virtual environment management
97
- **Plugin System**: Enables extensibility through plugin interfaces
98
- **Build System**: Provides PEP 517/518 compliant building and publishing
99
- **CLI Framework**: Command-line interface built on Cleo framework
100

101
This modular design enables Poetry to serve as both a comprehensive CLI tool and a programmatic library for Python project management, dependency handling, and packaging operations.
102

103
## Capabilities
104

105
### Core API
106

107
Core Poetry classes and factory methods for creating and managing Python projects programmatically. Includes the main Poetry class, Factory for instance creation, and basic project operations.
108

109
```python { .api }
110
class Poetry:
111
    def __init__(self, file: Path, local_config: dict, package: ProjectPackage, 
112
                 locker: Locker, config: Config, disable_cache: bool = False): ...
113
    def set_locker(self, locker: Locker) -> Poetry: ...
114
    def set_pool(self, pool: RepositoryPool) -> Poetry: ...
115
    def set_config(self, config: Config) -> Poetry: ...
116
    def get_sources(self) -> list[Source]: ...
117

118
class Factory:
119
    def create_poetry(self, cwd: Path | None = None, with_groups: bool = True, 
120
                     io = None, disable_plugins: bool = False, 
121
                     disable_cache: bool = False) -> Poetry: ...
122
    def create_pool(self, config: Config, sources = None, io = None, 
123
                   disable_cache: bool = False) -> RepositoryPool: ...
124
```
125

126
[Core API](./core-api.md)
127

128
### Configuration Management
129

130
Comprehensive configuration system for managing Poetry settings, package sources, and environment preferences. Handles both global and project-specific configuration options.
131

132
```python { .api }
133
class Config:
134
    def get(self, setting_name: str, default = None): ...
135
    def merge(self, config: dict) -> Config: ...
136
    def all(self) -> dict: ...
137
    @staticmethod
138
    def create(reload: bool = False) -> Config: ...
139

140
class Source:
141
    name: str
142
    url: str
143
    priority: str
144
    def to_dict(self) -> dict: ...
145
```
146

147
[Configuration Management](./configuration.md)
148

149
### Package Management
150

151
Dependency resolution, lock file management, and repository handling. Provides complete control over project dependencies and package sources.
152

153
```python { .api }
154
class Locker:
155
    def is_locked(self) -> bool: ...
156
    def is_fresh(self) -> bool: ...
157
    def locked_repository(self) -> Repository: ...
158
    def set_lock_data(self, root, packages) -> None: ...
159

160
class RepositoryPool:
161
    def add_repository(self, repository, priority = "supplemental") -> None: ...
162
    def has_primary_repositories(self) -> bool: ...
163
```
164

165
[Package Management](./package-management.md)
166

167
### Environment Management
168

169
Virtual environment creation, management, and execution. Handles Python interpreter selection and isolated execution environments.
170

171
```python { .api }
172
class EnvManager:
173
    def create_venv(self) -> VirtualEnv: ...
174
    def get_system_env(self) -> SystemEnv: ...
175

176
class VirtualEnv:
177
    def execute(self, *args, **kwargs): ...
178
    @property
179
    def python(self) -> str: ...
180

181
def build_environment(poetry: Poetry, env: Env, io) -> Env: ...
182
def ephemeral_environment() -> Env: ...
183
```
184

185
[Environment Management](./environment.md)
186

187
### Installation System
188

189
Package installation orchestration, dependency resolution, and operation management. Coordinates the installation of packages into environments.
190

191
```python { .api }
192
class Installer:
193
    def set_package(self, package) -> Installer: ...
194
    def set_locker(self, locker) -> Installer: ...
195
    def run(self) -> int: ...
196

197
class Install:
198
    def __init__(self, package): ...
199

200
class Update:
201
    def __init__(self, initial, target): ...
202
```
203

204
[Installation System](./installation.md)
205

206
### Plugin System
207

208
Extensibility interfaces for creating Poetry plugins. Enables custom commands, functionality extensions, and integration with external tools.
209

210
```python { .api }
211
class Plugin:
212
    def activate(self, poetry: Poetry, io) -> None: ...
213

214
class ApplicationPlugin:
215
    commands: list
216
    def activate(self, application) -> None: ...
217
```
218

219
[Plugin System](./plugins.md)
220

221
### Build System
222

223
PEP 517/518 compliant build backend for creating wheel and source distributions. Integrates with Python packaging standards for distribution creation.
224

225
```python { .api }
226
def build_wheel(wheel_directory: str, config_settings: dict = None, 
227
               metadata_directory: str = None) -> str: ...
228
def build_sdist(sdist_directory: str, config_settings: dict = None) -> str: ...
229
def get_requires_for_build_wheel(config_settings: dict = None) -> list: ...
230
def get_requires_for_build_sdist(config_settings: dict = None) -> list: ...
231
```
232

233
[Build System](./build-system.md)
234

235
### CLI Commands
236

237
Command-line interface providing comprehensive project management through terminal commands. Includes all Poetry CLI functionality for project creation, dependency management, and publishing.
238

239
```python { .api }
240
class Application:
241
    def main(self) -> int: ...
242

243
class Command:
244
    def set_poetry(self, poetry: Poetry) -> None: ...
245
    def reset_poetry(self) -> None: ...
246
```
247

248
Available commands: `add`, `build`, `check`, `config`, `init`, `install`, `lock`, `new`, `publish`, `remove`, `run`, `search`, `show`, `sync`, `update`, `version`, and many subcommands.
249

250
[CLI Commands](./cli-commands.md)
251

252
## Common Types
253

254
```python { .api }
255
from pathlib import Path
256
from typing import Any, Dict, List, Optional
257

258
class ProjectPackage:
259
    """Represents a Poetry project package with metadata and dependencies."""
260
    name: str
261
    version: str
262
    all_requires: List[Dependency]
263

264
class Dependency:
265
    """Represents a package dependency with constraints."""
266
    name: str
267
    constraint: str
268

269
class TOMLFile:
270
    """TOML file handler for reading and writing configuration files."""
271
    path: Path
272
    def read(self) -> dict: ...
273
    def write(self, data: dict) -> None: ...
274

275
class PyProjectTOML:
276
    """Enhanced pyproject.toml handler with Poetry-specific functionality."""
277
    file: TOMLFile
278
    data: dict
279
    def save(self) -> None: ...
280
```
281

282
## Error Handling
283

284
Poetry raises specific exceptions for different error conditions:
285

286
```python { .api }
287
class PoetryError(Exception):
288
    """Base exception for Poetry-specific errors."""
289

290
class EnvError(Exception):
291
    """Environment-related errors."""
292

293
class EnvCommandError(EnvError):
294
    """Command execution errors in environments."""
295
```
296

297
Common error scenarios include missing pyproject.toml files, dependency resolution conflicts, environment creation failures, and network issues during package operations.