poetry-pyinvoke-plugin

A plugin for poetry that allows you to invoke commands in your tasks.py file delegating to pyinvoke.

Heavily inspired by the work from keattang on the poetry-exec-plugin project.

• poetry-pyinvoke-plugin
• Installation
• Quickstart
• User Guide
  • Configuration
  • Command Line Usage
    • Quickstart
  • Detailed Command Usage
    • List All Tasks
    • Run a Task
    • Tasks with Arguments
      • Singular Positional Argument
      • Named Arguments
      • Multiple Named Arguments
    • Task Help
    • Plugin Help
    • Invoke Help
• Publishing
• Contributing

Installation

Installation requires poetry 1.6.0+. To install this plugin run:

pip install poetry-pyinvoke-plugin
# OR
poetry self add poetry-pyinvoke-plugin

For other methods of installing plugins see the poetry documentation.

Quickstart

See Configuration for details on how to setup a tasks.py file.

List all tasks:

poetry inv -- --list

Run a task:

poetry invoke lint
# OR
poetry inv lint

User Guide

Configuration

tasks.py

from invoke import task

@task
def lint(c):
  c.run("flake8")
  c.run("black --check .")

Command Line Usage

Quickstart

Then:

poetry inv -- --list

Example Output:

Invoke: invoke --list 

Available tasks:

  build      Build wheel.
  format     Autoformat code for code style.
  greeting   Example task that takes an argument for testing purposes.
  lint       Linting and style checking.
  test       Run test suite.

Run a task:

poetry invoke lint
# OR
poetry inv lint

You can use either poetry invoke or poetry inv. The rest of this documentation will use poetry inv.

Detailed Command Usage

List All Tasks

This uses -- to break the arguments to poetry and lets the remainder get passed to invoke.

Command:

poetry inv -- --list

Example Output:

Invoke: invoke --list 

Available tasks:

  build      Build wheel.
  format     Autoformat code for code style.
  greeting   Example task that takes an argument for testing purposes.
  lint       Linting and style checking.
  test       Run test suite.

---

Run a Task

Command:

poetry inv lint

Example Output:

Invoke: invoke lint 

All done! ✨ 🍰 ✨
3 files would be left unchanged.
Skipped 3 files
Success: no issues found in 2 source files

---

Tasks with Arguments

Singular Positional Argument

Command:

poetry inv greeting Loki

Example Output:

Invoke: invoke greeting Loki

Hello Loki, from Sylvie

Command:

poetry inv greeting -- Loki

Example Output:

Invoke: invoke greeting Loki

Hello Loki, from Sylvie

Named Arguments

Command:

poetry inv greeting -- --name Loki

Example Output:

Invoke: invoke greeting --name Loki

Hello Loki, from Sylvie

Command:

poetry inv greeting -- -n Loki

Example Output:

Invoke: invoke greeting -n Loki

Hello Loki, from Sylvie

Multiple Named Arguments

Command:

poetry inv greeting -- --name Loki --other Thor

Example Output:

Invoke: invoke greeting --name Loki --other Thor

Hello Loki, from Thor

Command:

poetry inv greeting -- -n Loki -o Thor

Example Output:

Invoke: invoke greeting -n Loki -o Thor

Hello Loki, from Thor

---

Task Help

This uses -- to break the arguments to poetry and lets the remainder get passed to invoke. It also uses --help positionally before the task command to get help for it.

Command:

poetry inv -- --help greeting

Example Output:

Invoke: invoke --help greeting

Usage: inv[oke] [--core-opts] greeting [--options] [other tasks here ...]

Docstring:
  Example task that takes an argument for testing purposes.

Options:
  -n STRING, --name=STRING
  -o STRING, --other=STRING

Plugin Help

Command:

poetry inv --help

Example Output:

Description:
  Delegate out to pyinvoke tasks specified in your tasks.py file

Usage:
  inv [options] [--] <cmd> [<arguments>...]

Arguments:
  cmd                        The command to run from your tasks.py.
  arguments                  Additional arguments to append to the command.

---

Invoke Help

This uses -- to break the arguments to poetry and lets the remainder get passed to invoke.

Command:

poetry inv -- --help

Example Output:

Invoke: invoke --help 

Usage: inv[oke] [--core-opts] task1 [--task1-opts] ... taskN [--taskN-opts]

---

Publishing

To publish a new version create a release from main (after pull request).

Contributing

At all times, you have the power to fork this project, make changes as you see fit and then:

pip install https://github.com/user/repository/archive/branch.zip

Stackoverflow: pip install from github branch

That way you can run from your own custom fork in the interim or even in-house your work and simply use this project as a starting point. That is totally ok.

However if you would like to contribute your changes back, then open a Pull Request "across forks".

Once your changes are merged and published you can revert to the canonical version of pip installing this package.

If you're not sure how to make changes or if you should sink the time and effort, then open an Issue instead and we can have a chat to triage the issue.