Type Annotations for boto3 (full)

1.42.88 · active · verified Sat Apr 11

types-boto3-full provides comprehensive type annotations for the popular AWS SDK for Python, boto3. It is an 'all-in-one' package that bundles all service-specific type stubs generated by mypy-boto3-builder. This allows for static type checking of boto3 code using tools like MyPy, catching potential errors before runtime. The current version is 1.42.88, matching the boto3 version it provides stubs for, and is frequently updated in sync with boto3 releases and mypy-boto3-builder enhancements.

Warnings

breaking Python 3.8 support has been removed as of `mypy-boto3-builder` version 8.12.0 (which generates `types-boto3-full` 1.42.x and above).
Fix: Upgrade your Python environment to 3.9 or newer. If you must use Python 3.8, pin `types-boto3-full` to a version older than 1.42.0 (e.g., `types-boto3-full<1.42`).
gotcha `types-boto3-full` provides type stubs only. You must also install `boto3` separately for your code to run at runtime.
Fix: Always install `boto3` alongside `types-boto3-full` (e.g., `pip install boto3 types-boto3-full`).
breaking The `sms-voice` service was removed in `mypy-boto3-builder` 8.11.0 (generating `types-boto3-full` 1.41.x+). It is no longer supported; use `pinpoint-sms-voice` instead.
Fix: Migrate your code to use the `pinpoint-sms-voice` service client instead of `sms-voice`.
breaking TypedDict naming conventions were changed in `mypy-boto3-builder` 8.9.0 (generating `types-boto3-full` 1.39.x+), potentially shortening names or reordering suffixes (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`).
Fix: Review your code for direct references to specific TypedDict names and adjust them according to the new conventions. Type checkers will highlight these breaking changes.
gotcha The package `types-boto3-full` itself is not meant to be imported directly at runtime. It's a collection of stub files that a type checker (like MyPy) uses to understand `boto3`'s types.
Fix: Do not add `import types_boto3_full` to your runtime code. Instead, import specific type definitions from `boto3_stubs` conditionally using `if TYPE_CHECKING:`.

Install

pip install types-boto3-full boto3 Install stubs and boto3

Imports

S3Client
```
from boto3_stubs.s3.client import S3Client
```
types-boto3-full is a meta-package. Its type definitions are typically imported from the `boto3_stubs` namespace (e.g., `boto3_stubs.service_name.client` or `boto3_stubs.session`). You typically use `TYPE_CHECKING` to conditionally import these.
Session
```
from boto3_stubs.session import Session
```
Use this for type-hinting the main boto3 session object.

Quickstart

This quickstart demonstrates how to use types-boto3-full for static type checking with boto3. It shows conditional imports for type stubs and then applies them to a standard boto3 client interaction. Ensure you have `boto3` and `mypy` installed alongside `types-boto3-full`.

from typing import TYPE_CHECKING
import boto3
import os

# Conditionally import type stubs only for type checking
if TYPE_CHECKING:
    from boto3_stubs.s3.client import S3Client
    from boto3_stubs.session import Session

# Instantiate a boto3 session (runtime code)
session: 'Session' = boto3.session.Session(
    region_name=os.environ.get('AWS_REGION', 'us-east-1'),
    aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', 'DUMMY_KEY'),
    aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', 'DUMMY_SECRET')
)

# Get an S3 client and type-hint it
s3_client: 'S3Client' = session.client('s3')

try:
    # This call will be type-checked by MyPy
    buckets = s3_client.list_buckets()
    print(f"Successfully listed {len(buckets.get('Buckets', []))} S3 buckets.")
except Exception as e:
    print(f"Error listing S3 buckets: {e}")

# To type-check this file, run:
# pip install mypy
# mypy your_script_name.py

view raw JSON →