<p>こんにちは! 仙台オフィスで主にTypeScriptを書いているChloéです。</p><p>普段の開発では静的型付き言語を使うことが多いのですが、今回はPythonにおける型ヒントと、それに基づいて型チェックを行うツールのmypyについて記事を書いてみることにしました。</p><p>記事のターゲットとしては、主に「Jupyter Notebook等で生成AI等を使うためにPythonを書くのには慣れているけど、Pythonで(Web)アプリケーションを作った経験があまり無い」という方を想定しています。</p><p></p><h2 id="h0669eefa7c">目次</h2><ol><li>環境</li><li>Pythonに型チェックを導入するモチベーション</li><li>型ヒントの基本<ol><li>変数の型ヒント</li><li>関数の型ヒント</li><li>Union型</li></ol></li><li>mypyの導入<ol><li>mypyのインストール</li><li>mypyによる型チェック</li></ol></li><li>実践的な型チェック<ol><li>意図しない型変換</li><li>Null安全</li></ol></li><li>まとめ</li></ol><h2 id="h2b77a92925">1. 環境</h2><ul><li>Python 3.12.1</li><li>mypy 1.10.0<ul><li>本記事では特にカスタマイズはせず、デフォルトの設定で使用します。</li></ul></li></ul><h2 id="he47629f54e">2. Pythonに型チェックを導入するモチベーション</h2><p>私たちの会社では、生成AIや機械学習関連の業務がそこそこ多いため、Pythonエンジニアの割合が高いです。そのため、Webバックエンドアプリケーションは主にPythonで実装されています。Pythonは動的型付き言語であるため、ある程度の規模以上のアプリケーションを実装する際、型の情報がコードに明示されていないとメンテナンス性に問題が生じる可能性があります。</p><p>このような問題を解決するために、現代のPythonには <strong>型ヒント(Type Hints)</strong> という機能が存在します。型ヒントを利用することで、以下の利点が得られます。</p><ul><li>ドキュメンテーション<ul><li>型ヒントによって変数や関数にどのような値が入るかが可視化されるため、人間がコードを読んだ時に理解の助けになります。</li></ul></li><li>自動補完<ul><li>Pythonに対応しているテキストエディタやIDEについて、自動補完をサポートします。Pythonは動的型付き言語なので、ある変数についてどのような操作や演算ができるか解析しにくいです。型ヒントを入れることにより、変数に対する操作や演算が明確になり、自動補完がより正確になります。</li></ul></li><li>型チェック<ul><li>型をチェックできる静的解析ツールにより、プログラミングのミスに早期に気付くことができます。</li></ul></li></ul><p>型ヒント自体はPythonの機能ですが、Pythonのランタイムは型ヒントに対して特に何もしないことに注意してください。(型ヒントが書かれているコードを実行した時、型ヒントが無い場合と全く同じ動作をします) 自動補完や型チェックについては、型ヒントを理解する外部ツールによって実現されています。</p><p>この記事では型チェックにフォーカスし、<strong>mypy</strong>という静的解析ツールを使って実際にPythonコードの型チェックを行う方法を説明します。</p><h2 id="h777965de86">3. 型ヒントの基本</h2><p>本章では、Pythonのコードに型ヒントを付ける方法を扱います。</p><h3 id="ha5befadd66">3.1 変数の型ヒント</h3><ul><li>変数に型ヒントを付ける際は、 <code>変数名: 型名 = 値</code> と書きます。</li></ul><pre><code class="language-python"># int型の値
int_value: int = 123

# str型の値
str_value: str = &quot;Biz Freak&quot;

# bool型の値
bool_value: bool = True</code></pre><ul><li><code>list</code>や<code>tuple</code>といったコレクション型の型ヒントは以下の要領で書きます。</li></ul><pre><code class="language-python"># str型の要素を持つlist
list_value: list[str] = [&quot;abc&quot;, &quot;def&quot;, &quot;ghi&quot;]

# 1番目の要素がstr型, 2番目の要素がint型のtuple
tuple_value: tuple[str, int] = (&quot;abc&quot;, 1)

# Keyがstr型、Valueがint型のdict
dict_value: dict[str, int] = { &quot;abc&quot;: 1, &quot;def&quot;: 2 }</code></pre><h3 id="h94457c143b">3.2 関数の型ヒント</h3><p>関数に型ヒントを付ける際は、 <code>def 関数名(引数名: 型名 ...) -&gt; 戻り値の型名</code> と書きます。</p><pre><code class="language-python"># str型の引数1つをとってstr型の返り値を返す関数
def do_freak(something: str) -&gt; str:
  return f&quot;{something} Freak&quot;</code></pre><h3 id="hb5e347ca97">3.3 Union型</h3><p>複数の型を受け入れる変数を定義したいことがしばしばあります。そのような時には、Union型を使います。Union型は「複数の型のうちいずれかの型」を表現するものです。</p><pre><code class="language-python">int_or_str_value: int | str = 1 # intとstrのUnion型。 int型の値を代入
