mypy-boto3-s3 Type Annotations for AWS S3

Warnings

• breaking Support for Python 3.8 was removed from `mypy-boto3-builder` version 8.12.0 onwards. This affects all generated stub packages, including `mypy-boto3-s3`. Projects on Python 3.8 will need to use an older version of the stubs or upgrade their Python interpreter.
  Fix: Upgrade to Python 3.9 or newer, or pin `mypy-boto3-s3` to a version compatible with Python 3.8 (e.g., <1.40.0, corresponding to builder <8.12.0).
• breaking Type Definition (`TypeDef`) naming conventions changed in `mypy-boto3-builder` version 8.9.0. This can lead to shorter names for packed method arguments (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`) and reordering of postfixes for conflicting names. Existing explicit imports of these `TypeDef`s will break.
  Fix: Update `TypeDef` import paths and names in your code to reflect the new conventions. Consult the specific service's documentation for the correct new names.
• deprecated The original `mypy-boto3` package is considered legacy and users are encouraged to migrate to the `types-boto3` ecosystem. While `mypy-boto3-s3` is a specific service stub package, the overarching `mypy-boto3` project has transitioned to `types-boto3`.
  Fix: For new projects, prefer `types-boto3` and its service-specific extras (`boto3-stubs[s3]`). For existing projects, ensure your stub installation aligns with the `types-boto3` recommendations.
• gotcha PyCharm users might experience slow performance and high CPU usage due to `Literal` overloads. This is a known issue (PY-40997) with PyCharm's type checker.
  Fix: Consider using `boto3-stubs-lite[s3]` for a more RAM-friendly option (requires explicit type annotations), or disable PyCharm's internal type checker and use an external tool like mypy or pyright instead.
• gotcha As of `mypy-boto3-builder` 8.12.0, packages migrated to PEP 561 for distributing type information. While this generally improves automatic discovery, it is crucial that the stub package (`mypy-boto3-s3` or `boto3-stubs[s3]`) is installed in the same Python environment where `mypy` or other type checkers are run.
  Fix: Ensure `pip install mypy-boto3-s3` (or `boto3-stubs[s3]`) is run in the same virtual environment as your project and type checker. Mypy's `--no-site-packages` flag will disable this functionality if used.

Install

• pip install mypy-boto3-s3 boto3 Install standalone S3 stubs and boto3
• pip install 'boto3-stubs[s3]' boto3 Install S3 stubs as part of boto3-stubs (recommended)

Imports

• S3Client

  from mypy_boto3_s3.client import S3Client

  The correct type annotation for a boto3 S3 client is provided by `mypy-boto3-s3`.
• S3ServiceResource

  from mypy_boto3_s3.service_resource import S3ServiceResource

  The correct type annotation for a boto3 S3 service resource is provided by `mypy-boto3-s3`.

Quickstart

This quickstart demonstrates how to obtain type-hinted S3 clients and service resources using `mypy-boto3-s3`. Explicit type annotations for `boto3.client('s3')` and `boto3.resource('s3')` are provided by importing `S3Client` and `S3ServiceResource`. This enables full code completion and type checking for S3 operations.

import boto3
from mypy_boto3_s3.client import S3Client
from mypy_boto3_s3.service_resource import S3ServiceResource, Bucket

def get_s3_client() -> S3Client:
    """Returns a type-hinted S3 client."""
    # Type is automatically discovered by mypy and IDEs (if configured)
    return boto3.client("s3")

def get_s3_resource() -> S3ServiceResource:
    """Returns a type-hinted S3 service resource."""
    # Type is automatically discovered by mypy and IDEs (if configured)
    return boto3.resource("s3")

def get_s3_bucket(bucket_name: str) -> Bucket:
    """Returns a type-hinted S3 Bucket resource."""
    s3_resource: S3ServiceResource = boto3.resource("s3")
    return s3_resource.Bucket(bucket_name)

if __name__ == "__main__":
    s3_client = get_s3_client()
    print(f"S3 Client type: {type(s3_client)}")
    # Example usage: list buckets
    try:
        response = s3_client.list_buckets()
        print("Buckets:")
        for bucket in response.get("Buckets", []):
            print(f"  - {bucket['Name']}")
    except Exception as e:
        print(f"Error listing buckets: {e}")

    # Example resource usage
    # s3_resource = get_s3_resource()
    # my_bucket = get_s3_bucket("your-bucket-name")
    # print(f"Bucket name: {my_bucket.name}")