0
# Task Configuration
1
2
Multiple task types supporting different execution modes: shell commands, Python expressions, script references, and complex task composition with sequences and DAGs.
3
4
## Capabilities
5
6
### Task Types
7
8
Poethepoet supports multiple task execution modes, each optimized for different use cases.
9
10
```python { .api }
11
# Available task types in configuration
12
TASK_TYPES = [
13
"cmd", # Shell command execution
14
"shell", # Shell script execution
15
"script", # Python script/function execution
16
"expr", # Python expression evaluation
17
"sequence", # Sequential task composition
18
"ref", # Task reference/alias
19
"switch" # Conditional task switching
20
]
21
```
22
23
### Command Tasks
24
25
Execute shell commands with full argument and environment support.
26
27
```python { .api }
28
# Command task configuration
29
class CmdTask:
30
cmd: str # Command to execute
31
args: list[str] # Additional arguments
32
env: dict[str, str] # Environment variables
33
cwd: str # Working directory
34
help: str # Help description
35
deps: list[str] # Task dependencies
36
```
37
38
#### Configuration Examples
39
40
```toml
41
[tool.poe.tasks]
42
# Simple command
43
test = "pytest tests/"
44
45
# Command with arguments
46
serve = {cmd = "python -m http.server", args = ["8000"]}
47
48
# Command with environment variables
49
build = {cmd = "python setup.py build", env = {DEBUG = "false"}}
50
51
# Command with working directory
52
docs = {cmd = "sphinx-build . _build", cwd = "docs/"}
53
54
# Command with dependencies
55
deploy = {cmd = "deploy.sh", deps = ["test", "build"]}
56
```
57
58
### Shell Tasks
59
60
Execute shell scripts with interpreter selection and variable substitution.
61
62
```python { .api }
63
# Shell task configuration
64
class ShellTask:
65
shell: str # Shell script content
66
interpreter: str # Shell interpreter
67
env: dict[str, str] # Environment variables
68
cwd: str # Working directory
69
help: str # Help description
70
deps: list[str] # Task dependencies
71
```
72
73
#### Configuration Examples
74
75
```toml
76
[tool.poe.tasks]
77
# Multi-line shell script
78
setup.shell = """
79
echo "Setting up environment..."
80
mkdir -p build/
81
cp config.json build/
82
echo "Setup complete"
83
"""
84
85
# Shell script with custom interpreter
86
bash_script = {shell = "echo 'Hello from bash'", interpreter = "bash"}
87
88
# Shell script with environment variables
89
build_env = {
90
shell = "echo $PROJECT_NAME version $VERSION",
91
env = {PROJECT_NAME = "myapp", VERSION = "1.0.0"}
92
}
93
```
94
95
### Script Tasks
96
97
Execute Python functions or modules with argument passing and import resolution.
98
99
```python { .api }
100
# Script task configuration
101
class ScriptTask:
102
script: str # Python function reference (module:function)
103
args: list[str] # Function arguments
104
env: dict[str, str] # Environment variables
105
cwd: str # Working directory
106
help: str # Help description
107
deps: list[str] # Task dependencies
108
```
109
110
#### Configuration Examples
111
112
```toml
113
[tool.poe.tasks]
114
# Function reference
115
build = {script = "scripts:build_project"}
116
117
# Function with arguments
118
process = {script = "data.processor:main", args = ["--input", "data.csv"]}
119
120
# Module execution
121
serve = {script = "myapp:run_server"}
122
123
# Built-in script utilities
124
clean = {script = "poethepoet.scripts:rm", args = ["dist/", "build/"]}
125
```
126
127
### Expression Tasks
128
129
Evaluate Python expressions with access to environment variables and utility functions.
130
131
```python { .api }
132
# Expression task configuration
133
class ExprTask:
134
expr: str # Python expression to evaluate
135
env: dict[str, str] # Environment variables
136
cwd: str # Working directory
137
help: str # Help description
138
deps: list[str] # Task dependencies
139
```
140
141
#### Configuration Examples
142
143
```toml
144
[tool.poe.tasks]
145
# Simple expression
146
version = {expr = "open('VERSION').read().strip()"}
147
148
# Expression with imports
149
timestamp = {expr = "__import__('datetime').datetime.now().isoformat()"}
150
151
# Expression using environment
152
debug_info = {
153
expr = "f'Debug mode: {environ.get(\"DEBUG\", \"false\")}'",
154
env = {DEBUG = "true"}
155
}
156
```
157
158
### Sequence Tasks
159
160
Compose multiple tasks into sequential execution chains with dependency management.
161
162
```python { .api }
163
# Sequence task configuration
164
class SequenceTask:
165
sequence: list[str | dict] # List of tasks to execute
166
env: dict[str, str] # Environment variables
167
cwd: str # Working directory
168
help: str # Help description
169
deps: list[str] # Task dependencies
170
ignore_fail: bool # Continue on task failure
171
```
172
173
#### Configuration Examples
174
175
```toml
176
[tool.poe.tasks]
177
# Simple sequence
178
check = {sequence = ["format", "lint", "test"]}
179
180
# Sequence with inline tasks
181
build = {sequence = [
182
"clean",
183
{cmd = "python setup.py build"},
184
{script = "scripts:package"}
185
]}
186
187
# Sequence with failure handling
188
deploy = {
189
sequence = ["test", "build", "upload"],
190
ignore_fail = false
191
}
192
193
# Sequence with environment
194
full_test = {
195
sequence = ["unit_test", "integration_test"],
196
env = {TEST_MODE = "comprehensive"}
197
}
198
```
199
200
### Reference Tasks
201
202
Create task aliases and references for code reuse and organization.
203
204
```python { .api }
205
# Reference task configuration
206
class RefTask:
207
ref: str # Reference to another task
208
args: list[str] # Additional arguments
209
env: dict[str, str] # Environment variables
210
help: str # Help description
211
```
212
213
#### Configuration Examples
214
215
```toml
216
[tool.poe.tasks]
217
# Task reference/alias
218
t = {ref = "test"}
219
quick_test = {ref = "test", args = ["-x"]}
220
221
# Reference with environment override
222
test_debug = {
223
ref = "test",
224
env = {DEBUG = "true", VERBOSE = "1"}
225
}
226
```
227
228
### Switch Tasks
229
230
Conditional task execution based on the output of a control task, with different cases executed based on the control task's result.
231
232
```python { .api }
233
# Switch task configuration
234
class SwitchTask:
235
control: str | dict # Control task definition
236
switch: list[dict] # List of case definitions
237
default: Literal["pass", "fail"] = "fail" # Default behavior when no case matches
238
env: dict[str, str] # Environment variables
239
cwd: str # Working directory
240
help: str # Help description
241
deps: list[str] # Task dependencies
242
```
243
244
#### Configuration Examples
245
246
```toml
247
[tool.poe.tasks]
248
# Platform-based switching using control task
249
build = {
250
control = {expr = "sys.platform"},
251
switch = [
252
{case = "win32", cmd = "build_windows.bat"},
253
{case = "darwin", cmd = "./build_macos.sh"},
254
{case = "linux", cmd = "./build_linux.sh"},
255
{cmd = "echo 'Unsupported platform'"} # default case
256
]
257
}
258
259
# Environment-based switching
260
test = {
261
control = {expr = "environ.get('TEST_MODE', 'default')"},
262
switch = [
263
{case = "ci", cmd = "pytest --ci-mode"},
264
{case = "debug", cmd = "pytest -v -s"},
265
{cmd = "pytest"} # default case
266
]
267
}
268
```
269
270
### Task Options
271
272
Common configuration options available across all task types.
273
274
```python { .api }
275
# Base task options (available to all task types)
276
class TaskOptions:
277
help: str # Help text description
278
env: dict[str, str] # Environment variables
279
cwd: str # Working directory
280
deps: list[str] # Task dependencies
281
args: dict | list | None # Additional arguments
282
capture_stdout: str | None # Capture standard output to variable
283
envfile: str | list[str] # Environment file(s) to load
284
executor: dict # Executor configuration
285
uses: dict[str, str] # Task dependencies with outputs
286
verbosity: int | None # Verbosity level (-2 to 2)
287
288
# Task-specific options
289
class CmdTaskOptions(TaskOptions):
290
use_exec: bool = False # Use exec instead of subprocess
291
empty_glob: str = "pass" # Handle empty glob patterns ("pass", "null", "fail")
292
293
class ShellTaskOptions(TaskOptions):
294
interpreter: str | list[str] # Shell interpreter override
295
296
class ScriptTaskOptions(TaskOptions):
297
use_exec: bool = False # Use exec instead of subprocess
298
print_result: bool = False # Print function return value
299
300
class ExprTaskOptions(TaskOptions):
301
imports: list[str] = [] # Additional imports for expression
302
assert_: bool | int = False # Assert expression result
303
use_exec: bool = False # Use exec instead of subprocess
304
305
class SequenceTaskOptions(TaskOptions):
306
ignore_fail: str | bool = False # Continue on failure ("return_zero", "return_non_zero", True, False)
307
default_item_type: str # Default task type for sequence items
308
309
class SwitchTaskOptions(TaskOptions):
310
control: str | dict # Switch control expression/mapping
311
default: str = "fail" # Default behavior ("pass", "fail")
312
```
313
314
### Environment Variables
315
316
Tasks can define and use environment variables in multiple ways.
317
318
```python { .api }
319
# Environment variable handling
320
class EnvOptions:
321
# Task-level environment variables
322
env: dict[str, str]
323
324
# Global environment from .env file
325
env_file: str
326
327
# Environment variable interpolation in task definitions
328
# Supports: ${VAR}, $VAR, environ.get('VAR')
329
```
330
331
#### Configuration Examples
332
333
```toml
334
[tool.poe.tasks]
335
# Task with environment variables
336
deploy = {
337
cmd = "deploy.sh",
338
env = {
339
API_URL = "https://api.example.com",
340
API_KEY = "${API_KEY}", # From shell environment
341
DEBUG = "false"
342
}
343
}
344
345
# Global environment file
346
[tool.poe]
347
env_file = ".env"
348
349
# Environment variable in task definition
350
backup = {cmd = "backup.sh ${BACKUP_TARGET}"}
351
```
352
353
### Argument Handling
354
355
Tasks can accept and process command-line arguments in various ways.
356
357
```python { .api }
358
# Argument handling options
359
class ArgOptions:
360
args: list[str] # Predefined arguments
361
# CLI arguments are passed through to tasks automatically
362
# Access via: ${@}, ${1}, ${2}, etc. in shell tasks
363
# Access via: sys.argv in script tasks
364
```
365
366
#### Configuration Examples
367
368
```toml
369
[tool.poe.tasks]
370
# Task with predefined arguments
371
test = {cmd = "pytest", args = ["--verbose", "--color=yes"]}
372
373
# Task accepting CLI arguments
374
serve = "python -m http.server" # CLI args passed through
375
# Usage: poe serve 8080
376
377
# Script task with argument handling
378
process = {script = "scripts:process_data"}
379
# Usage: poe process input.json --format csv
380
```
381
382
### Task Dependencies
383
384
Tasks can declare dependencies that must complete successfully before execution.
385
386
```python { .api }
387
# Dependency configuration
388
class DependencyOptions:
389
deps: list[str] # Task dependencies
390
# Dependencies run in parallel when possible
391
# Cyclic dependencies are detected and reported
392
```
393
394
#### Configuration Examples
395
396
```toml
397
[tool.poe.tasks]
398
# Task with dependencies
399
deploy = {
400
cmd = "deploy.sh",
401
deps = ["test", "build"]
402
}
403
404
# Complex dependency chain
405
package = {
406
cmd = "package.sh",
407
deps = ["build"]
408
}
409
410
build = {
411
cmd = "build.sh",
412
deps = ["clean", "compile"]
413
}
414
415
test = {deps = ["lint", "unit_test", "integration_test"]}
416
```
417
418
## Task Inheritance
419
420
Tasks can inherit configuration from parent tasks, including working directory, verbosity level, and other options.
421
422
```python { .api }
423
# Task inheritance context
424
class TaskContext:
425
config: PoeConfig # Configuration object
426
cwd: str # Working directory (inherited)
427
io: PoeIO # IO handler (inherited)
428
ui: PoeUi # UI handler (inherited)
429
specs: TaskSpecFactory # Task specifications
430
verbosity: int # Verbosity level (inherited)
431
```
432
433
#### Inheritance Examples
434
435
```toml
436
[tool.poe.tasks]
437
# Parent task with configuration
438
parent = {
439
cmd = "echo 'Running parent'",
440
cwd = "src/",
441
verbosity = 1,
442
env = {PROJECT = "myapp"}
443
}
444
445
# Child tasks inherit parent context
446
child_sequence = {sequence = [
447
"parent", # Child inherits cwd=src/, verbosity=1, env
448
{cmd = "echo 'Running child'"} # Runs in inherited context
449
]}
450
```
451
452
## Usage Examples
453
454
### Simple Task Definitions
455
456
```toml
457
[tool.poe.tasks]
458
# Command tasks
459
test = "pytest"
460
lint = "flake8 src/"
461
format = "black ."
462
463
# Script tasks
464
build = {script = "build:main"}
465
docs = {script = "sphinx.cmd.build:build_main"}
466
```
467
468
### Complex Task Workflows
469
470
```toml
471
[tool.poe.tasks]
472
# Development workflow
473
dev = {sequence = [
474
"format",
475
"lint",
476
"test",
477
{cmd = "python -m myapp", env = {DEBUG = "true"}}
478
]}
479
480
# CI/CD pipeline
481
ci = {sequence = [
482
"clean",
483
"deps",
484
"lint",
485
"test",
486
"build",
487
"package"
488
]}
489
490
# Platform-specific builds
491
build = {
492
switch = {
493
"sys.platform == 'win32'" = {cmd = "build.bat"},
494
"sys.platform != 'win32'" = {cmd = "./build.sh"}
495
}
496
}
497
```
498
499
### Environment-Aware Tasks
500
501
```toml
502
[tool.poe.tasks]
503
# Development vs production
504
deploy = {
505
switch = {
506
"environ.get('ENVIRONMENT') == 'prod'" = {
507
cmd = "deploy-prod.sh",
508
env = {API_URL = "https://api.prod.com"}
509
}
510
},
511
default = {
512
cmd = "deploy-dev.sh",
513
env = {API_URL = "https://api.dev.com"}
514
}
515
}
516
517
# Debug mode tasks
518
test_debug = {
519
ref = "test",
520
env = {DEBUG = "1", VERBOSE = "1"}
521
}
522
```