python-packaging

出典に関する声明：wshobson/agents の内容を基にしています （MIT License、Copyright (c) 2024 Seth Hobson。ライセンス全文は同じディレクトリの LICENSE.txt をご覧ください）。 使用、変更、再配布は MIT ライセンスの条項に従い、著作権表示を保持する必要があります。

日本語の説明

このスキルでは、フルスタック開発に関連するベストプラクティスとパターンをガイドします。

---

name: python-packaging description: 適切なプロジェクト構成、setup.py/pyproject.toml、PyPI への公開により、配布可能な Python パッケージを作成します。Python ライブラリのパッケージ化、CLI ツールの作成、Python コードの配布に使用します。

Python のパッケージ化

最新のパッケージ化ツール、pyproject.toml、PyPI への公開を使用して Python パッケージを作成、構成、配布するための包括的なガイドです。

このスキルを使用する場面

• 配布用の Python ライブラリを作成する
• エントリーポイントを備えたコマンドラインツールを構築する
• PyPI またはプライベートリポジトリにパッケージを公開する
• Python プロジェクトの構成を設定する
• 依存関係を含むインストール可能なパッケージを作成する
• wheel とソースディストリビューションをビルドする
• Python パッケージのバージョン管理とリリースを行う
• 名前空間パッケージを作成する
• パッケージのメタデータと分類子を実装する

基本概念

1. パッケージ構成

• ソースレイアウト：src/package_name/（推奨）
• フラットレイアウト：package_name/（よりシンプルですが、柔軟性は低くなります）
• パッケージのメタデータ：pyproject.toml、setup.py、または setup.cfg
• 配布形式：wheel（.whl）とソースディストリビューション（.tar.gz）

2. 最新のパッケージ化標準

• PEP 517/518：ビルドシステムの要件
• PEP 621：pyproject.toml でのメタデータ
• PEP 660：編集可能インストール
• pyproject.toml：設定の単一の情報源

3. ビルドバックエンド

• setuptools：従来から広く使用されています
• hatchling：最新の、明確な方針を持つツール
• flit：軽量で、純粋な Python 向け
• poetry：依存関係管理とパッケージ化

4. 配布

• PyPI：Python Package Index（公開）
• TestPyPI：本番環境への公開前のテスト
• プライベートリポジトリ：JFrog、AWS CodeArtifact など

クイックスタート

最小限のパッケージ構成

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
└── tests/
    └── test_module.py

最小限の pyproject.toml

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "0.1.0"
description = "A short description"
authors = [{name = "Your Name", email = "[email protected]"}]
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=22.0",
]

パッケージ構成のパターン

パターン 1：ソースレイアウト（推奨）

my-package/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       ├── utils.py
│       └── py.typed          # For type hints
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/
    └── index.md

メリット：

• ソースから誤ってインポートするのを防ぐ
• テストでのインポートがより整理される
• 分離性が高まる

ソースレイアウト用の pyproject.toml：

[tool.setuptools.packages.find]
where = ["src"]

パターン 2：フラットレイアウト

my-package/
├── pyproject.toml
├── README.md
├── my_package/
│   ├── __init__.py
│   └── module.py
└── tests/
    └── test_module.py

よりシンプルですが：

• インストールせずにパッケージをインポートできる
• ライブラリではプロフェッショナルさに欠ける

パターン 3：複数パッケージのプロジェクト

project/
├── pyproject.toml
├── packages/
│   ├── package-a/
│   │   └── src/
│   │       └── package_a/
│   └── package-b/
│       └── src/
│           └── package_b/
└── tests/

詳細なパターンと実例

詳細なパターンのドキュメントは references/details.md にあります。上記のナビゲーション階層だけでは不十分な場合は、このファイルをお読みください。

対応範囲

✅ 得意なこと

• フルスタック開発に関連するベストプラクティス
• コードアーキテクチャ設計のガイダンス
• パフォーマンス最適化の提案

⚠️ 必要な情報

• プロジェクトの具体的な背景
• 技術スタックの情報

❌ 対応範囲外

• 技術以外の分野におけるビジネス上の意思決定
• 具体的なコードの実装（ガイダンスのみを提供）

ワークフロー

Step 1：要件分析

プロジェクトの要件と技術的な制約を理解します

Step 2：アーキテクチャ設計

システムアーキテクチャとコンポーネントの分割を設計します

Step 3：実装ガイダンス

具体的な実装の提案とコードパターンを提示します

Step 4：コードレビュー

コードの品質とベストプラクティスへの準拠状況をレビューします

Step 5：最適化の提案

パフォーマンス最適化と改善の提案を行います

注意点

1. 過剰設計

シンプルなケースで複雑な設計パターンを使用しないようにします

2. パフォーマンスの軽視

特に本番環境では、パフォーマンスの最適化を軽視しないでください

3. セキュリティへの配慮

常にセキュリティとデータ保護を考慮してください

4. テストカバレッジ

特に境界ケースで、十分なテストカバレッジを確保してください

5. ドキュメントの保守

ドキュメントをコードと同期して更新し続けてください