Lambda ハンドラーの型定義、どっちを使う？ aws-lambda-typing vs aws-lambda-powertools

AI を使って Lambda のハンドラーを生成していると、event や context 引数の型定義に2種類のライブラリが使われることに気づきました。

# パターン1: aws-lambda-typing
from aws_lambda_typing import context as context_, events
def handler(event: events.SQSEvent, context: context_.Context):
    ...

# パターン2: aws-lambda-powertools
from aws_lambda_powertools.utilities.data_classes import SQSEvent, event_source
from aws_lambda_powertools.utilities.typing import LambdaContext
@event_source(data_class=SQSEvent)
def handler(event: SQSEvent, context: LambdaContext):
    ...

どちらを採用すべきか調べてみたので、まとめます。

TL;DR（結論）

観点	aws-lambda-typing	aws-lambda-powertools
目的	型定義に特化	サーバーレス開発の総合ツールキット
event 型	✅ `events.SQSEvent` 等 (TypedDict)	✅ `SQSEvent` 等 (Data Class)
context 型	✅ `context.Context`	✅ `LambdaContext`
依存関係	軽量（型定義のみ）	多機能（Logger, Tracer, Metrics 等含む）
おすすめケース	型ヒントだけ欲しい場合	Powertools の他機能も使う場合

結論：基本的には aws-lambda-powertools がおすすめ。パッケージサイズを極力減らしたい場合のみ aws-lambda-typing を検討。

各ライブラリの概要

aws-lambda-typing

PyPI: https://pypi.org/project/aws-lambda-typing/
目的: Lambda の event, context, response の型定義を提供
特徴: 型定義に特化した軽量パッケージ（TypedDict ベース）

uv add aws-lambda-typing

from aws_lambda_typing import context as context_, events

def handler(event: events.SQSEvent, context: context_.Context) -> dict:
    for record in event['Records']:  # 辞書アクセス
        print(record['body'])
    return {"statusCode": 200}

サポートしている event 型（一部）:

APIGatewayProxyEventV1 / V2
SQSEvent
S3Event
DynamoDBStreamEvent
SNSEvent
EventBridgeEvent
KinesisStreamEvent
CloudWatchLogsEvent
その他多数...

aws-lambda-powertools

ドキュメント: https://docs.powertools.aws.dev/lambda/python/
GitHub: https://github.com/aws-powertools/powertools-lambda-python
目的: サーバーレス開発のベストプラクティスを実装する総合ツールキット
特徴: AWS 公式が提供・メンテナンス（Data Class ベース）

uv add aws-lambda-powertools

from aws_lambda_powertools.utilities.data_classes import SQSEvent, event_source
from aws_lambda_powertools.utilities.typing import LambdaContext

@event_source(data_class=SQSEvent)
def handler(event: SQSEvent, context: LambdaContext) -> dict:
    for record in event.records:  # プロパティアクセス
        print(record.body)
    return {"statusCode": 200}

サポートしている event 型（一部）:

APIGatewayProxyEvent / APIGatewayProxyEventV2
SQSEvent
S3Event
DynamoDBStreamEvent
SNSEvent
EventBridgeEvent
KinesisStreamEvent
CloudWatchLogsEvent
BedrockAgentEvent
KafkaEvent
その他多数...

Powertools のその他の機能:

Tracer: X-Ray トレーシング
Logger: 構造化ログ
Metrics: CloudWatch カスタムメトリクス
Event Handler: API Gateway / AppSync のルーティング
Validation: JSON Schema バリデーション
Idempotency: 冪等性の実装
Parameters: SSM / Secrets Manager からのパラメータ取得
Batch Processing: SQS / Kinesis のバッチ処理

event 型と context 型の違い

context 型の違い

項目	aws-lambda-typing	aws-lambda-powertools
提供するプロパティ	同じ	同じ
アクセス方法	プロパティアクセス	プロパティアクセス
機能的な差	なし	なし

→ context 型は両ライブラリでほぼ同等（機能差なし）

どちらもプロパティアクセス（context.aws_request_id 等）が可能で、IDE の補完も同様に効きます。

event 型の実装方式の違い

項目	aws-lambda-typing	aws-lambda-powertools
実装方式	TypedDict	Data Class
アクセス方法	辞書アクセス `event['Records']`	プロパティアクセス `event.records`
読み取り専用の明示	❌ なし（辞書なので書き換え可能に見える）	✅ `@property` で読み取り専用が明示
ヘルパーメソッド	❌ なし	✅ あり（デコード、パース等）
`@event_source` デコレーター	❌ なし	✅ あり（自動パース）
IDE 補完	✅	✅（プロパティアクセスでより便利）

→ event 型は aws-lambda-powertools の方が機能的に充実

