Python ベストプラクティス

ruff format .   # フォーマット
ruff check .    # リント
ruff check --fix .  # 自動修正

import os
from pathlib import Path
 
import requests
from pydantic import BaseModel
 
from myapp.config import settings

def find_user(user_id: int, *, include_deleted: bool = False) -> User | None:
    ...

# ✅ 推奨
def process(items: list[str], mapping: dict[str, int] | None = None) -> tuple[int, ...]:
    ...
 
# ❌ 古い書き方
from typing import List, Dict, Optional, Tuple
def process(items: List[str], mapping: Optional[Dict[str, int]] = None) -> Tuple[int, ...]:
    ...

from collections.abc import Callable, Iterable, Iterator, Sequence, Mapping
from typing import Literal, TypedDict, Protocol, Final
 
Mode = Literal["read", "write"]
MAX_SIZE: Final = 1024
 
class Closeable(Protocol):
    def close(self) -> None: ...

# ❌ 何でもやる関数
def handle(data): ...
 
# ✅ 責務を分割
def validate(data: dict) -> None: ...
def transform(data: dict) -> Record: ...
def save(record: Record) -> None: ...

# ❌ リストが呼び出し間で共有される
def add_item(item, items=[]):
    items.append(item)
    return items
 
# ✅
def add_item(item: str, items: list[str] | None = None) -> list[str]:
    if items is None:
        items = []
    items.append(item)
    return items

def connect(host: str, port: int, *, timeout: float = 10.0, retries: int = 3) -> None:
    ...
 
connect("localhost", 5432, timeout=5.0)  # 意図が明確

from dataclasses import dataclass, field
 
@dataclass(frozen=True, slots=True)
class Point:
    x: float
    y: float
 
@dataclass
class Order:
    id: int
    items: list[str] = field(default_factory=list)

squares = [x * x for x in range(10) if x % 2 == 0]
name_by_id = {u.id: u.name for u in users}

total = sum(x * x for x in range(10_000_000))  # リストを作らない
 
def read_lines(path: Path) -> Iterator[str]:
    with path.open() as f:
        for line in f:
            yield line.rstrip("\n")

# ❌
for i in range(len(items)):
    print(i, items[i])
 
# ✅
for i, item in enumerate(items):
    print(i, item)
 
for name, score in zip(names, scores, strict=True):  # 長さ不一致を検出
    ...

first, *rest = values
a, b = b, a  # スワップ

if items:          # ✅  if len(items) > 0: ではなく
if value is None:  # ✅  == None ではなく
if flag:           # ✅  == True ではなく

msg = f"{user.name} has {count:,} points ({ratio:.1%})"
print(f"{value=}")  # デバッグ用: value=42 と出力

from pathlib import Path
 
config_path = Path(__file__).parent / "config" / "settings.toml"
text = config_path.read_text(encoding="utf-8")

match command:
    case {"action": "move", "x": x, "y": y}:
        move(x, y)
    case {"action": "quit"}:
        quit()
    case _:
        raise ValueError(f"Unknown command: {command}")

# LBYL（Look Before You Leap）
if key in mapping:
    value = mapping[key]
 
# EAFP — Pythonらしい書き方
try:
    value = mapping[key]
except KeyError:
    value = default
 
# もちろん、この例なら単に
value = mapping.get(key, default)

# ❌ すべてを握りつぶす
try:
    do_something()
except:
    pass
 
# ✅
try:
    data = json.loads(raw)
except json.JSONDecodeError as e:
    logger.warning("Invalid JSON: %s", e)
    raise

try:
    conn = connect(url)
except OSError as e:
    raise DatabaseError(f"Failed to connect to {url}") from e

class AppError(Exception):
    """アプリケーションの基底例外"""
 
class ValidationError(AppError): ...
class NotFoundError(AppError): ...

try:
    result = compute()
except ValueError:
    handle_error()
else:
    save(result)       # 例外が起きなかった時だけ
finally:
    cleanup()          # 必ず実行

with open("data.txt", encoding="utf-8") as f:
    content = f.read()

from contextlib import contextmanager
import time
 
@contextmanager
def timer(label: str):
    start = time.perf_counter()
    try:
        yield
    finally:
        print(f"{label}: {time.perf_counter() - start:.3f}s")
 
with timer("heavy task"):
    heavy_task()

[project]
name = "my-package"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
]
 
[dependency-groups]
dev = ["pytest", "ruff", "mypy"]
 
[tool.ruff]
line-length = 100
 
[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "SIM"]
 
[tool.mypy]
strict = true

def main() -> None:
    ...
 
if __name__ == "__main__":
    main()

uv init my-project
uv add requests
uv add --dev pytest ruff
uv run pytest
uv sync          # ロックファイルから環境を再現

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# tests/test_calc.py
import pytest
from my_package.calc import divide
 
def test_divide():
    assert divide(10, 2) == 5
 
def test_divide_by_zero():
    with pytest.raises(ZeroDivisionError):
        divide(1, 0)
 
@pytest.mark.parametrize(("a", "b", "expected"), [
    (6, 3, 2),
    (9, 3, 3),
    (-4, 2, -2),
])
def test_divide_parametrized(a, b, expected):
    assert divide(a, b) == expected

@pytest.fixture
def user() -> User:
    return User(id=1, name="Alice")
 
def test_user_name(user: User):
    assert user.name == "Alice"

import logging
 
logger = logging.getLogger(__name__)
 
def process(order_id: int) -> None:
    logger.info("Processing order %s", order_id)  # 遅延フォーマット
    try:
        ...
    except Exception:
        logger.exception("Failed to process order %s", order_id)  # スタックトレース付き
        raise

python -m cProfile -s cumtime script.py
python -m timeit "sum(range(1000))"

# 文字列の連結は join
result = "".join(parts)          # ✅
# result += part をループで繰り返さない
 
# 結果のキャッシュ
from functools import cache
 
@cache
def fib(n: int) -> int:
    return n if n < 2 else fib(n - 1) + fib(n - 2)

def fetch_user(user_id: int, *, timeout: float = 5.0) -> User:
    """ユーザー情報をAPIから取得する。
 
    Args:
        user_id: 取得対象のユーザーID。
        timeout: タイムアウト秒数。
 
    Returns:
        取得したユーザー。
 
    Raises:
        NotFoundError: ユーザーが存在しない場合。
    """

# ❌ 何をしているか（コードを見れば分かる）
i += 1  # iを1増やす
 
# ✅ なぜそうしているか
# APIが1始まりのインデックスを要求するため
page = index + 1

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.x.x  # 最新版を指定
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format