python-playground のエージェントガイドライン

このドキュメントは、python-playground リポジトリ内で動作するエージェントコーディングエージェントの規約、コマンド、およびベストプラクティスを概説します。これらのガイドラインに従うことで、一貫性、保守性、および効率的なコラボレーションが保証されます。

1. ビルド、リント、テストコマンド

このプロジェクトは、プロジェクトメタデータに pyproject.toml を使用しています。特定のスクリプトは定義されていませんが、一般的なPython開発プラクティスに基づいて、以下のコマンドを推奨します。

注意: 以下のツール (ruff、black、pytest、build) は、まだ存在しない場合、グローバルまたはプロジェクト固有の仮想環境にインストールする必要があるかもしれません。pip を使用してインストールできます。

pip install ruff black pytest build

1.1. ビルドコマンド

• プロジェクト配布物のビルド (sdist および wheel):

  python -m build
  

  このコマンドは、dist/ ディレクトリにソースおよびホイール配布パッケージを作成します。

1.2. リンティングとフォーマット

• Ruff を使用してすべての Python ファイルをリントする:

  python -m ruff check .
  

  このコマンドは、プロジェクト全体で一般的なエラーやスタイル違反を検出するために高速なリンティングを実行します。

• Black を使用してすべての Python ファイルを自動的にフォーマットする:

  python -m black .
  

  このコマンドは、すべての Python ファイルを Black の独自のスタイルに準拠するように再フォーマットします。Black が再フォーマットする可能性のある問題を Ruff が修正することを望む場合は、black の前に ruff --fix を実行することをお勧めします。

• 自動修正で Ruff を実行する:

  python -m ruff check . --fix
  

  このコマンドは、Ruff によって検出されたリンティングの問題を自動的に修正しようとします。

1.3. テストコマンド

• Pytest を使用してすべてのテストを実行する:

  python -m pytest
  

  このコマンドは、プロジェクト内のすべてのテストを検出し、実行します。

• 特定のファイル内のテストを実行する:

  python -m pytest <path/to/test_file.py>
  

  例: python -m pytest tests/test_example.py

• ファイル内の単一のテスト関数を実行する:

  python -m pytest <path/to/test_file.py>::<test_function_name>
  

  例: python -m pytest tests/test_example.py::test_addition

• 詳細な出力と失敗したテストの詳細を表示してテストを実行する:

  python -m pytest -v -s --tb=short
  

  失敗したテストのデバッグに役立ちます。

2. コードスタイルガイドライン

このセクションでは、このPythonプロジェクト内で従うべき一般的なコードスタイルガイドラインを概説します。

2.1. 一般原則

• PEP 8 への準拠: Pythonコードのスタイルガイドである PEP 8 に従ってください。ruff のようなリンターや black のようなフォーマッターを使用して、その多くを自動的に強制します。
• 可読性: 明確で簡潔で読みやすいコードを優先します。
• 一貫性: 既存のコードパターンとスタイルとの一貫性を維持します。

2.2. インポート

• 順序: インポートは、一般的に次の順序でグループ化する必要があります。
  1. 標準ライブラリのインポート。
  2. サードパーティライブラリのインポート。
  3. ローカルアプリケーション/ライブラリ固有のインポート。
• アルファベット順: 各グループ内では、インポートはアルファベット順にソートする必要があります。
• 絶対パス vs. 相対パス: プロジェクト内のモジュールには絶対パスインポートを優先します (例: from my_package.module import MyClass) が、兄弟モジュールには相対パスインポートも許容されます (例: from . import another_module)。
• ワイルドカードインポート: ワイルドカードインポート (from module import *) は避けてください。

2.3. フォーマット

• 行長: 1行あたり最大88文字を目指します (Black のデフォルト)。
• インデント: インデントには4つのスペースを使用します。タブは絶対に使用しないでください。
• 空白行:
  • トップレベルの関数とクラス定義の間には2つの空白行。
  • クラス内のメソッド定義の間には1つの空白行。
  • コード内の論理セクションの周囲には1つの空白行。
• 文字列: 通常の文字列には二重引用符 (") を優先し、二重引用符で囲まれた文字列内の文字列リテラルには単一引用符 (') を優先するか、Black のようなフォーマッターによって強制される場合は一貫したスタイルを使用します。

2.4. 型

• 型ヒント: コードの明確さを向上させ、静的解析を可能にするために、関数引数、戻り値、変数に型ヒントを使用します。
• 複合型: 複合型には、typing モジュール (例: List、Dict、Optional、Union、Any) の型を使用します。

2.5. 命名規則

• モジュール: lowercase_with_underscores.py
• パッケージ: lowercase_with_underscores
• クラス: CamelCase (例: MyClass)
• 関数/メソッド: lowercase_with_underscores (例: my_function、calculate_total)
• 変数: lowercase_with_underscores (例: my_variable、user_name)
• 定数: UPPERCASE_WITH_UNDERSCORES (例: MAX_RETRIES)
• プライベートメンバー: 単一のアンダースコアをプレフィックスとして使用します (例: _private_method、_internal_variable)。二重アンダースコア (__) は名前マングリング用であり、特に必要な場合を除き、一般的に避けるべきです。

2.6. エラー処理

• 特定の例外: 可能な場合は、広範な Exception ではなく、特定の例外をキャッチします。
• ロギング: 本番コードでは print ステートメントではなく、logging モジュールを使用してエラー報告とデバッグを行います。
• 意味のあるメッセージ: 明確で有益なエラーメッセージを提供します。
• コンテキスト: デバッグを支援するために、エラーメッセージまたはログに関連するコンテキストを含めます。

2.7. 作業ディレクトリ

pythonの実装は以下のディレクトリで行ってください。

• src/python_playground

テストは以下のディレクトリで行ってください。

• tests