Loading tasks from another file

There are some scenarios where one might wish to define tasks outside of pyproject.toml, or to collect tasks from multiple projects into one. For example, if you want to share tasks between projects via git modules, generate tasks definitions dynamically, organise your code in a monorepo, or simply have a lot of tasks and don’t want the pyproject.toml to get too large. This can be achieved by creating a toml or json file including the same structure for tasks as used in pyproject.toml

For example:

# pyproject.toml

[tool.poe]
include = "modules/acme_common/shared_tasks.toml" # include tasks from a git submodule

# acme_common/shared_tasks.toml

[tool.poe.tasks.build-image]
cmd = "docker build"

Imported files may also specify environment variables via tool.poe.envfile or entries for tool.poe.env.

Tip

If a referenced file is missing then poe ignores it without error, though failure to read the contents will result in failure.

Including multiple files

It’s also possible to include tasks from multiple files by providing a list like so:

[tool.poe]
include = ["modules/acme_common/shared_tasks.toml", "generated_tasks.json"]

Files are loaded in the order specified. If an item already exists then the included value is ignored.

If an included task file itself includes other files, these second order includes are not inherited, so circular includes are not a concern.

Setting a working directory for included tasks

When including files from another location, you can also specify that tasks from that other file should be run from within a specific directory. For example with the following configuration, when tasks imported from my_subproject are run from the root, the task will actually execute as if it had been run from the my_subproject subdirectory.

[[tool.poe.include]]
path = "my_subproject/pyproject.toml"
cwd  = "my_subproject"

The directory indicated by the cwd option will also be used as the base directory for global or task level envfile imports for tasks defined within an included file.

Tasks and config in an included file can access the cwd value via the POE_CONF_DIR environment variable. When no cwd is set on the include then POE_CONF_DIR refers the to the parent directory of the config file where a task is defined.

You can still specify that an envfile referenced within an included file should be imported relative to the main project root, using the POE_ROOT environment variable like so:

[tool.poe]
envfile = "${POE_ROOT}/.env"