types-aiobotocore-s3 Type Stubs

3.4.0 · active · verified Thu Apr 09

types-aiobotocore-s3 provides comprehensive type annotations for `aiobotocore`'s S3 service, enabling static type checking with tools like MyPy. It is part of the `mypy-boto3-builder` project, which generates stubs for all `aiobotocore` services. The library follows a rapid release cadence, often aligning with `aiobotocore` and `mypy-boto3-builder` updates, with its current version being 3.4.0.

Warnings

breaking Support for Python 3.8 was removed in `mypy-boto3-builder` version 8.12.0. Users on Python 3.8 should use an older version of `types-aiobotocore-s3` or upgrade their Python interpreter.
Fix: Upgrade Python to 3.9 or newer, or pin `types-aiobotocore-s3` to a version compatible with Python 3.8 (e.g., <3.0.0, which corresponds to builder versions <8.12.0).
breaking TypeDef names for packed method arguments changed in `mypy-boto3-builder` 8.9.0, adopting shorter names. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`.
Fix: If you explicitly import or reference TypeDefs from the stub package, update their names according to the new conventions.
breaking The `mypy-boto3-builder` project migrated to PEP 561 package structure in version 8.12.0. While this primarily affects package distribution and discovery, it might impact custom build systems or environments that expect the older stub package layout.
Fix: Ensure your packaging and type-checking tools are compatible with PEP 561 stub packages. Most modern tools should handle this automatically.
gotcha The `types-aiobotocore-s3` package provides static type annotations for `aiobotocore`. For your code to run, you must also install the `aiobotocore` library itself, and ensure its version is compatible with the type stubs.
Fix: Always install `aiobotocore` alongside `types-aiobotocore-s3` (e.g., `pip install aiobotocore types-aiobotocore-s3`). Refer to the `types-aiobotocore-s3` `pyproject.toml` for the exact `aiobotocore` version it targets.

Install

pip install types-aiobotocore-s3 Install type stubs

Imports

S3Client
```
from types_aiobotocore_s3.client import S3Client
```
While `aiobotocore.client` provides the runtime client, `types_aiobotocore_s3.client` provides the explicit type for static analysis.
AioSession
```
from aiobotocore.session import get_session
```
AioSession is obtained via `get_session()`. The type stubs automatically apply to the objects returned by `aiobotocore` functions and methods.

Quickstart

This quickstart demonstrates how to use `aiobotocore` with `types-aiobotocore-s3` for type-hinted interaction with Amazon S3. Once `types-aiobotocore-s3` is installed, `aiobotocore` client objects automatically gain type information. For explicit annotations, the `S3Client` type can be imported from `types_aiobotocore_s3.client` within a `TYPE_CHECKING` block to avoid runtime dependency. The example lists all S3 buckets in a specified region.

import asyncio
from os import environ
from typing import TYPE_CHECKING

# Only import S3Client for type checking, not for runtime
if TYPE_CHECKING:
    from types_aiobotocore_s3.client import S3Client

from aiobotocore.session import get_session

async def list_s3_buckets():
    session = get_session()
    async with session.create_client("s3", region_name="us-east-1") as client:
        # The 'client' object is automatically typed as S3Client
        # if types-aiobotocore-s3 is installed.
        # Explicit annotation for clarity:
        s3_client: S3Client = client
        response = await s3_client.list_buckets()
        for bucket in response.get("Buckets", []):
            print(f"Bucket Name: {bucket['Name']}")

        # Example of type-checked operation
        # await s3_client.non_existent_method() # MyPy would flag this

if __name__ == "__main__":
    # Set dummy credentials for quickstart if not already set
    environ.setdefault('AWS_ACCESS_KEY_ID', 'testing')
    environ.setdefault('AWS_SECRET_ACCESS_KEY', 'testing')
    environ.setdefault('AWS_SECURITY_TOKEN', 'testing')
    environ.setdefault('AWS_DEFAULT_REGION', 'us-east-1')

    asyncio.run(list_s3_buckets())

view raw JSON →