Python 15：型ヒントと道具

型ヒントは「注意書きの札」。守らせるのは別の検査員

型ヒントを一言でいうと、関数に貼った注意書きの札です。「ここには float を入れてください」「戻ってくるのは float です」と書いてあります。

ところが、実際に関数を動かす python は、この札を読み飛ばします。札に何と書いてあっても、渡されたものをそのまま使って計算します。

札を読んで「使い方が札と違う」と文句を言うのは、mypy（マイパイ）などの型チェッカー（型の検査員）です。型チェッカーは、コードを実行せずに読むだけで、札と実際の使い方の食い違いを探します。

つまり Python の型は、「書く」と「検査する」が別の人の仕事になっています。書くのはあなた、検査するのは別の道具で、しかもその道具を呼ぶかどうかもあなた次第です。この「別の道具」という点が、後半の「どの python で動いているか」の話につながります。

本当に何もしない：int と書いても str が通る

本当に python が札を無視するのか、確かめます。

def double(n: int) -> int:
    return n * 2

print(double(21))
print(double("21"))   # str を渡した

$ python double.py
42
2121

エラーは出ませんでした。n: int と書いてあるのに、"21" という文字列がそのまま入り、"21" * 2 が計算されました。Python では文字列に整数を掛けると「その回数つなげる」という意味になるので、"2121" が返ってきます。-> int と書いた戻り値が str なのに、それも確かめていません。

これが「型ヒントは実行時に何もしない」の意味です。止まらないどころか、間違った答えを返して先へ進むことがあります。tenki なら、気温が "2121" のような文字列で表示されてしまうかもしれません。

JS でも、function double(n) { return n * 2 } に "21" を渡すと 42 になります（JS は文字列を数に変換して掛ける）。どちらも「型が違っても動いてしまう」言語ですが、変換のしかたは違います。TypeScript が型の検査を足すのと同じように、Python では型チェッカーを足します。

止まるとしたら、ずっと後の「計算できない行」で

もちろん、型が合わないせいで止まることもあります。ただし、止まる場所に注意してください。

def to_fahrenheit(celsius: float) -> float:
    return celsius * 9 / 5 + 32

print(to_fahrenheit(20))
print(to_fahrenheit("20"))

68.0
Traceback (most recent call last):
  File "hint.py", line 5, in <module>
    print(to_fahrenheit("20"))
  File "hint.py", line 2, in to_fahrenheit
    return celsius * 9 / 5 + 32
TypeError: unsupported operand type(s) for /: 'str' and 'int'

エラーの最後の2行を見ると、止まったのは関数の中の2行目です。呼び出した5行目で「float じゃないよ」と止まったのではありません。

順に追うと、"20" * 9 は文字列の繰り返しなので "202020202020202020" になり、ここまでは進みます。次の / 5 で「文字列を数で割れない」となって、ようやく TypeError が出ました。

本物のコードでは、間違った値が何段も関数を渡り歩いた先で、ようやく止まります。原因（間違った値を渡した所）と、止まった所が離れるので、探すのが大変です。型チェッカーは、この「原因の所」を実行前に指してくれます。

型ヒントは捨てられず、関数に「メモ」として残る

python は型ヒントを読み飛ばす、と書きましたが、捨ててはいません。関数の __annotations__ という属性に、辞書として残っています。

>>> def label(city: str, temp: int) -> str:
...     return f"{city}: {temp}℃"
>>> label(24, "Tokyo")        # 逆に渡しても動く
'24: Tokyo℃'
>>> label.__annotations__
{'city': <class 'str'>, 'temp': <class 'int'>, 'return': <class 'str'>}
>>> x: int = "hello"
>>> type(x)
<class 'str'>

x: int = "hello" も通りました。変数の型ヒントも、ただのメモです。

このメモは、読みたい人が読めるようになっています。代表的なのが、第7章で出てきた dataclass と、第17章で使う FastAPI です。

つまり「型ヒントは実行時に何もしない」は、正確には「python 本体は型ヒントを使わないが、ライブラリが自分で読んで使うことはある」です。FastAPI が入力を検証してくれるのは、Python の機能ではなく、FastAPI が __annotations__ を読んで自分で確かめているからです。

TypeScript との違い：「コンパイルで止まる」段階が無い

TypeScript と Python の流れを並べると、図のようになります。

TypeScript では、tsc（TypeScript のコンパイラ）が .ts を読み、型を検査してから、型を取り除いた .js を作ります。node が動かすのは、型の無くなった .js です。型の検査は「JS にする途中の段階」に組み込まれています（ただし tsc も、既定では型エラーがあっても .js を書き出します。止めるかどうかは設定と、CI でエラーを失敗扱いにするかどうかで決まります）。

