Plugins

Poetryの機能を独自に変更または拡張したい場合、Poetryはプラグインの使用と構築をサポートします。

たとえば、あなたの環境が、大多数のユーザには適用されないPoetryの動作に特別な要件を課している場合や、ほとんどのユーザが望まない方法でPoetryで何かを達成したい場合などです。

このような場合には、特定のロジックを処理するプラグインを作成することを検討してください。

Creating a plugin

プラグインは、パッケージの一部としてコードを提供する通常のPythonパッケージであり、他のパッケージにも依存する場合があります。

Plugin package

プラグインパッケージはPoetryに依存し、pyproject.tomlファイルで適切なpluginを宣言する必要があります。

[tool.poetry]
name = "my-poetry-plugin"
version = "1.0.0"

# ...
[tool.poetry.dependencies]
python = "^3.7"
poetry = "^1.2"

[tool.poetry.plugins."poetry.plugin"]
demo = "poetry_demo_plugin.plugin:MyPlugin"

Generic plugins

すべてのプラグインは、poetry.plugins.Pluginインターフェースを実装するクラスを提供する必要があります。

プラグインのactivate()メソッドは、プラグインがロードされた後に呼び出され、Poetryのインスタンスとcleo.io.io.IOのインスタンスを受け取ります。

この2つのオブジェクトを使用すると、すべての設定を読み取ることができ、すべてのパブリック内部オブジェクトと状態を必要に応じて操作できます。

次に例を示します。

from cleo.io.io import IO

from poetry.plugins.plugin import Plugin
from poetry.poetry import Poetry


class MyPlugin(Plugin):

    def activate(self, poetry: Poetry, io: IO):
        io.write_line("Setting readme")
        poetry.package.readme = "README.md"
        ...

Application plugins

poetryスクリプトにコマンドやオプションを追加したい場合は、poetry.plugins.ApplicationPluginインターフェイスを実装するアプリケーションプラグインを作成する必要があります。

アプリケーションプラグインのactivate()メソッドは、プラグインがロードされた後に呼び出され、poetry.console.Applicationのインスタンスを受け取ります。

from cleo.commands.command import Command
from poetry.plugins.application_plugin import ApplicationPlugin


class CustomCommand(Command):

    name = "my-command"

    def handle(self) -> int:
        self.line("My command")

        return 0


def factory():
    return CustomCommand()


class MyApplicationPlugin(ApplicationPlugin):
    def activate(self, application):
        application.command_loader.register_factory("my-command", factory)

Note

コマンドを登録するには、次のようにします。

application.add(MyCommand())

ただし、実際にコマンドが呼び出されたときにコマンドのロードを延期するために、コマンドローダに新しいファクトリを登録することを強くお勧めします。

これは、Poetryのパフォーマンスを良好に保つのに役立ちます。

また、プラグインはプラグインパッケージのpyproject.tomlファイルでpoetry.application.pluginプラグインとして宣言する必要があります。

[tool.poetry.plugins."poetry.application.plugin"]
foo-command = "poetry_demo_plugin.plugin:MyApplicationPlugin"

Warning

プラグインは、Poetryのコアコマンドをいかなる方法でも削除または変更してはなりません。

Event handler

プラグインは、特定のイベントをリッスンし、必要に応じてそれらに対して動作することもできます。

このイベントはCleoによって起動され、cleo.events.console_eventsモジュールからアクセスできます。

COMMAND: このイベントでは、コマンドが実行される前にリスナーをアタッチすることができます。
SIGNAL: このイベントは、コマンドの実行が中断された後にいくつかのアクションを実行できるようにします。
TERMINATE: このイベントでは、コマンドの後にリスナーをアタッチできます。
ERROR: このイベントは、キャッチされなかった例外が発生したときに発生します。

アプリケーション・イベント・ハンドラーを実装する方法を見てみましょう。この例では、コマンドを実行する前に.envファイルから環境変数をロードする方法を説明します。

from cleo.events.console_events import COMMAND
from cleo.events.console_command_event import ConsoleCommandEvent
from cleo.events.event_dispatcher import EventDispatcher
from dotenv import load_dotenv
from poetry.console.application import Application
from poetry.console.commands.env_command import EnvCommand
from poetry.plugins.application_plugin import ApplicationPlugin


class MyApplicationPlugin(ApplicationPlugin):
    def activate(self, application: Application):
        application.event_dispatcher.add_listener(
            COMMAND, self.load_dotenv
        )

    def load_dotenv(
        self,
        event: ConsoleCommandEvent,
        event_name: str,
        dispatcher: EventDispatcher
    ) -> None:
        command = event.command
        if not isinstance(command, EnvCommand):
            return

        io = event.io

        if io.is_debug():
            io.write_line(
                "<debug>Loading environment variables.</debug>"
            )

        load_dotenv()

Using plugins

インストールされたプラグインパッケージは、Poetryの起動時に自動的にロードされます。

Poetryのプラグインは複数の方法でインストールできます。

With `pipx inject`

pipxを使ってPoetryをインストールした場合は、pipx injectコマンドでプラグインパッケージを追加できます。

pipx inject poetry poetry-plugin

アンインストールしたい場合は、以下で削除できます。

pipx uninject poetry poetry-plugin          # For pipx versions >= 1.2.0

pipx runpip poetry uninstall poetry-plugin  # For pipx versions  < 1.2.0

With `pip`

Poetryの仮想環境のpipバイナリは、プラグインのインストールと削除にも使用できます。ここでの環境変数$POETRY_HOMEは、仮想環境へのパスを表すために使われます。 Poetryがどこにインストールされているかわからない場合は、installation instructionsを参照してください。

プラグインを追加するには、pip installを使用します。

$POETRY_HOME/bin/pip install --user poetry-plugin

プラグインをアンインストールするには、次のコマンドを実行します。

$POETRY_HOME/bin/pip uninstall poetry-plugin

The `self add` command

Warinig

特にWindowsでは、self addとself removeが問題になる可能性があるので、他の方法が優先されるべきです。

poetry self add poetry-plugin

self addコマンドは、プラグインが現在のバージョンのPoetryと互換性があることを確認し、プラグインが動作するために必要なパッケージをインストールします。

self addコマンドでサポートされているパッケージ指定形式は、addコマンドでサポートされているものと同じです。

不要になったプラグインをアンインストールしたい場合は、self removeコマンドを使用できます。

poetry self remove poetry-plugin

次のコマンドを実行して、現在インストールされているすべてのプラグインを一覧表示することもできます。

poetry self show plugins

Maintaining a plugin

プラグインを作成する場合は、安定したパブリックAPIがないため、おそらくPoetryの内部にアクセスすることになるでしょう。最初にメソッドを非推奨にするように最善を尽くしていますが、削除する前に、内部メソッドのシグネチャを変更しなければならない場合があります。

プラグインの作成者として、おそらくプラグインをPoetryの最新リリースに対してテストしているでしょう。さらに、最新のリリースブランチとPoetryのメインブランチに対するテストを検討し、プラグインに変更を加えていない場合でも定期的に実行されるCIジョブをスケジュールする必要があります。こうすることで、プラグインを破壊する内部の変更にすぐに気付き、次のPoetryリリースに備えることができます。