writing-python

Python 開発（3.14+）

基本原則

• 標準ライブラリを優先：正当な理由がある場合のみ外部依存を追加します
• 型ヒントを徹底：すべての関数、すべてのパラメーターに指定します
• 暗黙より明示：巧妙さより分かりやすさを優先します
• 早期に失敗：有益なエラーメッセージとともに、早めに例外を送出します

ツールチェーン

uv           # Package management (not pip/poetry)
ruff         # Lint + format (not flake8/black)
pytest       # Testing
mypy         # Type checking

すぐに使えるパターン

型ヒント

def process_users(users: list[User], limit: int | None = None) -> list[Result]:
    ...

async def fetch_data(url: str, timeout: float = 30.0) -> dict[str, Any]:
    ...

データクラス

from dataclasses import dataclass, field

@dataclass
class Config:
    host: str
    port: int = 8080
    tags: list[str] = field(default_factory=list)

パターンマッチング

match event:
    case {"type": "click", "x": x, "y": y}:
        handle_click(x, y)
    case {"type": "key", "code": code}:
        handle_key(code)
    case _:
        raise ValueError(f"Unknown event: {event}")

Python 3.14 の機能

• 遅延アノテーション：from __future__ import annotations は不要です
• テンプレート文字列（t""）：t"Hello {name}" は Template オブジェクトを返します
• 括弧なしの except：except ValueError, TypeError:
• concurrent.interpreters：サブインタープリターによる真の並列処理
• compression.zstd：標準ライブラリで Zstandard を利用できます
• フリースレッドビルド：GIL なし（オプトイン）

参考資料

• PATTERNS.md - コードのパターンとスタイル
• CLI.md - CLI アプリケーションのパターン
• TESTING.md - pytest を使ったテスト

ツール

uv sync                    # Install deps
ruff check --fix .         # Lint and autofix
ruff format .              # Format
pytest -v                  # Test
mypy .                     # Type check

---

統合されたサブスキル（統合後）

このスキルには、以前の python-code-style および python-type-safety スキルが統合されています。それらの元の SKILL.md の内容は、詳細な参考資料として保持されています。

対象	パス
ruff、mypy、命名、インポート、docstring（Google スタイル）	References/code-style.md
型アノテーション、ジェネリクス、プロトコル、厳格なチェックのパターン	References/type-safety.md

システムの信頼性（バックグラウンドジョブ、再試行、オブザーバビリティ）については、関連する python-infrastructure スキルを参照してください。依存関係の管理とプロジェクトのひな形作成については、uv を参照してください。

---

注意点

• from __future__ import annotations を指定すると、すべてのアノテーションが文字列になります — 実行時のイントロスペクション（typing.get_type_hints）には実際の型が利用可能である必要があり、ローカルスコープのクラスへの前方参照は失敗します。
• f 文字列のデバッグ構文（f"{var=}"）は 3.8 以降です — 3.7 以前では静かに失敗し（= がリテラルとして扱われ）ます。
• dataclass(slots=True) は 3.10 以降です — 3.9 では何もせずに処理が続行されます。移植性を確保するには、__slots__ を手動で使用してください。
• PEP 604 のユニオン構文（int | None）は実行時には 3.10 以降です — 3.9 では from __future__ import annotations を指定すれば文字列アノテーションとして動作しますが、実行時のイントロスペクションでは失敗します。
• FastAPI の依存関係では async def と def を使い分けます：非同期の依存関係はイベントループで実行され、同期の依存関係はスレッドプールで実行されます。考慮せずに混在させると、ブロッキングが発生するか、コンテキスト切り替えのオーバーヘッドが増えます。