boto3-stubs Type Annotations for AWS SDK for Python

Warnings

• breaking Dropped Python 3.8 support. As of `mypy-boto3-builder` version 8.12.0, Python 3.8 is no longer supported for any `boto3-stubs` packages. Projects must use Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or newer.
• breaking Migration to PEP 561 packages. This changes how stubs are packaged and distributed, potentially affecting build systems or direct imports from stub packages.
  Fix: Ensure your project's `pyproject.toml` or `setup.py` correctly references PEP 561-compliant stub packages. Re-evaluate any custom build or packaging logic that interacts directly with stub files.
• breaking Service `sms-voice` was removed and replaced by `pinpoint-sms-voice`. If you were using `sms-voice` types, they are no longer generated.
  Fix: Update your code to use the `pinpoint-sms-voice` service and its corresponding types where applicable.
• breaking TypeDef naming conventions changed for packed method arguments and conflicting names. TypeDefs like `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`, and `CreateDistributionExtraRequestTypeDef` became `CreateDistributionRequestExtraTypeDef`.
  Fix: Update explicit TypeDef references in your code to match the new naming conventions.
• gotcha This library only provides type annotations. You must still install `boto3` (and `botocore`) for your code to actually run. `boto3-stubs` does not include the AWS SDK itself.
  Fix: Ensure `pip install boto3` is part of your project's dependency management.
• gotcha PyCharm's performance can be slow with `Literal` overloads. It is recommended to use `boto3-stubs-lite` or external type checkers (MyPy/PyRight) if you experience high CPU usage or slow performance in PyCharm.
  Fix: Consider installing `boto3-stubs-lite` (`pip install boto3-stubs-lite`) or configure PyCharm to use MyPy/PyRight as the primary type checker.

Install

• pip install boto3-stubs Install all stubs
• pip install 'boto3-stubs[s3]' Install stubs for a specific service (e.g., S3)
• pip install 'boto3-stubs[essential]' Install stubs for essential services (CloudFormation, DynamoDB, EC2, Lambda, RDS, S3, SQS)
• pip install boto3-stubs-lite Install lite version (less RAM, explicit annotations required)

Imports

• Session

  import boto3; from boto3.session import Session

  boto3-stubs works by augmenting the existing boto3 imports with type information; explicit imports from mypy_boto3_SERVICE are typically only needed for direct type hints.
• S3Client

  from mypy_boto3_s3.client import S3Client

  For explicit type annotations of a client, import the client type from the specific `mypy_boto3_SERVICE` module.
• Bucket

  from mypy_boto3_s3.service_resource import Bucket

  For explicit type annotations of a service resource, import the resource type from the specific `mypy_boto3_SERVICE` module.

Quickstart

This quickstart demonstrates how to use `boto3-stubs` to add type annotations to `boto3` client calls. By installing `boto3-stubs` (or `boto3-stubs[s3]` for S3 specific stubs), type checkers like MyPy will understand the return types and argument types of `boto3.client('s3')`, and IDEs will provide better auto-completion. Explicitly importing `S3Client` from `mypy_boto3_s3.client` allows for clear type hinting of the client object itself.

import boto3
from mypy_boto3_s3.client import S3Client
import os

def list_s3_buckets(region_name: str = os.environ.get('AWS_REGION', 'us-east-1')) -> list[str]:
    """Lists S3 bucket names with type hints."""
    # boto3-stubs automatically provides type hints for client() and resource() calls
    s3_client: S3Client = boto3.client("s3", region_name=region_name)
    response = s3_client.list_buckets()
    bucket_names = [bucket['Name'] for bucket in response.get('Buckets', [])]
    return bucket_names

if __name__ == "__main__":
    print(f"S3 Buckets: {list_s3_buckets()}")