boto3に型ヒントを付けるboto3-stubsを試してみました

型ヒント（型アノテーション）とは
boto3-stubs
雑談

こんにちは、アプリケーションサービス部ディベロップメントサービス 2 課の松尾です。

boto3 の型ヒントを追加してくれるboto3-stubs について調べる機会があったので、ブログを書くことにしました。

型ヒント（型アノテーション）とは

変数に代入する型（文字列型、数値型、真偽値型、など…）を宣言時に明記することを型ヒントといいます（型アノテーションと呼ぶこともあります）。
下のコードのように、変数宣言時に : <型> という記述を追加することで、代入する型を明示的に記述することができます。
str や int などの標準の型であれば、追加ライブラリなしで利用できます。

company_name: str = "serverworks"
count: int = 1

type-annotation-example — 型ヒント部分にマウスオーバーするとドキュメントの表示もしてくれます（VSCodeの例）

なお、Pythonの型ヒントで記載するのは「代入できる型」ではなく「代入する型」です。
実行時にエラーになってくれるわけではありません。
意図しない型をエラーにするような強制力はないので、TypeScript のような静的型付け言語に慣れている方は要注意です。

# インタプリタで実行
>>> company_name: int = "serverworks"
>>> type(company_name)
<class 'str'> # intの型ヒントがあっても実行時にstrを代入することが可能

Pythonの型ヒントは VSCodeなどのエディタや各種linterと併用してコード品質を上げるためのサポート機能的な位置付けです。

Pythonドキュメントより引用

Note: The Python runtime does not enforce function and variable type annotations. They can be used by third party tools such as type checkers, IDEs, linters, etc.

注釈: Python ランタイムは、関数や変数の型アノテーションを強制しません。 型アノテーションは、型チェッカー、IDE、linterなどのサードパーティーツールで使われます。

boto3-stubs

ここから本題です。
今回検証したboto3-stubsは、VSCode, PyCharm, Emacs, Sublime Text などのエディタでboto3の型ヒントが使用できるようになる Python パッケージです。
このパッケージを使用することで、標準ではサポートされていない boto3 の型ヒントを扱うことができるようになります。

インストール

標準のインストール方法はPyPIのドキュメントに書いてあるので、この記事では pipenv 環境でのインストールを行います。
インストールは、使用するサービスを明示的に指定する必要があります。
essential を指定すると、使用頻度の高い ec2, s3, rds, lambda, sqs, dynamo, cloudformation を一括インストールできます。

# ec2, s3, rds, lambda, sqs, dynamo, cloudformation を一括インストールする
pipenv install boto3-stubs[essential] --dev

# 特定のパッケージを指定してインストールすることも可能
pipenv install "boto3-stubs[acm]" --dev

# 複数のパッケージを追加することも可能
pipenv install "boto3-stubs[apigateway, essential]" --dev

ちなみに、pipenv で後から対象サービスを追加した際は、最後に実行したインストール内容しか Pipfile に残らない点にご注意ください。

# Pipfileの中身
# 上に記載した例の順でコマンドを実行すると、acm は Pipfileに残らない
[dev-packages]
boto3-stubs = {extras = ["apigateway", "essential"], version = "*"}

動作確認の際には pipenv clean を実行して、Pipfileから消えたパッケージを同期しておくことをお勧めします。
（uninstallしたのにコード補完が消えず混乱した人が書いています）

% pipenv clean
Uninstalling mypy-boto3-acm...

できること

boto3の型ヒント

冒頭に書いた通り、boto3のライブラリに型ヒントを使用できるようになります。
型ヒントに使用するパッケージ名やクラス名は boto3-stubs documentation で確認できます。

import boto3
from mypy_boto3_s3.client import S3Client
from mypy_boto3_s3.service_resource import Object


def main():
    s3_client: S3Client = boto3.client("s3")
    text_file: Object = s3_client.get_object(Bucket="aaa", Key="bbb/ccc.txt")

コード補完

本題と少しずれますが、このインストールによってコード補完が利用できるようになりました。
環境の問題か若干ラグを感じましたが、型ヒントを指定しなくても補完してくれました。

APIの戻りについてもキーの候補を出してくれました。

code-assist-2 — 毎回コンソールに json 出力して確認していたのでこれは嬉しい

ただし、戻りの補完については呼び出し方次第で挙動が変わってしまうようです。

感想

Pythonの型ヒントは実行時に厳密にチェックしてくれないので、mypy_boto3_xx の書き方を覚える手間を考えると型ヒントまで使うかはちょっと考えたいな、と思ってしまいました…。

個人的には型ヒントそのものよりもコード補完機能の部分が嬉しかったです。
boto3の全ての関数はさすがに覚えられないので、何ができるのかコーディングしながら確認できるのはメリットが大きいですね。

s3_client. の入力から1秒くらい待つことがあったのでラグは気にはなりますが、しばらく使ってみようと思います。

雑談

他にも似たようなライブラリがないか探してみたんですが、boto3_type_annotations のGitHub にはフォークされた mypy_boto3 を使え と書いてあって、その後 PyPIのmypy-boto3のページに行ったら 代わりに boto3-stubs をインストールしろ と書いてありました。
某所で見た盥回しのWikiページを思い出しました。