Global options#
The following options can be set for all tasks in a project directly under [tool.poe]
. These are called global options, in contrast with task options.
- env
Dict[str, str]
π Define environment variables to be exposed to all tasks. These can be extended on the task level.
- envfile
str
|List[str]
π Link to one or more files defining environment variables to be exposed to all tasks.
- executor
Dict[str, str]
π Override the default behavior for selecting an executor for tasks in this project.
- include
str
|List[str]
|Dict[str, str]
π Specify one or more other toml or json files to load tasks from.
- shell_interpreter
str
|List[str]
π Change the default interpreter to use for executing shell tasks.
- poetry_command
str
π Change the name of the task poe registers with poetry when used as a plugin.
- poetry_hooks
Dict[str, str]
π Register tasks to run automatically before or after other poetry CLI commands.
- verbosity
int
Set the default verbosity level for tasks in this project. The default value is
0
, providing the-v
global CLI option increases it by1
, whereas the-q
global CLI option decreases it by1
.- default_task_type
"cmd" | "expr" | "ref" | "script" | "shell"
When a task is declared as a string (instead of a table), then it is interpreted as the default task type, which will be
"cmd"
unless otherwise specified.- default_array_task_type
str
When a task is declared as an array (instead of a table), then it is interpreted as the default array task type, which will be
"sequence"
unless otherwise specified. Currently the sequence task type is the only one that can be defined as an array.- default_array_item_task_type
"cmd" | "expr" | "ref" | "script" | "shell"
When a task is declared as a string inside an array (e.g. inline in a sequence task), then it is interpreted as the default array item task type, which will be
"ref"
unless otherwise specified.
Global environment variables#
You can configure environment variables to be set for all poe tasks in the pyproject.toml file by specifying tool.poe.env
like so
[tool.poe.env]
VAR1 = "FOO"
VAR2 = "BAR BAR BLACK ${FARM_ANIMAL}"
The example above also demonstrates how β as with env vars defined at the task level β posix variable interpolation syntax may be used to define global env vars with reference to variables already defined in the host environment or in a referenced env file.
As with the task level option, you can indicated that a variable should only be set if not already set like so:
[tool.poe.env]
VAR1.default = "FOO"
You can also specify an env file (with bash-like syntax) to load for all tasks like so:
STAGE=dev
PASSWORD='!@#$%^&*('
[tool.poe]
envfile = ".env"
The envfile global option also accepts a list of env files.
Change the executor type#
You can configure poe to use a specific executor by setting
tool.poe.executor.type
. Valid values include:
auto: to automatically use the most appropriate of the following executors in order
poetry: to run tasks in the poetry managed environment
virtualenv: to run tasks in the indicated virtualenv (or else β./.venvβ if present)
simple: to run tasks without doing any specific environment setup
The default behaviour is auto.
For example the following configuration will cause poe to ignore the poetry environment (if present), and instead use the virtualenv at the given location relative to the parent directory.
[tool.poe.executor]
type = "virtualenv"
location = "myvenv"
Change the default shell interpreter#
Normally shell tasks are executed using a posix shell by default (see section for shell tasks above). This default can be overridden to something else by setting the shell_interpreter global option. In the following example we configure all shell tasks to use fish by default.
tool.poe.shell_interpreter = "fish"
[tool.poe.tasks.fibonacci]
help = "Output the fibonacci sequence up to 89"
shell = """
function fib --argument-names max n0 n1
if test $max -ge $n0
echo $n0
fib $max $n1 (math $n0 + $n1)
end
end
fib 89 1 1
"""
Default command verbosity#
You can alter the verbosity level for poe commands by passing --quiet
/
-q
(which decreases verbosity) or --verbose
/ -v
(which
increases verbosity) on the CLI.
If you want to change the default verbosity level for all commands, you can use
the tool.poe.verbose
option in pyproject.toml like so:
[tool.poe]
verbosity = -1
-1
is the quietest and 1
is the most verbose. 0
is the
default.
Note that the command line arguments are incremental: -q
subtracts one
from the default verbosity, and -v
adds one. So setting the default
verbosity to -1
and passing -v -v
on the command line is
equivalent to setting the verbosity to 0
and just passing -v
.
Change the default task type#
By default tasks defined as strings are interpreted as shell commands, and script tasks require the more verbose table syntax to specify. For example:
my_cmd_task = "cmd args"
my_script_task = { "script" = "my_package.my_module:run" }
This behaviour can be reversed by setting the default_task_type
option in your
pyproject.toml like so:
[tool.poe]
default_task_type = "script"
[tool.poe.tasks]
my_cmd_task = { "cmd" = "cmd args" }
my_script_task = "my_package.my_module:run"
Run poe from anywhere#
By default poe will detect when youβre inside a project with a pyproject.toml in the
root. However if you want to run it from elsewhere then that is supported by using the
--root
option to specify an alternate location for the toml file. The task will
run with the given location as the current working directory.
In all cases the path to project root (where the pyproject.toml resides) will be
available as $POE_ROOT
within the command line and process.