ホーム Poetry ロゴ

プラグイン

プラグイン #

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

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

このような場合は、特定のロジックを処理するためのプラグインの作成を検討できます。

プラグインの作成 #

プラグインは、パッケージの一部としてコードを配布し、さらにパッケージに依存することもできる通常のPythonパッケージです。

プラグインパッケージ #

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

[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"

汎用プラグイン #

すべてのプラグインは、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"
        ...

アプリケーションプラグイン #

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)
注記

次の方法でコマンドを登録することができます。

application.add(MyCommand())

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

これにより、Poetryのパフォーマンスを良好に保つことができます。

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

[tool.poetry.plugins."poetry.application.plugin"]
foo-command = "poetry_demo_plugin.plugin:MyApplicationPlugin"
警告
プラグインは、Poetryのコアコマンドを削除または変更してはいけません。

イベントハンドラ #

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

これらのイベントは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()

プラグインの使用 #

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

Poetryのプラグインをインストールするには、複数の方法があります。

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

pipを使用 #

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

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

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

プラグインをアンインストールする場合は、次を実行できます。

$POETRY_HOME/bin/pip uninstall poetry-plugin

self addコマンド #

警告
特に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

プラグインのメンテナンス #

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

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