0
# Poethepoet
1

2
A batteries included task runner that works well with Poetry and UV package managers. Poethepoet enables developers to define and execute project tasks directly from pyproject.toml configuration files, offering multiple task execution modes and comprehensive CLI features.
3

4
## Package Information
5

6
- **Package Name**: poethepoet  
7
- **Version**: 0.37.0
8
- **Language**: Python  
9
- **Installation**: `pip install poethepoet`
10
- **Python Version**: >= 3.9
11
- **CLI Command**: `poe`
12

13
## Core Imports
14

15
```python
16
from poethepoet import main
17
```
18

19
For programmatic usage:
20

21
```python
22
from poethepoet.app import PoeThePoet
23
from poethepoet.config import PoeConfig
24
from poethepoet.io import PoeIO
25
```
26

27
## Basic Usage
28

29
### CLI Usage
30

31
```bash
32
# Install poethepoet globally
33
pip install poethepoet
34

35
# Run a task defined in pyproject.toml
36
poe test
37

38
# List available tasks
39
poe
40

41
# Run with verbose output
42
poe -v task_name
43

44
# Run with dry-run mode
45
poe -d task_name
46
```
47

48
### Programmatic Usage
49

50
```python
51
from poethepoet.app import PoeThePoet
52
from pathlib import Path
53

54
# Create application instance
55
app = PoeThePoet(cwd=Path("."))
56

57
# Execute task with CLI arguments
58
result = app(cli_args=["test", "--verbose"])
59

60
# Or resolve and run specific task
61
task = app.resolve_task()
62
if task:
63
    result = app.run_task(task)
64
```
65

66
### Configuration in pyproject.toml
67

68
```toml
69
[tool.poe.tasks]
70
# Command task
71
test = "pytest tests/"
72

73
# Script task with arguments
74
format.script = "black:main"
75
format.args = ["."]
76

77
# Sequence task
78
check.sequence = ["format", "test"]
79

80
# Task with help text
81
serve.cmd = "python -m http.server 8000"
82
serve.help = "Start development server"
83

84
# Complex task with environment variables
85
build.script = "scripts:build_project"
86
build.env = {DEBUG = "false"}
87
```
88

89
## Architecture
90

91
Poethepoet's design centers around these key components:
92

93
- **PoeThePoet**: Main application class handling task resolution and execution
94
- **PoeConfig**: Configuration loader supporting multiple file formats (TOML, YAML, JSON)
95
- **Task Types**: Pluggable task execution modes (cmd, script, expression, sequence, etc.)
96
- **Executors**: Environment-aware execution engines (Poetry, UV, virtualenv, simple)
97
- **PoeIO**: Verbosity-controlled input/output management
98

99
This architecture enables poethepoet to integrate seamlessly with various Python project tools while maintaining flexibility for different task execution needs.
100

101
## Capabilities
102

103
### Programmatic API
104

105
Core classes and functions for embedding poethepoet functionality into other applications. Provides full control over task execution, configuration management, and environment setup.
106

107
```python { .api }
108
class PoeThePoet:
109
    def __init__(
110
        self,
111
        cwd: Path | str | None = None,
112
        config: Mapping[str, Any] | PoeConfig | None = None,
113
        output: PoeIO | IO = None,
114
        **kwargs
115
    ): ...
116
    
117
    def __call__(self, cli_args: Sequence[str], internal: bool = False) -> int: ...
118
    def run_task(self, task: PoeTask, context: RunContext | None = None) -> int | None: ...
119
```
120

121
[Programmatic API](./programmatic-api.md)
122

123
### CLI Interface
124

125
Command-line interface providing task execution, help system, shell completion, and comprehensive argument handling for interactive and scripted usage.
126

127
```python { .api }
128
def main() -> None: ...
129

130
# CLI arguments
131
# poe [options] task [task_args]
132
# -h, --help [TASK]    Show help
133
# -v, --verbose        Increase verbosity  
134
# -q, --quiet          Decrease verbosity
135
# -d, --dry-run        Print task without executing
136
```
137

138
[CLI Usage](./cli-usage.md)
139

140
### Task Configuration
141

142
Multiple task types supporting different execution modes: shell commands, Python expressions, script references, and complex task composition with sequences and DAGs.
143

144
```python { .api }
145
# Task types available in configuration
146
task_types = ["cmd", "shell", "script", "expr", "sequence", "ref", "switch"]
147

148
# Configuration options
149
class TaskOptions:
150
    help: str
151
    env: dict[str, str] 
152
    cwd: str
153
    deps: list[str]
154
    args: list[str]
155
```
156

157
[Task Configuration](./task-configuration.md)
158

159
### Poetry Plugin Integration
160

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

163
```python { .api }
164
class PoetryPlugin:
165
    def activate(self, application: Application) -> None: ...
166

167
class PoeCommand:
168
    def handle(self) -> int: ...
169
```
170

171
[Plugin Integration](./plugin-integration.md)
172

173
## Exception Handling
174

175
```python { .api }
176
# Base exception class
177
class PoeException(Exception): ...
178

179
# Specific exception types
180
class ConfigValidationError(PoeException): ...
181
class ExecutionError(PoeException): ...
182
class CyclicDependencyError(PoeException): ...
183
class ExpressionParseError(PoeException): ...
184
```
185

186
Common error scenarios:
187
- Invalid task configuration
188
- Cyclic task dependencies  
189
- Missing task executables
190
- Environment setup failures
191
- Task execution errors