python-best-practices

使用する場面

Python 3.12 以降を対象とする Python コードの作成またはレビュー時に、このスキルを使用します。最新の型ヒント、非同期パターン、Pydantic v2 API、プロジェクト構成、標準ライブラリの使用を徹底します。古いコードベースで学習したエージェントは、古いパターンを出力することがよくあります。このスキルはそれを修正します。

重要なルール

1. 最新の型ヒント構文を使用する

誤り：

from typing import Union, List, Dict, Optional

def process(items: List[str]) -> Optional[Dict[str, Union[int, str]]]:
    ...

正しい例：

def process(items: list[str]) -> dict[str, int | str] | None:
    ...

理由： list[str] と X | Y は Python 3.9 以降で組み込み構文として使用できます（PEP 585、PEP 604）。typing.List、typing.Union、typing.Optional をインポートするのは冗長であり、組み込みジェネリックでは非推奨です。

2. 型パラメーター構文を使用する（PEP 695、Python 3.12 以降）

誤り：

from typing import TypeVar

T = TypeVar("T")

def max(args: list[T]) -> T:
    ...

正しい例：

def max[T](args: list[T]) -> T:
    ...

理由： PEP 695 の型パラメーターはより簡潔で、関数やクラス内に局所化されます。ジェネリッククラスでも同様に、class Bag(Generic[T]): ではなく class Bag[T]: を使用します。

3. パターンマッチングには if/elif の連鎖ではなく match/case を使用する

誤り：

def http_error(status: int) -> str:
    if status == 400:
        return "Bad request"
    elif status == 404:
        return "Not found"
    elif status == 418:
        return "I'm a teapot"
    else:
        return "Something's wrong"

正しい例：

def http_error(status: int) -> str:
    match status:
        case 400:
            return "Bad request"
        case 404:
            return "Not found"
        case 418:
            return "I'm a teapot"
        case _:
            return "Something's wrong"

理由： 構造的パターンマッチング（PEP 634）は、互いに重複しないケースをより明確に記述でき、分解もサポートします。複数のリテラルには case 401 | 403 | 404: を使用します。

4. Pydantic v2 API を使用し、v1 は使用しない

誤り：

from pydantic import BaseModel, validator, root_validator

class Model(BaseModel):
    x: list[int]

    class Config:
        validate_assignment = True

    @validator("x", each_item=True)
    def validate_x(cls, v):
        return v * 2

    @root_validator
    def check_a_b(cls, values):
        ...

正しい例：

from pydantic import BaseModel, field_validator, model_validator, ConfigDict

class Model(BaseModel):
    model_config = ConfigDict(validate_assignment=True)
    x: list[int]

    @field_validator("x", mode="each")
    @classmethod
    def validate_x(cls, v: int) -> int:
        return v * 2

    @model_validator(mode="after")
    def check_a_b(self) -> "Model":
        ...
        return self

理由： Pydantic v1 のデコレーターと class Config は非推奨です。v2 では model_config、field_validator、model_validator を明示的なモードとともに使用します。

5. 新しいプロジェクトではパッケージ管理に uv を使用する

誤り：

pip install -r requirements.txt
poetry init

正しい例：

uv init
uv add requests pydantic
uv sync

理由： uv は高速で、最新のロックファイルを備え、pyproject.toml をネイティブにサポートします。新しいプロジェクトでは uv を優先してください。

6. プロジェクト構成には pyproject.toml を使用する

誤り：

# setup.py
from setuptools import setup
setup(name="myapp", version="0.1", ...)

正しい例：

# pyproject.toml
[project]
name = "myapp"
version = "0.1"
dependencies = ["requests"]

理由： setup.py と setup.cfg は旧式です。pyproject.toml（PEP 517/518）が標準です。

7. os.path ではなく pathlib.Path を使用する

誤り：

import os
path = os.path.join(os.getcwd(), "data", "file.txt")
if os.path.exists(path):
    with open(path) as f:
        ...

正しい例：

from pathlib import Path
path = Path.cwd() / "data" / "file.txt"
if path.exists():
    path.read_text()

理由： pathlib はオブジェクト指向で、より明確かつクロスプラットフォームです。単純な読み書きでは open() より Path.read_text()／write_text() を優先してください。

8. .format() や % 形式ではなく f 文字列を使用する

誤り：

"User %s has %d items" % (name, count)
"User {} has {} items".format(name, count)

正しい例：

f"User {name} has {count} items"