Python には、この「途中の段階」がありません。python main.py は、型ヒントを読み飛ばしてそのまま実行します。型の検査は、mypy を自分で呼んで初めて行われます。

注目したいのは、最近の Node.js の動きです。Node.js 22.18 と 23.6 以降は、.ts ファイルを直接 node app.ts で動かせます。このとき Node.js は型の部分を消して実行するだけで、型の検査はしません。型の検査は別に tsc --noEmit で行う、という形です。

これは、Python が最初からやっている形とほぼ同じです。「実行は型を見ない。検査は別の道具」。TypeScript から来た人は、tsc の「検査」の部分だけを mypy が受け持つと考えると、すっきりします。

型ヒントの書き方（TypeScript と並べて）

よく使う書き方を、TypeScript と並べました。

list[str] や str | None は、Python 3.9・3.10 で入った書き方です。古い記事では List[str]・Optional[str] のように typing から import して書いていますが、Python 3.13 では今の書き方で書けます。

tenki の関数に付けると、たとえばこうなります。

def fetch_temp(city: str) -> float:
    ...

def forecast(cities: list[str]) -> dict[str, float]:
    return {c: fetch_temp(c) for c in cities}

def find_city(key: str) -> str | None:
    ...

型ヒントは全部に書かなくてもかまいません。まず関数の引数と戻り値に書くのが効果的です。関数の中の変数は、たいてい型チェッカーが推論（右辺から自動で判断）してくれます。

mypy：実行せずに、札と使い方の食い違いを探す

mypy は、型ヒントを読んでコードを検査する道具です。Python で最も古くからある型チェッカーで、型ヒントの仕組み自体が mypy から始まりました。

def label(city: str, temp: int) -> str:
    return f"{city}: {temp}℃"

print(label(24, "Tokyo"))
x: int = "hello"

このファイル（hint2.py）を python で動かすと、何も言わずに 24: Tokyo℃ と出ます。mypy に渡すと、こうなります。

$ mypy hint2.py
hint2.py:4: error: Argument 1 to "label" has incompatible type "int"; expected "str"  [arg-type]
hint2.py:4: error: Argument 2 to "label" has incompatible type "str"; expected "int"  [arg-type]
hint2.py:5: error: Incompatible types in assignment (expression has type "str", variable has type "int")  [assignment]
Found 3 errors in 1 file (checked 1 source file)

mypy はコードを1行も実行していません。だから、ネットワークに行く関数や、ファイルを消す関数でも安心して検査できます。

同じ役目の道具に pyright（パイライト。Microsoft 製）があります。VS Code の Python 拡張に入っている Pylance の中身は pyright です。同じファイルを pyright に渡しても、同じ3か所がエラーになりました。どちらを使ってもかまいませんが、プロジェクトの中では1つにそろえるのがふつうです。

mypy が一番役に立つのは「None かもしれない」

型チェッカーが実際に一番よく助けてくれるのは、「None かもしれない値」の扱いです。

CITIES = {"tokyo": "東京", "osaka": "大阪"}

def find_city(key: str) -> str | None:
    return CITIES.get(key)

def shout(key: str) -> str:
    return find_city(key).upper()

dict.get は、キーが無いと None を返します（JS でオブジェクトに無いキーを読むと undefined になるのと似ています）。だから find_city の戻り値は str | None です。その結果にいきなり .upper() を呼ぶと、"nagoya" のように無いキーのとき AttributeError: 'NoneType' object has no attribute 'upper' で落ちます。

mypy は、これを実行前に教えてくれます。

$ mypy none.py
none.py:7: error: Item "None" of "str | None" has no attribute "upper"  [union-attr]

直し方は、None のときを先に片付けることです。

def shout(key: str) -> str:
    city = find_city(key)
    if city is None:
        return "?"
    return city.upper()   # ここでは str

if city is None: return の後では、mypy は「ここから先の city は str」と分かっています。これを型の絞り込みと呼びます。TypeScript の strictNullChecks で if (city === null) return と書くのと、まったく同じ考え方です。

第3章で is None を使う理由を見ましたが、型チェッカーも is None の形を見て絞り込みます。

型ヒントは少しずつ足せる。ただし書いていない所は見ない

Python の型ヒントは、書いた所から少しずつ足していけます。これを段階的型付け（gradual typing）と呼びます。既存のコードに、全部を一度に書き足す必要はありません。