int_or_str_value = &quot;foo&quot; # str型の値の代入が許される</code></pre><h2 id="h38babb5976">4. mypyの導入</h2><p>本章では、静的解析ツールであるmypyの導入と、簡単な型チェックの方法を扱います。</p><h3 id="h643ed29b6a">4.1 mypyのインストール</h3><p>mypyは外部ツールなので、 <code>pip</code> などのパッケージマネージャからインストールするのが簡単です。</p><pre><code class="language-shell">pip install mypy</code></pre><h3 id="h09aa9f9c49">4.2 mypyによる型チェック</h3><p><code>mypy</code> コマンドの後に型チェックしたいスクリプトファイルのパスを渡すと、そのファイルの型チェックを行えます。</p><pre><code class="language-shell">mypy my-script.py</code></pre><p>ここで、標準出力に <code>Success: no issues found in 1 source file</code> と出力されると、型チェック成功です。</p><p>また、ソースコードが置かれているディレクトリを渡すと、ディレクトリの中のスクリプトファイルを再帰的に型チェックできます。</p><pre><code class="language-shell">mypy ./src/</code></pre><h3 id="hdaad11f928">4.3 テキストエディタ・IDEとの統合</h3><p>この手のツール全般に言えることですが、テキストエディタやIDEと統合することで快適な開発環境を構築することができます。ここでは例として、VSCodeとの統合方法を紹介します。</p><ul><li>VSCodeの拡張機能のマーケットプレースから”<a href="https://marketplace.visualstudio.com/items?itemName=ms-python.mypy-type-checker">Mypy Type Checker</a>”をインストールします。</li><li>拡張機能の設定から”Mypy-type-checker: Show Notifications”を”onError”に設定します。<figure><img src="https://images.microcms-assets.io/assets/145b371faece4417bfaf63302a2f6c77/8e6187309f204d3e914819e0266b0bd7/python01-mypy-type-checker-show-notifications.png" alt="" width="511" height="118"></figure><p></p></li><li>型エラーのある箇所に、自動的に以下のような表示が出ます。<figure><img src="https://images.microcms-assets.io/assets/145b371faece4417bfaf63302a2f6c77/cdcf023227794d658583209077bcfe1d/python01-mypy-error-on-cursor.png" alt="" width="1037" height="129"></figure><p>ちなみにこのエディタは正確にはVSCodeではなく、VSCodeをフォークして開発された<a href="https://cursor.sh/">Cursor</a>です :-)</p></li></ul><h2 id="haed544bae8">5. 実践的な型チェック</h2><p>この章では、実際のコードでありそうな型エラーとその解決方法について扱います。</p><h3 id="hfbcb309316">5.1 意図しない型変換</h3><h4 id="h07bd922a7b">5.1.1 型エラーの出るコード例</h4><p>以下は、価格と税率から税込価格を計算しようとしているコードです。</p><pre><code class="language-python"># 税込価格を計算する
def calcurate_total(price: int, tax_rate_percentage: int) -&gt; int:
	tax_rate = tax_rate_percentage / 100
	return price * (1 + tax_rate)

if __name__ == &quot;__main__&quot;:
    print(calcurate_total(900, 10))</code></pre><p>このコードをmypyで型チェックすると、以下のようなエラーが出ます。</p><pre><code class="language-shell">error: Incompatible return value type (got &quot;float&quot;, expected &quot;int&quot;)  [return-value]</code></pre><h4 id="h8cbe228081">5.1.2 原因</h4><p>原因は <code>price * (1 + tax_rate)</code>の部分です。 <code>int</code> 型の値 <code>price</code> と、 <code>float</code> 型の値 <code>tax_rate</code> について計算を行っていますが、このとき <code>price</code> の型が <code>int</code> から <code>float</code> に自動的に変換されます。</p><ul><li> <code>float</code>は<code>int</code>よりも表現できる範囲が広いため、これらを混ぜて演算すると<code>int</code>が<code>float</code>に変換された上で演算されます。このような挙動を<strong>型昇格</strong>といいます。</li></ul><h4 id="hbc7a8127ed">5.1.3 修正案</h4><p>修正の方針ですが、税込価格が整数で欲しい場合は以下のような修正が考えられるでしょう。</p><pre><code class="language-python"># 税込価格を計算する
def calcurate_total(price: int, tax_rate_percentage: int) -&gt; int:
	tax_rate = tax_rate_percentage / 100
	return math.floor(price * (1 + tax_rate)) # 小数点以下を切り捨て</code></pre><p>この場合、<code>math.floor()</code>は<code>float</code>型の値を引数に取って<code>int</code>型の値を返す関数なので、<code>calcurate_total</code>関数の戻り値は<code>int</code>型になります。</p><p>割りとありがちなケアレスミスですが、型ヒントを書いておけばこのようなミスに早く気付くことができます。</p><h3 id="h2ae2f1a608">5.2 Null安全</h3><h4 id="h96d34dd40e">5.2.1 型エラーの出るコード例</h4><p>以下は、辞書からキー &quot;id&quot; に対応する値を取得しようとしているコードです。また、関数内で何やらデバッグログを出そうとしています。</p><pre><code class="language-python">import logging
