Pythonエンジニアなら誰もが通る道、型ヒントの記述揺れ問題。特にNoneを許容する型定義で、現場のコードベースを見ていると、Optional[int]とint | Noneが混在しているケースに遭遇します。これ、レビューで指摘するたびに「結局どっちがいいんですか？」と聞かれるんですよね。
結論、Python 3.10以降を使っているなら、新しい|演算子を使った記述に統一すべきです。この変更の背景と、混乱を避けるための現場テクニックを共有します。
※この記事は、個人技術ブログ CodeArchPedia.com の技術メモ（要約）です。
何が起きたか（課題）
Python 3.10以前のコードベースで型の整合性を保とうとすると、以下のような問題が発生します。
- プロジェクト内で
Optional[T]とUnion[T, None]が混在し、可読性が低下する。 - 新しい開発者が入った際、どちらが現在の標準なのか認識のズレが生じる。
- 静的解析ツール（Mypyなど）を導入しても、記述揺れによって警告の精度が落ちる。
どう解決したか（概要）
Python 3.10で導入されたPEP 604に基づき、|演算子を型結合子として採用し、コードベース全体でType | None形式に統一しました。
モダンPython型ヒントの標準化：Optional[T] vs T | Noneの解決策
Python 3.10以降では、Type | Noneを採用することが標準記法です。これはOptional[Type]の冗長な記述を避け、コードをスッキリさせます。
-
推奨記法:
int | Noneというシンプルな記述（特別なインポート不要）を全ファイルで採用。 -
自動統一: Lintツール（Ruffなど）を設定し、旧記法を見つけ次第、自動で
|記法に変換する仕組みを導入。 -
旧環境対応: Python 3.7や3.8環境でもモダンな記法を使うため、ファイル冒頭に
from __future__ import annotationsを記述。
このアプローチにより、コードの可読性と保守性が劇的に向上し、チーム内の認識統一が図れました。
Python 3.9以前ではUnion型を記述するのにtyping.Unionが必要でした。例えば、IDが整数または文字列の場合、以下のように記述していました。
from typing import Union
def process_id(data: Union[int, str]):
print(f"Processing: {data}")
しかし、PEP 604のおかげで、Python 3.10以降ではインポートなしで直感的に記述できます。
# Python 3.10以降
def process_id(data: int | str):
print(f"Processing: {data}")
また、オプショナル型も同様に簡潔になります。
# Optional[int] の代替
def get_config() -> int | None:
# ...
return 500
「Type | None」が推奨される客観的な理由
新しい記法が推奨されるのは、単なる簡略化だけでなく、Pythonの思想に沿っているからです。
1. 識別子の削減と直感性
Optional[T]を使うにはfrom typing import Optionalが必要ですが、T | Noneなら特別なインポートが不要です。パイプ記号は「または」という意味で直感的です。
2. コア開発者による支持
Pythonの設計者がこの構文を好ましいとしており、長期的な保守性を考慮すると標準に従うのが最善です。
3. 移行の自動化
現場で最も強力だったのは、RuffのようなモダンなリンターがType | Noneを標準として自動修正してくれる点です。ツール任せにすることで、開発者は記法について悩む時間がなくなります。
実践的な使い分けとテクニカルな考慮事項
基本的にはType | Noneで統一しますが、引数のデフォルト値としてNoneを設定する場合、少しだけ考慮が必要です。
# 引数が「省略可能」であることを強調したい場合
def create_record(user_id: Optional[int] = None):
# Optionalを使うことで、引数が省略可能であることが一目でわかる
...
def create_record_modern(user_id: int | None = None):
# Noneが2回出てきて、少し冗長に感じるかもしれない
...
型チェッカー上はどちらも等価ですが、文脈に応じてOptionalを残す余地もあります。ただし、一貫性を崩さないためには統一が優先されます。
Python 3.9以前で | 構文を使いたい場合
実行環境が古い場合でも将来を見据えて|構文を使いたいなら、ファイル冒頭に以下を記述します。
from __future__ import annotations
# Python 3.7+ 環境でもこの書き方が可能になります
def calculate(value: float | None) -> float | None:
# ...
これは型ヒントの評価を遅延させ、新しい構文を解釈できるようにするマジックインポートです。モダンなプロジェクトではデファクトスタンダードになりつつあります。
効果（Before/After）
| 項目 | Before (混在時) | After (統一後) |
|---|---|---|
| コードの視認性 | 低下（インポートと記法が混在） | 向上（パイプ記号で統一） |
| レビュー工数 | 高（記法の指摘が発生） | ほぼゼロ（リンターが担保） |
| 開発者の認知負荷 | 中 | 低 |
記述ルールが明確になったことで、コードレビューの時間が短縮され、静的解析ツールの警告がより信頼できるものになりました。これは大規模プロジェクトの品質維持に直結します。
🚀 詳細な設定とコードはこちら
具体的なRuffの設定方法や、from __future__ import annotationsを用いたクラス自己参照時の動作保証に関する詳細な解説は、元のブログで確認できます。
👉 Pythonの型ヒント新常識！Optional[Type]とType | None、どちらが「今」のベストプラクティス？