Poe the Poet supports several ways of defining tasks under
[tool.poe.tasks], trading off simplicity against configurability. Furthermore toml syntax supports both more terse or more expressive alternative ways of writing the same thing, see the guide on Using toml syntax for details.
A task defined as a string will by default be interpreted as a single command to be executed without a shell (aka a cmd task).
[tool.poe.tasks] test = "pytest"
[tool.poe.tasks] test = "pytest" _build = "poetry build" build = ["test", "_build"] # this task runs the two referenced tasks in sequence
Task with names starting with an underscore
_ are excluded from documentation and cannot be run directly from the command line. They can only be run when referenced by another task.
Tasks can also be defined as sub-tables, which allows for specifying the task type and various configuration options on the task. The type of a task defined as a table is determined by the presence of a particular key that is unique to a certain task type and corresponds to the name of the task type.
[tool.poe.tasks.test-quick] help = "Run tests excluding those makes as slow." cmd = "pytest -m \"not slow\"" # here the cmd key identifies the task type and content
This implies that you can also define tasks of other types on a single line, like so:
[tool.poe.tasks] tunnel.shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &" } # (posix) shell based task
Top level tasks are defined as members of
[tool.poe.tasks], but sometimes tasks can be defined as children of other tasks, for example as items within a sequence task, or as the
case roles with a switch task.
Types of task#
You can define seven different types of task:
cmd: for simple commands that are executed as a subprocess without a shell
script: for python function calls
shell: for scripts to be executed with via an external interpreter (such as sh).
sequence: for composing multiple tasks into a sequence
expr: which consist of a python expression to evaluate
switch: for running different tasks depending on a control value (such as the platform)
ref: for defining a task as an alias of another task, such as in a sequence task.