Type annotations for boto3 S3

Warnings

• breaking Python 3.8 support has been removed in `mypy-boto3-builder` version 8.12.0, which generates this package. Projects using `types-boto3-s3` must now target Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or higher.
• breaking The `mypy-boto3-builder` (version 8.9.0) introduced changes to `TypeDef` naming conventions for service operations, specifically shortening packed argument names (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`) and moving `Extra` postfixes. This might require updating type hint declarations for specific S3 operations if your code relies on these specific `TypeDef` names.
  Fix: Review and update `TypeDef` import paths and names in your code to match the new conventions.
• gotcha This package (`types-boto3-s3`) provides *only* type annotations. The actual `boto3` library must be installed separately for your code to run correctly. This package is a development dependency, not a runtime dependency.
  Fix: Ensure `boto3` is installed in your runtime environment (e.g., `pip install boto3`).
• gotcha For optimal performance and to avoid unnecessary runtime dependencies, always enclose `types-boto3-s3` imports within an `if TYPE_CHECKING:` block. This ensures that the type stubs are only processed by static analysis tools and not imported at runtime.
  Fix: Wrap type stub imports like `from types_boto3_s3.client import S3Client` with `if TYPE_CHECKING: ...`.
• gotcha PyCharm users may experience slow performance or high CPU usage due to how PyCharm handles `Literal` overloads with `types-boto3` packages. In such cases, using `types-boto3-lite` (e.g., `pip install types-boto3-lite[s3]`) is recommended, which offers a more RAM-friendly alternative by not providing `session.client`/`resource` overloads, requiring explicit type annotations.
  Fix: Consider `pip uninstall types-boto3-s3` and `pip install types-boto3-lite[s3]` if experiencing PyCharm performance issues.

Install

• pip install types-boto3-s3 boto3 Install types-boto3-s3 and boto3

Imports

• S3Client

  from types_boto3_s3.client import S3Client

  For type-hinting the S3 client returned by `boto3.client('s3')`.
• S3ServiceResource

  from types_boto3_s3.service_resource import S3ServiceResource

  For type-hinting the S3 service resource returned by `boto3.resource('s3')`.
• ListBucketsOutputTypeDef

  from types_boto3_s3.type_defs import ListBucketsOutputTypeDef

  For type-hinting the response structure of `s3_client.list_buckets()`.

Quickstart

This quickstart demonstrates how to use `types-boto3-s3` to add type hints to a `boto3` S3 client. The `TYPE_CHECKING` guard ensures that the type stubs are only imported during static analysis, preventing unnecessary runtime dependencies. It initializes an S3 client and lists bucket names, with all relevant variables type-hinted for better code quality and IDE support.

import boto3
from typing import TYPE_CHECKING

# Only import type stubs during type checking to avoid runtime dependency
if TYPE_CHECKING:
    from types_boto3_s3.client import S3Client
    from types_boto3_s3.type_defs import ListBucketsOutputTypeDef

def list_s3_bucket_names() -> list[str]:
    # The actual boto3 client is used at runtime
    s3_client: 'S3Client' = boto3.client(
        "s3",
        aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),
        aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
        region_name=os.environ.get('AWS_REGION', 'us-east-1')
    )

    print("Listing S3 buckets...")
    response: 'ListBucketsOutputTypeDef' = s3_client.list_buckets()
    bucket_names = [bucket['Name'] for bucket in response.get('Buckets', [])]
    return bucket_names

if __name__ == "__main__":
    import os
    # Ensure AWS credentials and region are set in environment variables for a runnable example
    # e.g., export AWS_ACCESS_KEY_ID='YOUR_KEY' AWS_SECRET_ACCESS_KEY='YOUR_SECRET' AWS_REGION='us-east-1'
    if not all(os.environ.get(k) for k in ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION']):
        print("Please set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION environment variables.")
    else:
        try:
            buckets = list_s3_bucket_names()
            if buckets:
                print(f"Found buckets: {', '.join(buckets)}")
            else:
                print("No S3 buckets found.")
        except Exception as e:
            print(f"An error occurred: {e}")