boto3-stubs-full

Warnings

• breaking Python 3.8 support has been removed. Projects using Python 3.8 must either upgrade Python or pin `boto3-stubs-full` to a version prior to 8.12.0.
  Fix: Upgrade your Python environment to 3.9 or higher, or explicitly specify an older `boto3-stubs-full` version (e.g., `<8.12.0`).
• breaking The `sms-voice` service is no longer supported and has been removed. Use `pinpoint-sms-voice` instead.
  Fix: Migrate your code to use the `pinpoint-sms-voice` service client instead of `sms-voice`.
• breaking Breaking changes were introduced to `TypeDef` naming conventions. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`, and conflicting `Extra` postfixes were moved (e.g., `CreateDistributionExtraRequestTypeDef` to `CreateDistributionRequestExtraTypeDef`).
  Fix: Update your code to reflect the new `TypeDef` naming conventions as indicated by your type checker.
• gotcha Mismatched versions between `boto3` and `boto3-stubs-full` can lead to incorrect or missing type hints. The `boto3-stubs` project generally aims to keep pace with `boto3` releases.
  Fix: Always install `boto3-stubs-full` with a version compatible with your `boto3` installation, ideally by matching their major and minor versions (e.g., `pip install 'boto3==1.28.x' 'boto3-stubs-full==1.28.x'`).
• gotcha PyCharm users may experience slow performance or high CPU usage due to `Literal` overloads. It is recommended to use `boto3-stubs-lite` or an external type checker (like MyPy or Pyright) with PyCharm's type checker disabled.
  Fix: For PyCharm, consider `pip install boto3-stubs-lite` or disable PyCharm's built-in type checker and use `mypy` or `pyright` externally.
• gotcha When importing specific `mypy_boto3_*` types (e.g., `from mypy_boto3_s3.client import S3Client`), it is best practice to wrap these imports within an `if TYPE_CHECKING:` block. Failing to do so can make the stubs an unnecessary runtime dependency, potentially leading to circular import issues or larger deployment sizes.
  Fix: Always use `from typing import TYPE_CHECKING` and `if TYPE_CHECKING: ...` for explicit type imports to ensure they are only processed by type checkers.

Install

• pip install boto3 boto3-stubs-full Install boto3 with full stubs

Imports

• boto3

  import boto3

  boto3-stubs-full provides type hints; at runtime, you import boto3 as usual.
• S3Client

  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from mypy_boto3_s3.client import S3Client

  For explicit type annotations in type-checking contexts, import specific client types from `mypy_boto3_*` sub-packages. Avoid `BaseClient` as it lacks service-specific details.

Quickstart

This quickstart demonstrates using `boto3-stubs-full` with a standard boto3 S3 client. After installing `boto3-stubs-full`, your IDE and static type checkers like MyPy will automatically provide type hints for `boto3` calls. For explicit type annotations, `mypy_boto3_s3.client.S3Client` is imported conditionally for type-checking only.

from typing import TYPE_CHECKING
import boto3
import os

# Boto3-stubs-full enhances type checking for standard boto3 usage.
# For explicit type annotations, import service clients within a TYPE_CHECKING block.
if TYPE_CHECKING:
    from mypy_boto3_s3.client import S3Client

def list_s3_buckets(region: str) -> None:
    # Initialize an S3 client. IDEs and type checkers will recognize the type
    # even without explicit type hints if boto3-stubs-full is installed.
    s3_client: S3Client = boto3.client('s3', region_name=region)

    print(f"Listing S3 buckets in {region}:")
    try:
        response = s3_client.list_buckets()
        for bucket in response.get('Buckets', []):
            print(f"- {bucket['Name']}")
    except Exception as e:
        print(f"Error listing buckets: {e}")

if __name__ == "__main__":
    aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
    list_s3_buckets(aws_region)