型ヒント×mypyでバグを未然に防ぐ: 失敗しない設定と使い方

# ファイル名: demo_runtime_no_enforce.py
def number_to_str(n: int) -> int:  # 戻り値をintと書いているが…
    # 実際には文字列を返している
    return str(n)

result = number_to_str(3)
print(result, type(result))  # 実行は成功してしまう

# mypyの実行例
mypy demo_runtime_no_enforce.py

# 仮想環境の作成と有効化(例: venv)
python -m venv .venv
# Windowsなら .venv\Scripts\activate、macOS/Linuxなら:
source .venv/bin/activate

# mypyのインストール
pip install mypy

# バージョン確認
mypy --version

# プロジェクト直下をまとめてチェック
mypy .

# ファイル名: basics_minimal_hints.py
from typing import Optional

# 変数の型注釈
count: int = 0
title: Optional[str] = None  # Noneを取り得る

# 引数と戻り値の注釈
def greet(name: str) -> str:
    return f"Hello, {name}!"

# リストや辞書などのコレクション
def sum_all(xs: list[int]) -> int:
    s = 0
    for x in xs:
        s += x
    return s

print(greet("Alice"))
print(sum_all([1, 2, 3]))

# ファイル名: error_optional.py
from typing import Optional

def upper_or_default(s: Optional[str]) -> str:
    # mypyはsがNoneの可能性を指摘する
    return s.upper()  # エラー: "None"にはupperがない

error_optional.py:5: error: Item "None" of "Optional[str]" has no attribute "upper"  [union-attr]

# ファイル名: fix_optional.py
from typing import Optional

def upper_or_default(s: Optional[str]) -> str:
    if s is None:
        return ""
    return s.upper()

# ファイル名: error_list_type.py
names: list[str] = ["Alice", "Bob"]
names.append(123)  # エラー: intはlist[str]に入れられない

# ファイル名: fix_list_type.py
names: list[str] = ["Alice", "Bob"]
names.append(str(123))  # 文字列に変換してから追加

# ファイル名: error_missing_return.py
def sign(n: int) -> str:
    if n > 0:
        return "plus"
    elif n < 0:
        return "minus"
    # n == 0 の場合に戻り値がない → mypyが検出

# ファイル名: fix_missing_return.py
def sign(n: int) -> str:
    if n > 0:
        return "plus"
    elif n < 0:
        return "minus"
    else:
        return "zero"

# ファイル名: cautious_ignore.py
from typing import Any, cast

def parse_user_id(raw: Any) -> int:
    # 外部からの入力など、Anyが避けられない箇所
    if isinstance(raw, str) and raw.isdigit():
        return int(raw)
    # どうしても型が不明確ならcastを使って意図を明示
    # mypyエラーを抑制しつつ、後で置き換えやすい
    return cast(int, raw)  # type: ignore[return-value]  # API制約上ここは後で直す

# ファイル名: reveal_type_demo.py
from typing import Optional

def f(s: Optional[str]) -> None:
    reveal_type(s)  # mypy専用: "Optional[str]" と表示される

mypy reveal_type_demo.py

# ファイル名: pyproject.toml (推奨)
[tool.mypy]
python_version = "3.12"
pretty = true
show_error_codes = true
warn_unused_ignores = true
warn_redundant_casts = true
no_implicit_optional = true
check_untyped_defs = true

# ファイル名: mypy.ini (代替)
[mypy]
python_version = 3.12
pretty = True
show_error_codes = True
warn_unused_ignores = True
warn_redundant_casts = True
no_implicit_optional = True
check_untyped_defs = True

[tool.mypy.my_app.*]
disallow_untyped_defs = true

# ステップ1: 基本の安全ライン
[tool.mypy]
warn_unused_ignores = true
warn_redundant_casts = true
no_implicit_optional = true
check_untyped_defs = true

# ステップ2: 返り値・Anyの可視化を強める
warn_return_any = true
disallow_any_generics = true

# ステップ3: 未注釈の流入を止める
disallow_untyped_defs = true
disallow_incomplete_defs = true

# ステップ4: さらに厳格化(ほぼ--strict相当へ)
warn_unused_configs = true
no_implicit_reexport = true
strict_equality = true

# 例: requests の型スタブ
pip install requests types-requests

# ファイル名: use_requests_typed.py
import requests

def fetch_json(url: str) -> dict:
    r = requests.get(url, timeout=10)
    r.raise_for_status()
    return r.json()  # 型スタブがあると戻り値がdict扱いになり、後続の型検査が効く

pip install typing-extensions

# ファイル名: typing_extensions_demo.py
from typing_extensions import TypedDict, Protocol

class User(TypedDict):
    id: int
    name: str

class Greeter(Protocol):
    def greet(self, name: str) -> str: ...

# pyproject.toml
[tool.mypy]
exclude = [
  "legacy/.*",
]

# 特定モジュールだけ
[[tool.mypy.overrides]]
module = "some_legacy_lib.*"
ignore_missing_imports = true

# ファイル名: .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install -U pip
      - run: pip install -r requirements.txt
      - run: pip install mypy
      - run: mypy .

# ファイル名: .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
        additional_dependencies:
          - types-requests

// ファイル名: .vscode/settings.json
{
  "python.analysis.typeCheckingMode": "basic",  // 余力があれば "strict"
  "mypy-type-checker.args": [
    "--pretty",
    "--show-error-codes"
  ],
  "mypy-type-checker.severity": "error",       // 問題パネルにエラー表示
  "mypy-type-checker.preferDaemon": true       // 高速化(dmypy)
}

# ファイル名: optional_patterns.py
from typing import Optional

def length_or_zero(s: Optional[str]) -> int:
    if s is None:
        return 0
    return len(s)

def require_non_null(s: Optional[str]) -> int:
    assert s is not None  # 実行時にも守られる前提条件
    return len(s)

# ファイル名: any_boundary.py
from typing import Any, TypedDict, cast

class User(TypedDict):
    id: int
    name: str

def parse_user(payload: Any) -> User:
    # ざっくり検証してから型付け
    if not isinstance(payload, dict):
        raise ValueError("Invalid payload")
    if not isinstance(payload.get("id"), int) or not isinstance(payload.get("name"), str):
        raise ValueError("Invalid fields")
    return cast(User, payload)

# ファイル名: none_init.py
token: str | None = None
# 後でセット
token = "abc123"