Python型ヒントの書き方と使い方: typingとmypyまで

# hint_demo.py
# 型ヒントはありますが、Pythonは実行時にこれを強制しません。
def repeat(s: str, n: int) -> str:
    return s * n  # 文字列sをn回繰り返す

print(repeat("ha", 3))      # 正しい呼び出し
print(repeat(3, "ha"))      # 引数の並びが逆(論理的には誤り)でも実行は成功してしまう

mypy hint_demo.py

# 変数への型注釈
count: int = 0
names: list[str] = ["Alice", "Bob"]
config: dict[str, int] = {"retries": 3}

pi: float  # ここで型だけ注釈して後で代入
pi = 3.14159

# レガシーな書き方(コメント注釈)。新規では推奨されません。
data = []  # type: list[int]

from typing import Final

API_VERSION: Final = "v1"  # 上書きを意図しない

def greet(name: str, excited: bool = False) -> str:
    """挨拶文を生成する"""
    base = f"Hello, {name}"
    return base + "!" if excited else base

def total(*scores: int) -> int:
    """可変長引数の例"""
    return sum(scores)

def debug(**flags: bool) -> None:
    """キーワード引数の例"""
    print(flags)

print(greet("Alice"))
print(greet("Bob", excited=True))
print(total(10, 20, 30))
debug(verbose=True, dry_run=False)

def parse_port(port: int | None) -> int:
    """ポート番号。Noneならデフォルト80を使う"""
    if port is None:       # Noneチェックで型が絞り込まれます(型ナローイング)
        return 80
    return port

def to_str(x: int | float | str) -> str:
    return str(x)

# 代表例
nums: list[int] = [1, 2, 3]
index: dict[str, int] = {"a": 1}
seen: set[str] = {"x", "y"}
point: tuple[float, float] = (35.0, 139.0)

# 長さ不定のタプル(同じ型が並ぶ)
values: tuple[int, ...] = (1, 2, 3, 4)

# 読み取り専用インターフェイス(反復専用など)を受ける引数
from collections.abc import Mapping, Sequence

def sum_all(xs: Sequence[int]) -> int:  # listでもtupleでもOK
    return sum(xs)

def lookup(key: str, m: Mapping[str, int]) -> int:
    return m[key]

from typing import Callable

def operate(x: int, y: int, op: Callable[[int, int], int]) -> int:
    """2項演算を引数で受け取る"""
    return op(x, y)

print(operate(2, 3, lambda a, b: a + b))

from typing import Any

payload: Any = {"id": 123}   # Anyにすると何でも通ってしまう
payload = "oops"              # これもエラーにならない

from typing import NoReturn

def fail(msg: str) -> NoReturn:
    raise RuntimeError(msg)

from typing import TypeAlias

UserId: TypeAlias = int
GeoPoint: TypeAlias = tuple[float, float]

def locate(user_id: UserId) -> GeoPoint:
    # 実装は仮の例
    return (35.0, 139.0)

from typing import Literal

# methodは"GET"か"POST"のみ
def request(method: Literal["GET", "POST"], url: str) -> None:
    print(method, url)

request("GET", "https://example.com")
# request("PATCH", "...")  # mypyはエラーにします

from enum import Enum

class Method(Enum):
    GET = "GET"
    POST = "POST"

def request2(method: Method, url: str) -> None:
    print(method.value, url)

request2(Method.GET, "https://example.com")

from typing import TypedDict

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

u: User = {"id": 1, "name": "Alice", "is_active": True}  # 型整合性をチェックできる

from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float

p = Point(1.0, 2.0)
print(p.x, p.y)

from dataclasses import dataclass, field

@dataclass
class Account:
    id: int
    name: str
    tags: list[str] = field(default_factory=list)  # ミュータブルはdefault_factoryで
    active: bool = True

    def describe(self) -> str:
        return f"{self.id}:{self.name} ({'active' if self.active else 'inactive'})"

acc = Account(id=1, name="Alice")
acc.tags.append("premium")
print(acc)
print(acc.describe())

from typing import Generic, TypeVar

T = TypeVar("T")

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._data: list[T] = []

    def push(self, item: T) -> None:
        self._data.append(item)

    def pop(self) -> T:
        return self._data.pop()

ints = Stack[int]()
ints.push(10)
x = ints.pop()   # xはintとして推論される

texts = Stack[str]()
texts.push("hello")
# texts.push(123)  # mypyはエラーにします
print(x, texts.pop())

# 仮想環境の作成と有効化(例: Unix系)
python -m venv .venv
source .venv/bin/activate

# Windowsの場合は: .venv\Scripts\activate

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

# ファイル単位でチェック
mypy hint_demo.py

# ディレクトリ単位でチェック
mypy src/

# wrong_return.py
def half(x: int) -> float:
    if x % 2 == 0:
        return x / 2
    # 偶数以外で戻り値がない -> エラー

mypy wrong_return.py

def half(x: int) -> float:
    return x / 2

# maybe_len.py
def maybe_len(s: str | None) -> int:
    # return len(s)  # エラー: "None"の可能性
    if s is None:
        return 0
    return len(s)     # ここではsはstrに絞り込まれる

# reveal_demo.py
def f(x: int | None) -> int:
    if x is None:
        return 0
    reveal_type(x)  # mypy: Revealed type is "builtins.int"
    return x

mypy reveal_demo.py

[tool.mypy]
python_version = "3.11"
# まずは外部ライブラリ起因のエラーを黙らせる
ignore_missing_imports = true
# 未使用の # type: ignore を警告
warn_unused_ignores = true
# 未型注釈の関数定義を許容(段階的に厳しくする)
disallow_untyped_defs = false
# Noneの混入を厳密に扱う
no_implicit_optional = true

# モジュール単位で上書き
[[tool.mypy.overrides]]
module = ["myapp.core.*"]
disallow_untyped_defs = true  # 中核部分は厳しくする

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

pip install typing_extensions