理由： f 文字列はより高速で、読みやすくなります。

9. 構造化データには通常の dict ではなく、データクラスまたは Pydantic を使用する

誤り：

def get_user() -> dict:
    return {"name": "Alice", "age": 30}

正しい例：

from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int

def get_user() -> User:
    return User(name="Alice", age=30)

理由： 構造化された型を使うと、型安全性と IDE のサポートが得られます。検証が必要な場合は Pydantic を使用してください。

10. asyncio.gather ではなく asyncio.TaskGroup を使用する（Python 3.11 以降）

誤り：

import asyncio
results = await asyncio.gather(f1(), f2(), f3())

正しい例：

import asyncio
async with asyncio.TaskGroup() as tg:
    t1 = tg.create_task(f1())
    t2 = tg.create_task(f2())
    t3 = tg.create_task(f3())
results = (t1.result(), t2.result(), t3.result())

理由： TaskGroup は例外を適切に伝播し、失敗時には他のタスクをキャンセルします。

11. 例外グループと except* を使用する（Python 3.11 以降）

誤り：

try:
    ...
except (ValueError, TypeError) as e:
    ...

正しい例（並行処理からの ExceptionGroup を扱う場合）：

try:
    ...
except* TypeError as e:
    print(f"caught {type(e)} with nested {e.exceptions}")
except* OSError as e:
    ...

理由： except* は asyncio や並行タスクから発生した ExceptionGroup を処理します。TaskGroup などから例外を捕捉する場合に使用してください。

12. TOML の解析には tomllib を使用する（Python 3.11 以降の標準ライブラリ）

誤り：

import toml
data = toml.load("pyproject.toml")

正しい例：

import tomllib
with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

理由： tomllib は組み込みなので、追加の依存関係は不要です。バイナリモードで読み込んでください。

13. typing.override デコレーターを使用する（Python 3.12 以降）

誤り：

class Child(Parent):
    def method(self) -> str:
        return "child"

正しい例：

from typing import override

class Child(Parent):
    @override
    def method(self) -> str:
        return "child"

理由： @override によって意図が明確になり、メソッド名の誤記を検出できます。

14. ガードを使用した構造的パターンマッチングを使用する

誤り：

match x:
    case (a, b):
        if a > b:
            ...

正しい例：

match x:
    case (a, b) if a > b:
        ...

理由： ガード（if）を使うとロジックをパターン内に保ち、条件分岐のネストを避けられます。

15. 抽象型には typing より collections.abc を優先する

誤り：

from typing import Iterable, Mapping

正しい例：

from collections.abc import Iterable, Mapping

理由： collections.abc は ABC の標準的な定義元です。typing からも再エクスポートされていますが、実行時チェックには collections.abc が推奨されます。

パターン

型パラメーターを使用したジェネリッククラス

class Bag[T]:
    def __iter__(self) -> Iterator[T]:
        ...
    def add(self, arg: T) -> None:
        ...

ジェネリック型エイリアス

type ListOrSet[T] = list[T] | set[T]

before モードの Pydantic model_validator

@model_validator(mode="before")
@classmethod
def check_card_number_not_present(cls, data: Any) -> Any:
    if isinstance(data, dict) and "card_number" in data:
        raise ValueError("'card_number' should not be included")
    return data

複数のリテラルを使った match

case 401 | 403 | 404:
    return "Not allowed"

避けるべきパターン

• 組み込みジェネリクスには from typing import List, Dict, Union, Optional を使用しないでください。代わりに list、dict、X | Y、X | None を使用してください。
• Pydantic で @validator、@root_validator、class Config を使用しないでください。代わりに v2 API を使用してください。
• 新しいコードでは os.path を使用しないでください。代わりに pathlib.Path を使用してください。
• setup.py や setup.cfg を使用しないでください。代わりに pyproject.toml を使用してください。
• f-string が使える場合は、% や .format() を使用しないでください。
• toml パッケージを使用しないでください。代わりに標準ライブラリの tomllib（Python 3.11 以降）を使用してください。
• Python 3.12 以降の型パラメーター構文が適用できる単純なジェネリクスには、TypeVar を使用しないでください。
• TaskGroup が利用できる場合（3.11 以降）は、構造化された並行処理に asyncio.gather を使用しないでください。
• 型付きの構造化データには、データクラスや Pydantic モデルが適している場合、通常の dict を使用しないでください。
• from typing import Iterable, Mapping を使用しないでください。代わりに from collections.abc import ... を使用してください。