Using poethepoet as a library

Normally poethepoet would be installed as a tool or poetry plugin, but it can also be used as a library to embed task runner capabilities into another tool.

The following script replicates the main functionality of the poe standalone cli.

import sys

from poethepoet.app import PoeThePoet


if __name__ == "__main__":
    app = PoeThePoet()
    result = app(cli_args=sys.argv[1:])
    if result:
        sys.exit(result)

The PoeThePoet class accepts various optional arguments to customize its behavior as described below.

class poethepoet.app.PoeThePoet(cwd: Path | str | None = None, config: Mapping[str, Any] | PoeConfig | None = None, output: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, poetry_env_path: str | None = None, config_name: str | None = None, program_name: str = 'poe', env: Mapping[str, str] | None = None, suppress_args: Sequence[str] = ('legacy_project_root', ))
Parameters:

  • cwd (Path, optional) – The directory that poe should take as the current working directory, this determines where to look for a pyproject.toml file, defaults to Path().resolve()

  • config (dict | PoeConfig, optional) – Either a dictionary with the same schema as a pyproject.toml file, or a PoeConfig object to use as an alternative to loading config from a file.

  • output (IO, optional) – A stream for the application to write its own output to, defaults to sys.stdout

  • poetry_env_path (str, optional) – The path to the poetry virtualenv. If provided then it is used by the PoetryExecutor, instead of having to execute poetry in a subprocess to determine this.

  • config_name (str, optional) – The name of the file to load tasks and configuration from. If not set then poe will search for config by the following file names: pyproject.toml poe_tasks.toml poe_tasks.yaml poe_tasks.json

  • program_name (str, optional) – The name of the program that is being run. This is used primarily when outputting help messages, defaults to “poe”

  • env (dict, optional) – Optionally provide an alternative base environment for tasks to run with. If no mapping is provided then os.environ is used.

  • suppress_args (Sequence[str], optional) – A sequence of identifiers for global arguments that should not be displayed in the help message.