0
# Plugin Integration
1

2
Seamless integration with Poetry's plugin system, enabling poethepoet tasks to be executed through Poetry commands with shared environment and configuration.
3

4
## Capabilities
5

6
### Poetry Plugin
7

8
The Poetry plugin enables poethepoet tasks to be executed directly through Poetry commands, providing unified environment management and configuration sharing.
9

10
```python { .api }
11
class PoetryPlugin:
12
    def activate(self, application: Application) -> None:
13
        """
14
        Activate the poethepoet plugin within Poetry.
15
        
16
        Args:
17
            application: Poetry application instance
18
            
19
        Registers the 'poe' command with Poetry's command system,
20
        enabling 'poetry poe task_name' execution.
21
        """
22
```
23

24
### Poetry Command Integration
25

26
The PoeCommand class provides the Poetry command interface for executing poethepoet tasks.
27

28
```python { .api }
29
class PoeCommand:
30
    def handle(self) -> int:
31
        """
32
        Handle Poetry poe command execution.
33
        
34
        Returns:
35
            Exit code (0 for success)
36
            
37
        Processes Poetry command arguments and delegates to
38
        poethepoet for task execution within Poetry's environment.
39
        """
40
    
41
    def get_poe(self, application, io, poe_config) -> PoeThePoet:
42
        """
43
        Create PoeThePoet instance configured for Poetry integration.
44
        
45
        Args:
46
            application: Poetry application instance
47
            io: Poetry IO handler
48
            poe_config: Poethepoet configuration
49
            
50
        Returns:
51
            Configured PoeThePoet instance
52
        """
53
```
54

55
### Plugin Installation
56

57
The plugin can be installed and managed through Poetry's plugin system.
58

59
#### Installation Methods
60

61
```bash
62
# Install poethepoet with plugin support
63
pip install poethepoet[poetry_plugin]
64

65
# Or install as Poetry plugin directly
66
poetry self add poethepoet[poetry_plugin]
67

68
# Verify plugin installation
69
poetry --plugins
70
```
71

72
#### Plugin Entry Point
73

74
The plugin is registered through the Poetry entry point system:
75

76
```python { .api }
77
# Entry point configuration (in pyproject.toml)
78
[project.entry-points."poetry.application.plugin"]
79
poethepoet = "poethepoet.plugin:PoetryPlugin"
80
```
81

82
### Plugin Usage
83

84
Once installed, poethepoet tasks can be executed through Poetry commands.
85

86
#### Basic Plugin Usage
87

88
```bash
89
# Execute poethepoet task through Poetry
90
poetry poe test
91

92
# Pass arguments to tasks
93
poetry poe serve --port 8080
94

95
# Use Poetry's environment management
96
poetry poe build  # Runs in Poetry's virtual environment
97
```
98

99
#### Comparison with Standalone Usage
100

101
```bash
102
# Standalone poethepoet (requires separate installation)
103
poe test
104

105
# Poetry plugin (uses Poetry's environment)
106
poetry poe test
107

108
# Both execute the same tasks but with different environment contexts
109
```
110

111
### Environment Integration
112

113
The plugin provides seamless integration with Poetry's virtual environment and dependency management.
114

115
```python { .api }
116
# Environment integration features
117
class PoetryIntegration:
118
    # Automatic virtual environment detection
119
    virtual_env_path: str
120
    
121
    # Poetry configuration sharing
122
    poetry_config: dict
123
    
124
    # Dependency resolution integration
125
    dependencies: dict
126
    
127
    # Build system integration
128
    build_backend: str
129
```
130

131
#### Shared Configuration
132

133
The plugin shares configuration and environment settings between Poetry and poethepoet:
134

135
- **Virtual Environment**: Uses Poetry's activated virtual environment
136
- **Dependencies**: Access to Poetry's installed dependencies
137
- **Configuration**: Inherits Poetry's project configuration
138
- **Working Directory**: Operates in Poetry's project root
139

140
### Plugin Configuration
141

142
The plugin can be configured through Poetry's configuration system and poethepoet's own configuration.
143

144
#### Poetry Configuration Integration
145

146
```toml
147
# pyproject.toml - Shared configuration
148
[tool.poetry]
149
name = "my-project"
150
version = "0.1.0"
151

152
[tool.poetry.dependencies]
153
python = "^3.9"
154
requests = "^2.25.0"
155

156
# Poethepoet tasks available to both standalone and plugin usage
157
[tool.poe.tasks]
158
test = "pytest"
159
lint = "flake8 ."
160
build = {script = "build:main"}
161
```
162

163
#### Plugin-Specific Options
164

