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 import PoeThePoet

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

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

class ~pathlib.Path | str | None = None, config: ~typing.Mapping[str, ~typing.Any] | PoeConfig | None = None, output: ~typing.IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, poetry_env_path: str | None = None, config_name: str = 'pyproject.toml', program_name: str = 'poe')#
  • 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, defaults to “pyproject.toml”

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