Type annotations for aioboto3

Warnings

• breaking As of mypy-boto3-builder 8.12.0 (which generates types-aioboto3), Python 3.8 is no longer supported for any generated packages. Users on Python 3.8 will encounter issues with newer versions.
  Fix: Upgrade your Python environment to version 3.9 or newer. Ensure your `pyproject.toml` or `setup.cfg` reflects `python_requires >=3.9`.
• breaking Service-specific TypeDef names for method arguments and conflicting names were changed in mypy-boto3-builder 8.9.0. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`, and `CreateDistributionExtraRequestTypeDef` became `CreateDistributionRequestExtraTypeDef`.
  Fix: Update type annotation references in your code to match the new naming conventions. Refer to the specific service stub documentation for updated TypeDef names.
• deprecated The `sms-voice` service stubs were removed in mypy-boto3-builder 8.11.0. Users should migrate to `pinpoint-sms-voice` for related functionality.
  Fix: Replace references to `sms-voice` with `pinpoint-sms-voice` in your code and update imports and client calls accordingly (e.g., `session.client("pinpoint-sms-voice")` and `from types_aioboto3_pinpoint_sms_voice import PinpointSMSVoiceClient`).
• gotcha This library provides type stubs for `aioboto3` and does not include the `aioboto3` runtime itself. It's solely for static type checking; you must install `aioboto3` separately for your application to run.
  Fix: Ensure `pip install aioboto3` is performed in your environment alongside `types-aioboto3`.
• gotcha Even if you install the `types-aioboto3` metapackage (which includes all service stubs), the type hints (e.g., Client classes, TypeDefs) must be imported from their respective service-specific sub-packages (e.g., `types_aioboto3_s3`).
  Fix: Always use `from types_aioboto3_SERVICE.client import ServiceClient` and `from types_aioboto3_SERVICE.type_defs import ...` for specific service types.
• gotcha It is recommended to keep the version of `types-aioboto3` (or its service-specific sub-packages) synchronized with your `aioboto3` runtime version to ensure accurate type hints, as stubs are generated for specific `aioboto3` versions and AWS API shapes.
  Fix: Periodically update both `aioboto3` and `types-aioboto3` simultaneously, or pin their versions in your `requirements.txt` or `pyproject.toml` to prevent mismatches.

Install

• pip install types-aioboto3 Install all service stubs (metapackage)
• pip install types-aioboto3-s3 types-aioboto3-ec2 Install specific service stubs (recommended for smaller footprint)

Imports

• S3Client

  from types_aioboto3_s3.client import S3Client

  Type hints for clients are imported from service-specific sub-packages, even if the main 'types-aioboto3' metapackage is installed.
• BucketTypeDef

  from types_aioboto3_s3.type_defs import BucketTypeDef

  TypeDefs for AWS responses and request bodies are provided by these stubs, not directly from aioboto3 runtime.
• Session

  import aioboto3

  The aioboto3 session object itself is from the runtime library, not the type stubs. The stubs provide types for what `session.client()` returns.

Quickstart

This quickstart demonstrates how to integrate `types-aioboto3` for static type checking with an `aioboto3` S3 client. It shows how to import and apply `S3Client` and `BucketTypeDef` to enhance code clarity, enable IDE autocompletion, and catch potential errors at development time.

import aioboto3
import asyncio
from types_aioboto3_s3.client import S3Client
from types_aioboto3_s3.type_defs import BucketTypeDef

async def list_s3_buckets_typed():
    session = aioboto3.Session()
    async with session.client("s3") as client:
        # Type hint the client to enable autocompletion and static checks
        client: S3Client
        
        response = await client.list_buckets()
        
        # Type hint the list of buckets for better type safety
        buckets: list[BucketTypeDef] = response.get("Buckets", [])
        
        if not buckets:
            print("No S3 buckets found or access denied.")
            return

        print("S3 Buckets:")
        for bucket in buckets:
            print(f"  - {bucket['Name']}")

async def main():
    # aioboto3 uses standard AWS credential chain (e.g., environment variables, 
    # ~/.aws/credentials, IAM roles). No hardcoded keys are needed here.
    await list_s3_buckets_typed()

if __name__ == "__main__":
    asyncio.run(main())