Poetryプラグイン開発入門：独自の依存関係バリデーションでチームの品質を担保する
テックリードとして複数のPythonプロジェクトを統括していると、ある「絶望的な瞬間」に直面することがあります。それは、CI/CDパイプラインが回る直前、あるいは最悪の場合、ステージング環境へのデプロイ後に発覚する「脆弱性を持つライブラリの混入」や「社内ニッチなプライベートパッケージのバージョン不整合」です。
「レビュー時に気づけ」と言うのは簡単ですが、人間の目によるコードレビューには限界があります。`pyproject.toml` の数行の変更を、人間が常にセキュリティポリシーと照らし合わせてチェックし続けるのは非現実的です。
ここで、世の中の一般的なCIツールに依存する前に、「開発者の手元（Local）」の段階で不正な依存関係を弾き返す防波堤を作れたとしたらどうでしょう？
本記事では、Poetryの強力なプラグインアーキテクチャを活用し、「特定のセキュリティポリシーやパッケージバージョン制限をプロジェクトに強制する独自の依存関係バリデーションツール」をゼロから構築する方法を解説します。CI/CDの前にブロックする、プロフェッショナルな品質担保の仕組みを共に実装しましょう。
—
1. なぜPoetryプラグインなのか？（アーキテクチャの背景）
Python界隈では `pip` や `uv` など、高速なパッケージマネージャーが台頭しています。しかし、エンタープライズなチーム開発において、Poetryが今なお強力な選択肢であり続ける理由は、その拡張性の高さ（Plugin Architecture）にあります。
Poetryは内部で `cleo`（CLIフレームワーク）や `poetry-core` を用いて構築されており、イベント駆動型のフック機構を持っています。これを利用することで、`poetry add` や `poetry install` といったコマンドのライフサイクルに独自の処理を割り込ませることができます。
外部スクリプトではなく「プラグイン」を作るべき理由
- UXの統合: 開発者は別のスクリプト（例: `python scripts/check_deps.py`）を叩く必要がありません。いつも通り `poetry lock` や `poetry install` を叩くだけで、暗黙的にバリデーションが走ります。
- 配布の容易さ: 社内PyPIやGitリポジトリ経由でチームメンバーに一発でインストール（`poetry self add`）できます。
- 依存コンテキストへのアクセス: Poetryの内部オブジェクト（`Pool`, `Constraint`, `LockedRepository` など）に直接アクセスできるため、依存関係解決木（Dependency Tree）を精密に解析可能です。
—
2. 開発環境を極限まで加速するプロの技
プラグイン開発や日々のPoetry運用をストレスフリーで行うために、テックリードとしてチームに強制している環境設定と隠しコマンドを共有します。
必須の「神プラグイン」
環境構築の初手で以下のプラグインは必ずグローバルに導入しています。
1. `poetry-plugin-shell`: プロジェクトごとに仮想環境のアクティベートを意識させない（Poetry 2.0以降では標準化の方向ですが、1.x系では必須）。
2. `poetry-plugin-up`: `pyproject.toml` のバージョン制約を保ったまま対話的に安全なアップデートを行う。
グローバル環境へのプラグイン一括導入コマンド
poetry self add poetry-plugin-shell poetry-plugin-up
チーム開発で絶対共有すべき `pyproject.toml` の設定ルール
ローカル環境とCIで依存関係の挙動がズレる最大の原因は、仮想環境の作成場所やキャッシュの扱いです。以下の設定をプロジェクトのルートに必ず配置してください。
[tool.poetry]
パッケージ名や説明
name = “enterprise-service”
version = “1.0.0”
description = “High-performance backend service with strict policy enforcement”
authors = [“DevOps Team
[tool.poetry.dependencies]
python = “^3.11”
原則として厳密なバージョンピン、あるいは安全なキャレット要件を強制
fastapi = “>=0.100.0,<0.110.0"
pydantic = "^2.0.0"
[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^23.0.0"
[tool.poetry.virtualenvs]
仮想環境をプロジェクト配下の .venv に強制作成（IDE連携とコンテナ化を容易にする）
in-project = true
存在しない場合は自動作成
create = true
[tool.poetry.cache-dir]
キャッシュディレクトリをCI間で共有しやすいように明示的に設計（必要に応じて環境変数で上書き）
---
3. 実践：独自の依存関係バリデーション・プラグインの作成
ここからが本題です。`poetry add` や `poetry install` が実行された際に、以下のポリシーを強制するカスタムプラグイン `poetry-policy-enforcer` を作成します。
バリデーションポリシーの要件
1. 禁止パッケージの検出: セキュリティ上、社内で利用が禁止されているパッケージ（例: `requests` の代わりに `httpx` を強制するため、`requests` の混入を検知）が含まれていないか。
2. バージョン範囲の強制: 特定のライブラリ（例: `django`）を使う場合、脆弱性のある古いバージョン（例: `<4.2`）が含まれていないか。
ディレクトリ構造
プラグインは独立したPythonパッケージとして作成し、Poetryのプラグインシステムにエントリーポイントで登録します。
poetry-policy-enforcer/
├── pyproject.toml
└── poetry_policy_enforcer/
├── __init__.py
└── plugin.py
1. プラグイン側の `pyproject.toml`
Poetryに「これはプラグインである」と認識させるためのエントリーポイント（`poetry.application.plugin`）を定義します。
[tool.poetry]
name = “poetry-policy-enforcer”
version = “0.1.0”
description = “Custom Poetry plugin to enforce internal dependency policies.”
authors = [“TechLead
packages = [{ include = “poetry_policy_enforcer” }]
[tool.poetry.dependencies]
python = “^3.11”
poetry = “^1.5.0″ # 依存するPoetryのバージョン
[tool.poetry.plugins.”poetry.application.plugin”]
エントリーポイントの定義：Poetry起動時にこのクラスがロードされる
policy-enforcer = “poetry_policy_enforcer.plugin:PolicyEnforcerPlugin”
[build-system]
requires = [“poetry-core”]
build-backend = “poetry.core.masonry.api”
2. プラグインの実装コード (`poetry_policy_enforcer/plugin.py`)
イベントリスナーを利用し、Poetryのコマンド実行ライフサイクルに割り込みます。
import sys
from cleo.events.event import Event
from cleo.events.console_events import COMMAND
from cleo.events.console_command_event import ConsoleCommandEvent
from poetry.plugins.application_plugin import ApplicationPlugin
from poetry.application import Application
class PolicyEnforcerPlugin(ApplicationPlugin):
“””
Poetryのアプリケーション起動時にフックし、
特定のコマンド（add, install, lock）の実行前に依存関係のポリシーチェックを走らせるプラグイン。
“””
# 禁止するパッケージのブラックリスト（実務では外部の設定ファイルや環境変数から読み込むことも可能）
FORBIDDEN_PACKAGES = {“requests”, “urllib3”}
# 特定のパッケージに対する最小バージョンの強制など
RESTRICTED_PACKAGES = {
“pydantic”: “2.0.0”
}
def activate(self, application: Application) -> None:
# コマンド実行前のイベントにリスナーを登録
application.event_dispatcher.addListener(COMMAND, self.enforce_policies)
def enforce_policies(self, event: ConsoleCommandEvent, event_name: str, dispatcher) -> None:
command = event.command
command_name = command.name
# 対象とするPoetryコマンドを限定（add, install, update など）
target_commands = {“add”, “install”, “update”, “lock”}
if command_name not in target_commands:
return
io = event.io
io.write_line(“
# Poetryの現在のプロジェクト設定（pyproject.toml）を取得
try:
poetry = command.poetry
locker = poetry.locker
# ロックファイルが存在しない場合（初期化直後など）はスキップ、または警告
if not locker.is_locked():
io.write_line(“
return
locked_repository = locker.locked_repository()
packages = locked_repository.packages
# 1. ブラックリストパッケージの検知
for package in packages:
pkg_name = package.name.lower()
if pkg_name in self.FORBIDDEN_PACKAGES:
io.write_line(f”
io.write_line(“
# 違反がある場合はプロセスを強制終了し、コマンドの実行をブロック
sys.exit(1)
io.write_line(“
except Exception as e:
# 予期せぬエラーの場合も安全のためブロックするか、ログを出力する
io.write_line(f”
sys.exit(1)
—
4. チームへの導入とCI/CDパイプラインでの運用
開発者がローカル環境でこのプラグインを入れている前提はもちろんですが、CI/CD環境（GitHub Actionsなど）でも確実にこのバリデーションが機能する状態を担保する必要があります。
ローカル開発者へのプラグイン配布手順
社内用プライベートレジストリ、あるいはローカルのホイール（wheel）ファイルからプラグインをインストールさせます。
プラグインのビルド
poetry build
開発者のローカル環境へプラグインとして追加
poetry self add ./dist/poetry_policy_enforcer-0.1.0-py3-none-any.whl
GitHub Actionsでの防波堤構築（YAML設定例）
CI/CDパイプライン上では、`poetry install` や `poetry lock` が実行された瞬間、自動的にプラグインがロードされ、ブラックリストに含まれるパッケージが存在すればビルドが即座に失敗（Exit Code 1）します。
name: Backend CI / Policy Validation
on:
push:
branches: [ “main”, “develop” ]
pull_request:
branches: [ “main” ]
jobs:
validate-and-test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: “3.11”
- name: Install Poetry
uses: snok/install-poetry@v1
with:
version: 1.8.2
virtualenvs-create: true
virtualenvs-in-project: true
# 【重要】社内ポリシー・バリデーションプラグインのCI環境への導入
# 実際には社内PyPIやGitHub Packagesから `poetry self add` する形に拡張します
- name: Install Custom Policy Enforcer Plugin
run: |
# ここではローカルにあるプラグインソースを直接インストールする例
pip install ./poetry-policy-enforcer
poetry self add ./poetry-policy-enforcer
- name: Load Cached Dependencies
uses: actions/cache@v3
with:
path: .venv
key: venv-${{ runner.os }}-${{ hashFiles(‘/poetry.lock’) }}
# この `poetry install` の裏側で、作成したプラグインのバリデーションロジックが走ります
- name: Install Dependencies & Run Policy Check
run: |
poetry install –no-interaction –no-root
- name: Run Test Suite
run: |
poetry run pytest
—
5. テックリードからの実践アドバイス：運用上の注意点
このカスタムプラグインを導入した現場を運用する中で、いくつか陥りがちな罠と対策を共有します。
1. 例外処理の重要性
プラグイン内で予期せぬ例外（ネットワークエラーやパースエラーなど）が発生した際、`sys.exit(1)` で雑に落とすと、開発者が緊急のバグ修正を行っている最中にPoetry自体が一切動かなくなる「デッドロック状態」に陥ります。例外時は詳細なログを出力しつつ、必要に応じて環境変数（例: `BYPASS_POLICY_CHECK=true`）で一時的にバイパスできる退避ルートを用意しておくと、開発現場のフラストレーションを溜めずに済みます。
2. ポリシーの外部化
ブラックリストやバージョン制約をプラグインのコード内にハードコーディングすると、ルール変更のたびにプラグイン自体のバージョンを上げ、全開発者に `self update` を強いることになります。実務では、プロジェクトの `pyproject.toml` の `[tool.poetry.plugin.policy]` セクションから設定値を読み込む設計にリファクタリングすることをお勧めします。
結びにかえて
インフラやセキュリティのルールを「ドキュメントや規約」として残す時代は終わりました。規約は読まれないものであり、人間の記憶は曖昧です。
Poetryのプラグイン開発を通じて「開発者の日常的なワークフローの中にルールを強制的に組み込む仕組み」を作ることで、チームのコード品質は劇的に、そして持続的に向上します。ぜひ、あなたの組織のセキュリティポリシーに合わせた独自のバリデーションを実装し、強固な防波堤を築き上げてください。