ただし裏返しとして、書いていない所を mypy は見ません。

def untyped(x):        # 型ヒントなし
    return x + 1

untyped("a")           # 実行すると TypeError

$ mypy gradual.py
Success: no issues found in 1 source file

実行すれば "a" + 1 で TypeError になるのに、mypy は「問題なし」と言いました。型ヒントの無い関数は、引数も戻り値も Any（何でもよい）として扱われ、既定では関数の中身も調べないからです。

--strict を付けると、この「書いていない」ことも指摘させられます。

$ mypy --strict gradual.py
gradual.py:1: error: Function is missing a type annotation  [no-untyped-def]
gradual.py:4: error: Call to untyped function "untyped" in typed context  [no-untyped-call]

tenki の weather.py で return r.json()["temp"] と書いた所を --strict で検査すると、「float を返すはずの関数が Any を返している」と言われました。外から来るデータの形は、型ヒントだけでは保証できないのです。第17章では、FastAPI（と、その中の pydantic）が、この「外から来たデータ」を実行時に確かめる役を担います。

mypy が何も言わない＝正しい、ではないことを覚えておきましょう。新しく書くプロジェクトなら、最初から strict = true にしておくのが楽です。

ruff check：型ではなく「よくある書き間違い」を探す

型とは別に、「動くけれど、たぶん間違い」「読みにくい」書き方を探す道具をリンターと呼びます。JS でいう ESLint です。今の Python では ruff（ラフ）がよく使われます。uv と同じ Astral という会社が作っていて、Rust で書かれているのでとても速い道具です。

図の左のような、少し雑なファイルを検査してみます。

$ ruff check --output-format concise messy.py
messy.py:1:8: F401 [*] `os` imported but unused
messy.py:2:8: F401 [*] `sys` imported but unused
messy.py:3:8: F401 [*] `json` imported but unused
messy.py:6:16: E711 Comparison to `None` should be `cond is None`
Found 4 errors.
[*] 3 fixable with the `--fix` option (1 hidden fix can be enabled with the `--unsafe-fixes` option).

[*] の付いたものは、ruff check --fix で自動で直せます。E711 は、== を is に変えると意味が変わりうるので、自動では直さない（--unsafe-fixes を付けたときだけ直す）扱いになっています。

F401・E711 のような番号は、規則の名前です。Python には昔から flake8・isort・pyupgrade など、役割ごとに別々のリンターがあり、それぞれが規則に番号を付けていました。ruff はそれらの規則を1つの道具で引き継いでいるので、番号の頭の文字（F は pyflakes、E は pycodestyle など）が元の道具を表しています。

ruff format：書き方の揺れを1通りにそろえる

ruff にはもう1つ、フォーマッター（整形する道具）の役目があります。JS でいう Prettier です。空白・引用符・空行などを、決まった1通りの形に書き直します。

--diff を付けると、書き換えずに「どう変えるか」だけを見せてくれます。

$ ruff format --diff messy.py
-def show(city,temp):
+
+def show(city, temp):
     if temp == None:
-        return city+": ?"
+        return city + ": ?"
     return f"{city}: {temp}℃"
-print( show('Tokyo',24) )
+
+
+print(show("Tokyo", 24))

== None は直していないことに注目してください。フォーマッターは形だけを変え、意味は変えないのが約束です。意味にかかわる指摘は ruff check の仕事です。

ruff format の形は、Python でよく使われてきた black というフォーマッターとほぼ同じになるように作られています。形を1つに決めてしまうと、「インデントは」「引用符は」という議論が要らなくなり、差分も読みやすくなります。エディタで保存のたびに自動で整形するようにしておくのがおすすめです。

pytest：ファイル名と関数名の決まりでテストを見つける

pytest は、Python で最もよく使われるテストの道具です。JS でいう Jest や Vitest にあたります。

pytest の特徴は、テストを登録しなくてよいことです。決まった名前のファイルと関数を、pytest が自分で探して全部呼びます。

逆に、図の helper メソッド（test で始まらない）や、helpers.py の中の関数（ファイル名が決まりに合わない）は、テストとして集められません。実際に、何が集められるかを確かめられます。

$ uv run pytest --collect-only -q
tests/test_class.py::TestConvert::test_minus
tests/test_convert.py::test_freezing
tests/test_convert.py::test_boiling
tests/test_convert.py::test_body

4 tests collected in 0.01s

helpers.py の中の test_not_collected は、名前が test で始まっていても、ファイル名が test_ で始まっていないので無視されました。

