外掛程式
外掛 #
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 的實例。
使用這兩個物件，就可以讀取所有設定檔，並能依需要來操作所有公開的內部物件和狀態。
範例
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 的效能。
外掛模組也必須在 plugin 軟體套件的 pyproject.toml 檔案中，宣告為 poetry.application.plugin 外掛模組
[tool.poetry.plugins."poetry.application.plugin"]
foo-command = "poetry_demo_plugin.plugin:MyApplicationPlugin"
事件處理常式 #
外掛模組也可以監聽特定事件，並在必要時採取動作。
這些事件是由 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 指令碼 #
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
維護外掛程式 #
當撰寫外掛程式時，你可能需要存取 Poetry 的內部運作，因為沒有穩定的公開 API。儘管我們會盡力先棄用方法後再將它們移除，但有時需要變更內部方法的簽章。
作為外掛程式的作者，你可能需要針對 Poetry 的最新版本測試你的外掛程式。此外，你也應該考慮針對 Poetry 的最新發行分支和主要分支進行測試，並排定定期執行的 CI 作業，即使你沒有對你的外掛程式進行任何變更。這樣一來，你就能立即發現會損壞你的外掛程式的內部變更，並為下一個 Poetry 版本做好準備。