165
```toml
166
# Optional plugin-specific configuration
167
[tool.poe.poetry_hooks]
168
# Hooks to run before/after Poetry commands
169
pre_install = "poe clean"
170
post_install = "poe setup"
171
```
172

173
### Advanced Plugin Features
174

175
#### Environment Variable Sharing
176

177
```python { .api }
178
# Environment variables available in plugin context
179
POETRY_ACTIVE = "1"           # Indicates Poetry environment
180
POETRY_VIRTUAL_ENV = "path"   # Virtual environment path  
181
POETRY_PROJECT_ROOT = "path"  # Project root directory
182
POETRY_PYPROJECT_TOML = "path" # pyproject.toml location
183
```
184

185
#### Dependency Integration
186

187
The plugin can access Poetry's dependency information:
188

189
```python { .api }
190
# Dependency integration capabilities
191
class PoetryDependencyIntegration:
192
    def get_installed_packages(self) -> dict[str, str]:
193
        """Get Poetry's installed packages."""
194
    
195
    def get_project_dependencies(self) -> dict[str, str]:
196
        """Get project dependencies from pyproject.toml."""
197
    
198
    def get_dev_dependencies(self) -> dict[str, str]:
199
        """Get development dependencies."""
200
```
201

202
### Error Handling and Compatibility
203

204
The plugin handles various Poetry versions and configuration scenarios.
205

206
```python { .api }
207
# Compatibility and error handling
208
class PluginCompatibility:
209
    min_poetry_version: str = "1.2.0"
210
    max_poetry_version: str = "3.0.0"
211
    
212
    def check_compatibility(self) -> bool:
213
        """Check Poetry version compatibility."""
214
    
215
    def handle_config_conflicts(self) -> None:
216
        """Resolve configuration conflicts."""
217
    
218
    def migrate_legacy_config(self) -> None:
219
        """Migrate from legacy configuration formats."""
220
```
221

222
#### Common Plugin Issues
223

224
- **Version Conflicts**: Poetry and poethepoet version mismatches
225
- **Environment Issues**: Virtual environment activation problems
226
- **Configuration Conflicts**: Conflicting task definitions
227
- **Plugin Loading**: Plugin registration and discovery issues
228

229
## Usage Examples
230

231
### Basic Plugin Workflow
232

233
```bash
234
# Install project with Poetry
235
poetry install
236

237
# Install poethepoet plugin
238
poetry self add poethepoet[poetry_plugin]
239

240
# Run tasks through Poetry
241
poetry poe test
242
poetry poe lint
243
poetry poe build
244
```
245

246
### Development Workflow Integration
247

248
```bash
249
# Poetry + poethepoet integrated workflow
250
poetry install                    # Install dependencies
251
poetry poe format                # Format code
252
poetry poe lint                  # Lint code  
253
poetry poe test                  # Run tests
254
poetry build                     # Build package
255
poetry poe deploy                # Deploy application
256
```
257

258
### CI/CD Integration
259

260
```yaml
261
# GitHub Actions example with Poetry plugin
262
name: CI
263
on: [push, pull_request]
264
jobs:
265
  test:
266
    runs-on: ubuntu-latest
267
    steps:
268
      - uses: actions/checkout@v2
269
      - uses: actions/setup-python@v2
270
        with:
271
          python-version: '3.9'
272
      
273
      - name: Install Poetry
274
        run: pip install poetry
275
      
276
      - name: Install dependencies and plugin
277
        run: |
278
          poetry install
279
          poetry self add poethepoet[poetry_plugin]
280
      
281
      - name: Run tasks via plugin
282
        run: |
283
          poetry poe lint
284
          poetry poe test
285
          poetry poe build
286
```
287

288
### Mixed Usage Patterns
289

290
```bash
291
# Developers can use both approaches
292
poe test                    # Standalone poethepoet
293
poetry poe test            # Through Poetry plugin
294

295
# Environment differences
296
poe --executor simple test   # Custom executor
297
poetry poe test             # Poetry's virtual environment
298

299
# Configuration sharing
300
poe -C other_project test   # Different project
301
poetry poe test             # Current Poetry project only
302
```
303

304
### Plugin Development and Customization
305

306
```python
307
# Custom plugin extension example
308
from poethepoet.plugin import PoetryPlugin
309

310
class CustomPoetryPlugin(PoetryPlugin):
311
    def activate(self, application):
312
        super().activate(application)
313
        # Add custom Poetry integration features
314
        self.add_custom_commands()
315
    
316
    def add_custom_commands(self):
317
        # Extend plugin functionality
318
        pass
319
```