この「名前の決まりで探す」は、JS の Jest が *.test.js や *.spec.ts を探すのと同じ発想です。pytest は、どのフォルダから探し始めるかも決められます（後で出てくる testpaths の設定）。

書くのは assert だけ。失敗すると中身まで見せてくれる

pytest のテストは、ふつうの関数の中に `assert` 文を書くだけです。assert 条件 は Python の文で、条件が偽なら AssertionError を出します。

# tests/test_convert.py
from tenki.convert import to_fahrenheit

def test_freezing():
    assert to_fahrenheit(0) == 32

def test_body():
    assert to_fahrenheit(37) == 99   # わざと間違えた

$ uv run pytest
tests/test_convert.py ..F
    def test_body():
>       assert to_fahrenheit(37) == 99
E       assert 98.6 == 99
E        +  where 98.6 = to_fahrenheit(37)
FAILED tests/test_convert.py::test_body - assert 98.6 == 99
1 failed, 2 passed in 0.02s

. は成功、F は失敗です。失敗したテストでは、左辺が 98.6 だったこと、そしてそれが `to_fahrenheit(37)` の結果だったことまで表示されました。

ふつうの assert は、失敗しても「AssertionError」としか言いません。pytest は、テストのファイルを読み込むときに assert 文を書き換えて、途中の値を覚えておくようにしています。だから Jest の expect(a).toBe(b) のような専用の関数を覚えなくても、失敗の中身が分かります。

1行目の from tenki.convert import to_fahrenheit に注目してください。テストは、インストールされた tenki を import しているのです。これが次の問題の入口です。

pytest を打ったら No module named 'tenki'

この環境で、ふつうに pytest と打ったら、こうなりました。

$ pytest
E   ModuleNotFoundError: No module named 'tenki'

tenki はちゃんと .venv に入っている（第14章の .pth）のに、なぜでしょうか。

原因は、この `pytest` がどの python で動いているかです。この環境の pytest は uv tool install pytest（第14章）で入れたもので、~/.local/share/uv/tools/pytest/ という pytest 専用の venv の python で動いています。図の左です。

第8章を思い出してください。import tenki は、いま動いている python の `sys.path` を探します。左の python の sys.path には、左の site-packages しかありません。右の .venv に何が入っていても、左の python からは見えないのです。

道具もただの Python のプログラムで、どれか1つの python の上で動いています。道具の「中から」見えるのは、その python に入っているものだけです。これが、この章の後半の要点です。

uv run pytest なら、tenki の .venv の python で動く

直し方は、pytest を tenki の `.venv` に入れて、その python で動かすことです。

$ uv add --dev pytest mypy ruff
$ uv run pytest
4 passed in 0.01s

uv add --dev は、開発のときだけ使う道具を .venv に入れ、pyproject.toml の [dependency-groups] の dev に記録します（JS の npm install -D が devDependencies に書くのと同じ）。

uv run pytest は、.venv/bin/pytest を .venv の python で動かします。図の右です。この python の site-packages には、第14章で見た tenki_cli.pth があるので、sys.path に src/ が足され、import tenki が見つかります。

pytest の公式の手引きも、テストするプロジェクトを pip install -e . で入れてからテストすることを勧めています。uv sync や uv run は、自分のプロジェクトを自動で編集可能の形で入れてくれる（第14章）ので、何もしなくてもこの形になっています。

uv run は、JS の npx や npm run と同じ役目です。「このプロジェクトに入っている道具を、このプロジェクトの環境で動かす」。

mypy も同じ：どの python で動くかで結果が変わる

mypy でも、同じことが起きます。tenki に、httpx（第16章で使う HTTP のライブラリ）を import する net.py を足して検査しました。

$ head -1 $(which mypy)
#!/…/.local/share/uv/tools/mypy/bin/python
$ mypy src/tenki/net.py
src/tenki/net.py:1: error: Cannot find implementation or library stub for module named "httpx"  [import-not-found]

$ uv run mypy src/tenki/net.py
Success: no issues found in 1 source file

1行目の head -1 は、mypy コマンドの実行ファイルの1行目（第14章で見た #! の行）を表示しています。この mypy は、mypy 専用の venv の python で動いていることが分かります。

mypy の公式の説明によると、mypy は「自分が動いている Python の環境」に入っているパッケージから、型の情報を探します。左の venv には httpx が無いので「見つからない」になりました。右の .venv で動かせば、httpx の型の情報を読めるので「問題なし」です。

