Grouping or namespacing tasks in a monorepo project

[MrSmiler]

Hi, I'm using poe in a huge monorepo project with many poe tasks and I was thinking about a namespacing tasks.
for example I have this folder hierarchy:

C:.
│   .gitignore
│   .python-version
│   main.py
│   pyproject.toml
│   README.md
│   tasks.toml
│   uv.lock
│   
├───app1
│       main.py
│       pyproject.toml
│       README.md
│       tasks.toml
│       
└───app2
        main.py
        pyproject.toml
        README.md
        tasks.toml

I have tasks.toml in the root of project and inside app1 and app2
poe-demo.zip
above file is the sample project.
and my pyproject.toml is like this:

[project]
name = "poe-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = []

[tool.uv.workspace]
members = [
    "app1",
    "app2",
]

[tool.poe]
executor.type = "uv"
include = [
    "tasks.toml",
    "app1/tasks.toml",
    "app2/tasks.toml",
]

what I would like to do is to run tasks inside the app1 and app2 like this:

$ poe app1 check-lint
$ poe app1 run
$ poe app2 check-lint
$ poe app2 run

what I imagine in it's implementation is something like this in pyproject.toml:

[project]
name = "poe-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = []

[tool.uv.workspace]
members = [
    "app1",
    "app2",
]

[tool.poe.includes] # for backward compatibility it's name is `includes`
root = "tasks.toml"
app1 = "app1/task.toml"
app2 = "app2/task.toml"

so what do you think ? also can you recommend approach that can be done with the current version of poe ?

[MrSmiler]

go task has such feature

[nat-n]

Hi @MrSmiler, I've also encountered this use case but hadn't thought about solutions in much detail.

I like your idea of explicitly namespacing imported (or inline) tasks. Maybe namespace or group should be an option on the include?

In the mean time you can get halfway there but just creating a task that calls poe in the subproject. What's missing is that if you want tasks to be documented at the top level you have to document them explicitly.

The simple way:

[tool.poe.task.app1]
cmd = "poe"
cwd = "./app1"  
executor = "simple"  # this ensures no venv conflict in case there isn't a shared workspace, but may require that poethepoet is [installed globally](https://poethepoet.natn.io/installation.html)

Or if you want all tasks to be documented at the top level you can declare them all

[tool.poe.task.app1-run]
cmd = "poe run --log_level ${log_level}"
cwd = "./app1"  
executor = "simple"
args = ["log_level"] # also replicate task args config if you like

[tool.poe.task.app1-check-lint]
cmd = "poe check-list"
cwd = "./app1"  
executor = "simple"

Another approach that might be even better if you have the same task repeated in each subproject anyway would be to declare the repeated tasks in a python module, the poethepoet-tasks library can help with this. This is a very powerful approach though of course it breaks with the usual config based task declaration paradigm. You can import the tasks from the module into each subpackage like so:

[tool.poe]
include_script = "my_tasks:tasks()"

and then make the tasks function parametrizable to accept a set of namespaces or whatever to create the subproject when including it in the root project:

[tool.poe]
include_script = "my_tasks:tasks(subprojects=['app1', 'app2'])"