logging.basicConfig(level=logging.DEBUG, format=&quot;%(message)s&quot;)

def get_id_value(input: dict[str, str]) -&gt; str:
    id_value = input.get(&quot;id&quot;)
    logging.debug(&quot;id_value: &quot; + id_value)
    return id_value

if __name__ == &quot;__main__&quot;:
    print(get_id_value({&quot;id&quot;: &quot;bar&quot;}))</code></pre><p>このコードをmypyで型チェックすると、以下のようなエラーが出ます。</p><pre><code class="language-python">Unsupported operand types for + (&quot;str&quot; and &quot;None&quot;)  [operator]
Incompatible return value type (got &quot;str | None&quot;, expected &quot;str&quot;)  [return-value]</code></pre><h4 id="hfc0ce67b96">5.2.2 原因</h4><p>エラーの内容を大雑把にいうと</p><ul><li>1行目: <code>str</code>型と <code>None</code>型について<code>+</code>演算子を適用できない (つまり、足し算ができない)</li><li>2行目: 関数の戻り値の型ヒントが<code>str</code>だが、mypyが推論した戻り値の型は <code>str | None</code> である</li></ul><p>ということになります。</p><p><code>input.get(&quot;id&quot;)</code> について、<code>input</code>に “id”という名前のキーが含まれていない場合、対応する値の代わりに<code>None</code>が返されるのですが、このコードはそれの考慮を忘れてしまっています。</p><p>また、このコードですが、<code>get_id_value</code>関数にうっかり”id”キーを含まない辞書を渡して実行すると以下のような例外がraiseされてしまいます。</p><pre><code class="language-python">Traceback (most recent call last):
  File &quot;/path-to-script.py&quot;, line 20, in &lt;module&gt;
    print(get_id({&quot;a&quot;: &quot;foo&quot;, &quot;d&quot;: &quot;bar&quot;}))
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File &quot;/path-to-script.py&quot;, line 15, in get_id
    logging.debug(&quot;id_value: &quot; + id_value)
                  ~~~~~~~~~~~~~^~~~~~~~~~
TypeError: can only concatenate str (not &quot;NoneType&quot;) to str</code></pre><p>このような実行時エラーが起こりうる実装を、mypyを使うことによって実行前にチェックできます。</p><h4 id="hb3caff6542">5.2.3 修正案</h4><p>まず、<code>logging.debug()</code>の部分で例外が出ないように修正します。f-stringを使い、変数を文字列にそのまま埋め込むのが手っ取り早いでしょう。</p><pre><code class="language-python">logging.debug(f&quot;id_value: {id_value}&quot;)</code></pre><p>次に、戻り値の型を修正します。今回は ”id” がない場合はとりあえず<code>None</code>を返すようにします。この時、適切な型は<code>str</code>と<code>None</code>のUnion型 <code>str | None</code>です。</p><pre><code class="language-python">def get_id_value(input: dict[str, str]) -&gt; str | None:
  ...</code></pre><p>合わせると、以下のようになります。</p><pre><code class="language-python">import logging
logging.basicConfig(level=logging.DEBUG, format=&quot;%(message)s&quot;)

def get_id_value(input: dict[str, str]) -&gt; str | None:
    id_value = input.get(&quot;id&quot;)
    logging.debug(f&quot;id_value: {id_value}&quot;)
    return id_value

if __name__ == &quot;__main__&quot;:
    print(get_id_value({&quot;id&quot;: &quot;bar&quot;}))</code></pre><p>これは極端な例でしたが、値がNull (Pythonでは<code>None</code>に相当する) である場合のハンドリングを忘れてしまうことはしばしばあります。ある変数がNullではない事を言語レベルで表明できる機能のことを「Null Safety」と呼んだりしますが、mypyによってそれを部分的に実現できます。</p><h2 id="h51351c43d4">6. まとめ</h2><p>この記事では、Pythonの型ヒントとmypyを用いた型チェック方法を説明しました。型ヒントを使用すると、コードのドキュメンテーション、自動補完、型チェックの利点が得られ、開発効率が向上します。また、mypyを使用することにより、型エラーを早期に発見し修正することが可能になります。</p><p>また、一般的にコードを書く時間よりも読む時間の方が長いといわれています。型ヒントを重要な場所(特に、モジュール外から参照されうる関数や変数)に書くことにより、 他の開発者がコードを読む際に理解が容易になります。それにより、特に多人数で開発する際の開発者間の齟齬が小さくなり、結果的に開発の高速化に寄与できるのではないでしょうか。</p><p>どのようなツールを使用するかはプロジェクトやチームの状況によりますが、mypyや型ヒントなどのツールはPython開発をさらに効率的で信頼性の高いものにするための一つの選択肢となるでしょう。</p><p><a href="https://bizfreak.co.jp/recruit" target="_blank" rel="noopener noreferrer nofollow">株式会社Biz Freak</a>は、ロバストなソフトウェアの設計・実装に興味のあるPythonエンジニアを募集しています。</p>

プログラミング

型ヒントと型チェックで開発スピードを落とさずに安全に実装しましょう。

BLOG

【Python #1】はじめてのmypy

RECRUIT