ライブラリが型の情報を持っている印は、パッケージのフォルダにある `py.typed` という空のファイルです。持っていないライブラリには、types-requests のようなスタブ（型の情報だけのパッケージ）が別に配られていることがあります。mypy が「Library stubs not installed」と言うのは、この「型の情報だけのパッケージを入れて」という意味です。

道具の設定も pyproject.toml の [tool.…] に集める

JS では、package.json のほかに .eslintrc・.prettierrc・jest.config.js と、道具ごとに設定のファイルが増えがちです。Python では、これらを `pyproject.toml` の `[tool.道具の名前]` に集めるのがふつうです（第14章で見た [tool.uv.build-backend] と同じ仕組み）。

[dependency-groups]
dev = [
    "mypy>=2.3.1",
    "pytest>=9.1.1",
    "ruff>=0.16.9",
]

[tool.mypy]
strict = true

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

[tool.pytest.ini_options]
testpaths = ["tests"]

[dependency-groups] の版は、uv add --dev がそのとき入れた版を書いたものです（2026年9月に実際に入った版）。

これで、友だちが tenki を clone して uv sync すれば、同じ版の mypy・ruff・pytest が .venv に入り、同じ設定で同じ検査ができます。道具も依存の一部として記録するのが、「自分のところでは通るのに」を減らすコツです。

エディタも「どの python を見るか」を選んでいる

エディタも同じ話です。VS Code の Python 拡張は、Pylance（中身は pyright）を使って、補完や赤い波線を出しています。そのとき、どの python の site-packages を見るかを、エディタの設定で選んでいます。これが「インタプリタの選択」（Python: Select Interpreter）です。

違う python を選んでいると、import の行にこう波線が出ます。

Import "httpx" could not be resolved

これは、pyright を実際に動かして確かめられます。同じ net.py を、.venv を向けずに検査すると上のエラーが出て、--pythonpath .venv/bin/python で .venv の python を向けると、エラーは0件になりました。

選んだ python は、エディタの中で実行するときにも使われます。VS Code の公式の説明では、選んだ環境は「コードの実行・デバッグ・補完などの言語機能」のすべてに使われ、新しく開いたターミナルでも自動で activate されます。

つまり「インタプリタの選択」は、第12章の activate を、エディタ全体に対してするスイッチです。コードに問題が無いのに赤い波線が消えないときは、まずここを疑います。

「どの python？」を確かめる3つの場所

迷ったときは、図の3か所が同じ `.venv` を指しているかを確かめます。

$ which python
/Users/you/tenki/.venv/bin/python
$ python -c "import sys; print(sys.executable)"
/Users/you/tenki/.venv/bin/python

3つがそろっていれば、エディタの波線・ターミナルでの実行・uv run が、すべて同じ python の上で動いています。

いくつかのコツがあります。VS Code は、開いたフォルダ（ワークスペース）の一番上にある .venv を最初の候補にします。だから tenki/ フォルダそのものを開くのが一番確実です。親のフォルダを開いて、その中に tenki が入っている形だと、.venv が見つからないことがあります。

選び直すときは、コマンドパレット（Ctrl+Shift+P、macOS は Cmd+Shift+P）で「Python: Select Interpreter」を選び、一覧から .venv を選びます。一覧に無ければ「インタプリタのパスを入力」で .venv/bin/python を指定します。

第18章の「困ったとき」でも、この3か所はもう一度出てきます。

JS の道具でいうと

この章の道具を、JS・TypeScript の道具と並べます。

ほぼ1対1ですが、大きな違いが2つあります。

1つは、型の検査が「実行への段階」に組み込まれていないことです。TypeScript は tsc を通さないと（あるいは型を消さないと）動かせませんが、Python は mypy を一度も呼ばなくても動きます。だから、CI（GitHub Actions など）で uv run mypy . を必ず回すようにしておかないと、型ヒントは「書いてあるだけ」になります。

もう1つは、道具が「どの python で動くか」を意識する必要があることです。JS の道具も node_modules の中にありますが、node は1つのプロセスでそのプロジェクトの node_modules を探すので、「道具からプロジェクトのライブラリが見えない」ことはあまり起きません。Python では、道具も python の上で動くプログラムで、その python の sys.path しか見えません。uv run で動かす習慣をつければ、この違いはほとんど気にならなくなります。

よくある間違いと、その原因

この章の内容で、よく出会うものをまとめました。

こうして並べると、原因は大きく2つに分かれます。

後者は、どれも第8章の sys.path の話に帰ってきます。「このコマンドは、どの python で動いている？ その python の site-packages に、目当てのものは入っている？」と2つ問えば、たいてい原因が見つかります。