tomevault-io Edit Python Script
このスキルは、プロジェクト内での Python スクリプトの品質と現代的な記述を保証するためのガイドラインを提供します。スクリプトの新規作成だけでなく、既存スクリプトの修正やリファクタリング時にも適用してください。
1. 開発フロー
- 仕様の確認: 入力（引数）、処理内容、出力を明確にする。
- 実装: 後述の「コア要件」に従ってコードを記述・修正する。
- 品質検証:
ruffを使用して静的解析とフォーマットを行う。 - 動作確認: 実際にスクリプトを実行し、意図した動作をすることを確認する。
2. コア要件
2.1. CLI 設計 (argparse)
sys.argvを直接参照せず、必ずargparseモジュールを使用すること。- ツールが「検索 (search)」「閲覧 (view)」「作成 (create)」などの異なる複数のアクションを持つ場合は、サブコマンド (
subparsers) を活用し、dest="command"で制御することを推奨する。
2.2. 環境管理 (PEP 723)
- 全ての Python スクリプトの先頭に PEP 723 形式のインラインメタデータを記述し、
uv runで実行可能にすること。 dependenciesには、スクリプトが依存するライブラリを明記する。- 例:
# /// script # requires-python = ">=3.13" # dependencies = [ # "requests", # "beautifulsoup4", # ] # ///
2.3. 品質検証 (ruff)
- スクリプトの修正後は必ず以下のコマンドを実行し、エラーがないことを確認すること。
HOME=/home/node uvx ruff check --fix <script_path> HOME=/home/node uvx ruff format <script_path>
2.4. 単一責務の原則 (SRP)
- 1つの関数やクラスは、1つの明確な役割のみを持つように設計すること。
- ただし、ドキュメントやコメントに「責務」という単語を直接含めることは避け、簡潔かつ自然な説明を記述すること。
3. Rust-ish Python Rules (規律ある Python 記述)
Python の自由さに甘えず、Rust のような厳格さと安全性を持って記述するための追加ルールです。
3.1. "Map" ではなく "Struct" を
- キーが固定された辞書（例:
{"label": label, "url": url}）をデータの受け渡しに使用しないこと。 - データの構造が既知である場合、
dictは使用せず必ずdataclasses.dataclassを定義すること。 - 原則として
frozen=Trueを指定し、不変性（イミュータビリティ）を確保すること。
3.2. 静的型付けと現代的な型ヒント
- 全ての関数引数、戻り値、および複雑な変数宣言に型ヒントを記述すること。
Anyの使用は原則禁止とする。- 現代的な Python (3.9+) の記法を用い、
typingモジュールの古いエイリアス（List,Dict等）の使用を避ける（例:list[str],dict[str, int]）。 Optional[T]は使用せずT | None、Union[A, B]は使用せずA | Bと記述すること。
3.3. 変数の不変性 (Immutability)
- 基本的に変数は再代入せず、一度初期化したら変更しない（immutable）ものとして扱うこと。
- 状態を変更するのではなく、新しい値を計算して別の変数に割り当てる設計を優先すること。
3.4. 命令的ではなく宣言的に
- 手続き的なステップ（どうやるか）を記述するのではなく、リスト内包表記などを活用して「何であるか（宣言的）」を記述すること。
3.5. 構造化された Docstring
- 全ての関数に Docstring を記述すること。
- 特に、引数と戻り値の説明を明記すること。
4. 重要なルール
- 即時検証の義務: Python コードを変更した直後、他の作業（ユーザーへの報告を含む）を行う前に必ず Ruff による品質検証を実行すること。
- 実行による最終確認: スクリプトを修正または作成した後は、実際にスクリプトを実行し、正常に動作することを必ず確認すること。
- 妥協の禁止: Ruff がエラーを報告している間は、タスクの完了を報告してはならない。
- 再帰的修正: Ruff の指摘を修正するためにコードを変更した場合、再度 Ruff を実行して完全にクリーンな状態であることを確認すること。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.