Depending on how you manage your python environments you may also wish to use Poe the Poet in the form of a poetry plugin.
poetry self add 'poethepoet[poetry_plugin]'
Configuring the plugin#
By default the poetry plugin will register poe as a command prefix so tasks can be invoked like:
poetry poe [task_name] [task_args]
And the poe documentation can be viewed via:
It is also possible to modify this behavoir, to either have a different command prefix
or none at all by setting the
poetry_command global option in your
pyproject.toml like so:
[tool.poe] poetry_command = ""
In this case poe tasks will be registered as top level commands on poetry and can be invoked simply as:
tool.poe.poetry_command is set to must not already exist as a
Additionally if setting it to the emtpy string then care must be taken to avoid defining any poe tasks that conflict with any other built in or plugin provided poetry command.
Hooking into poetry commands#
It is also possible to configure a task to be run before or after a specific poetry
command by declaring the
poetry_hooks global option like so:
[tool.poe.poetry_hooks] pre_build = "prep-assets --verbosity=5" post_build = "archive-build" [tool.poe.tasks.prep-assets] script = "scripts:prepare_assets" help = "Optimise static assets for inclusion in the build" [tool.poe.tasks.archive-build] script = "scripts:archive_build" help = "Upload the latest build version to the archive server"
In this example the
prep-assets task will be run as the first step when calling
poetry build with an argument passed as if the task were being called via the
poe CLI. We’ve also configured the
archive-build task to be run after every
If a task fails when running as a hook, then the poetry command will exit with an error.
If it is a pre hook then this will cause the actual poetry command not to execute.
This behaviour may be useful for running checks before
Hooks can be disabled for a single invocation by passing the
Namespaced commands like
poetry env info can be specified with underscores like so:
[tool.poe.poetry_hooks] post_env_info = "info"
All poetry commands are supported in principle.
Due to how the poetry CLI works (using cleo — a featureful but highly opinionated CLI framework) there exist a few minor limitations to consider when using the Poe the Poet poetry plugin.
Normally the poe CLI allows tasks to accept any arguments, either by defining the expected options or by passing any command line tokens following the task name to the task at runtime. This is not supported by cleo. The plugin implements a workaround that mostly works, but still if the –no-plugins option is provided anywhere in the command line then the poe plugin will never be invoked.
Poetry comes with its own command line completion, which includes completion of task names but poe’s command line completion won’t work.
If you declare named arguments for your poe tasks then these are included in the documentation when poe is invoked without any arguments. However the inline documentation for poetry commands contains only the task names and help text.
Therefore it is generally recommended to use the poe CLI tool directly if you don’t mind having it installed onto your path.