`expr` tasks#

Expr tasks consist of a single python expression. Running the task evaluates the expression and outputs the resulting value. Here’s a trivial example of an expr task that will print 2 when run:

[tool.poe.tasks.trivial-example]
expr = "1 + 1"

$ poe trivial-example
Poe => 1 + 1
2

Expressions can:

use most python expression constructs with the exception of yield, await, or named expressions
use most builtin functions including all members of this collection
reference the sys module module without having to specify it as an import
directly access whatever arguments were passed to the task from sys.argv
reference values of named args as python variables
include environment variables as string values that are injected into the expression using the usual templating syntax ${...}

Available task options#

expr tasks support all of the standard task options.

The following options are also accepted:

importsList[str] 📖: A list of modules to import for use in the expression.
assertbool 📖: If set to true and the result of the expression is found to be a falsey value then the task will fail with a non-zero return value.

Referencing arguments and environment variables#

The expression can reference environment variables using templating syntax as in cmd tasks, and named arguments as python variables in scope as in script tasks.

[tool.poe.tasks.venv-active]
expr = """(
  f'{target_venv} is active'
  if ${VIRTUAL_ENV}.endswith(target_venv)
  else f'{target_venv} is not active'
)"""
args = [{ name = "target-venv", default = ".venv", positional = true }]

$ poe venv-active poethepoet-LCpCQf8S-py3.10
Poe => (
  f'{target_venv} is active'
  if ${VIRTUAL_ENV}.endswith(target_venv)
  else f'{target_venv} is not active'
)
poethepoet-LCpCQf8S-py3.10 is not active

In this example the VIRTUAL_ENV environment variable is templated into the expression using the usual templating syntax, and the target_venv argument is referenced directly as a variable.

Notice that the expression may be formatted over multiple lines, as in normal python code.

Referencing imported modules in an expression#

By default the sys module is available to the expression which allows access to sys.argv or sys.platform among other useful values. However you can also reference any other importable module via the imports option as in the following example.

[tool.poe.tasks.count-hidden]
help    = "Count hidden files or subdirectories"
expr    = "len(list(pathlib.Path('.').glob('.*')))"
imports = ["pathlib"]

Fail if the expression result is falsey#

The expression can be made to behave like an assertion that fails if the result is not truthy by providing the assert option. The task defined in the following example will return non-zero if the result is False.

[tool.poe.tasks.venv-active]
expr   = "${VIRTUAL_ENV}.endswith(target_venv)"
assert = true
args   = [{ name = "target-venv", default = ".venv", positional = true }]

Referencing the result of other tasks in an expression#

Expr tasks can reference the results of other tasks by leveraging the uses option.

[tool.poe.tasks._get_active_session]
cmd = "read_session --format json"

[tool.poe.tasks.show-user]
expr    = """(
  f"User: {json.loads(${SESSION_JSON})['User']}"
  if len(${SESSION_JSON}) > 2
  else "No active session."
)"""
uses    = { SESSION_JSON = "_get_active_session" }
imports = ["json"]

expr tasks#