@property による読み取り専用の明示

aws-lambda-powertools の Data Class では、各属性が @property として定義されています。これにより：

IDE が「読み取り専用」であることを認識
誤って値を書き換えようとすると警告が出る
イベントデータの不変性（immutability）が型レベルで保証される

# aws-lambda-powertools: @property で読み取り専用
def handler(event: SQSEvent, context):
    record = event.records[0]
    record.body = "new value"  # ❌ IDE が警告（読み取り専用プロパティへの代入）

# aws-lambda-typing: TypedDict は辞書なので書き換え可能に見える
def handler(event: events.SQSEvent, context):
    event['Records'][0]['body'] = "new value"  # ⚠️ IDE は警告しない（辞書だから）

Lambda イベントは本来書き換えるべきものではないため、@property による読み取り専用の明示は意図しないバグを防ぐのに役立ちます。

プロパティアクセスによる IDE 補完の利点

aws-lambda-powertools はプロパティアクセスのため、IDE で . を打つだけで候補が表示されます。

# aws-lambda-powertools: プロパティアクセスで補完が効く
event.records[0].  # ← ここで body, message_id 等の候補が表示される

# aws-lambda-typing: 辞書アクセスなのでキー名を覚えておく必要がある
event['Records'][0]['']  # ← 補完が効きにくい

aws-lambda-powertools の event 型が便利な例

# Kinesis: Base64 デコード + JSON パースが簡単
from aws_lambda_powertools.utilities.data_classes import KinesisStreamEvent

def handler(event: KinesisStreamEvent, context):
    for record in event.records:
        # ヘルパーメソッドでデコード＆パース
        data = record.kinesis.data_as_json()  # Base64 → JSON を一発で

# CloudWatch Logs: 圧縮データの解凍も簡単
from aws_lambda_powertools.utilities.data_classes import CloudWatchLogsEvent

def handler(event: CloudWatchLogsEvent, context):
    # gzip 解凍 + Base64 デコード + JSON パースを一発で
    logs = event.parse_logs_data()
    for log_event in logs.log_events:
        print(log_event.message)

aws-lambda-typing の場合、これらの処理は自分で実装する必要があります。

LambdaContext で使えるプロパティ・メソッド

両ライブラリとも、Lambda の context オブジェクトに対して以下の型ヒントを提供します：

プロパティ/メソッド	種類	説明
`function_name`	property	Lambda 関数の名前
`function_version`	property	関数のバージョン
`invoked_function_arn`	property	呼び出しに使用された ARN
`memory_limit_in_mb`	property	割り当てメモリ（MB）
`aws_request_id`	property	リクエスト ID
`log_group_name`	property	CloudWatch Logs のロググループ
`log_stream_name`	property	CloudWatch Logs のログストリーム
`identity`	property	Cognito ID 情報
`client_context`	property	モバイルアプリからのコンテキスト
`get_remaining_time_in_millis()`	method	タイムアウトまでの残り時間（ミリ秒）

使い分けの基準

aws-lambda-powertools を選ぶケース

✅ Logger, Metrics, Tracer など Powertools の他機能を使う予定がある

すでに Powertools を導入しているなら統一すべき

✅ IDE の補完機能をフル活用したい

@property による読み取り専用の明示
ヘルパーメソッド（data_as_json() 等）の補完
プロパティアクセス event.records の補完

aws-lambda-typing を選ぶケース

✅ パッケージサイズを極力減らしたい

Powertools は多機能な分、サイズが大きい
Lambda のコールドスタート時間を少しでも短くしたい
ただし、これが問題になるケースは稀

併用は必要？

基本的に不要です。どちらか一方に統一するのがおすすめ。

両ライブラリとも event と context の型を提供しているため、混在させる必要はありません。

パターン	event	context	評価
Powertools 統一	`data_classes.SQSEvent`	`LambdaContext`	✅ おすすめ（Powertools 利用時）
aws-lambda-typing 統一	`events.SQSEvent`	`context.Context`	✅ おすすめ（型定義のみ欲しい時）
混在	`events.SQSEvent` (typing)	`LambdaContext` (powertools)	⚠️ 非推奨（依存が増えるだけ）

まとめ

基本的には aws-lambda-powertools を採用するのがおすすめ。

判断基準	推奨ライブラリ
基本（迷ったらこれ）	aws-lambda-powertools
Logger, Metrics, Tracer 等を使う予定	aws-lambda-powertools
IDE 補完をフル活用したい（`@property`、ヘルパーメソッド）	aws-lambda-powertools
パッケージサイズを極力減らしたい	aws-lambda-typing

AI が生成するコードで型定義がばらつく場合は、プロジェクトで統一したいライブラリを明示的に指示するか、既存コードのインポート文を参照させると良いと思います。