{"id":2335,"library":"types-boto3-s3","title":"Type annotations for boto3 S3","description":"This library provides PEP 561 compliant type annotations (stub files) for the `boto3` S3 service, generated by `mypy-boto3-builder`. It enhances static analysis, auto-completion, and type checking in IDEs and tools like `mypy` for code interacting with AWS S3 via `boto3`, addressing the dynamic nature of `boto3` clients and resources.","status":"active","version":"1.42.85","language":"en","source_language":"en","source_url":"https://github.com/youtype/mypy_boto3_builder","tags":["aws","boto3","s3","mypy","type-hints","stub","typing","dev-dependency"],"install":[{"cmd":"pip install types-boto3-s3 boto3","lang":"bash","label":"Install types-boto3-s3 and boto3"}],"dependencies":[{"reason":"Provides the runtime functionality that types-boto3-s3 offers type hints for. This package is only stubs.","package":"boto3","optional":false},{"reason":"A common static type checker used to leverage these type annotations.","package":"mypy","optional":true},{"reason":"May be required for full type compatibility on older Python versions, though modern versions often use built-in typing features. The builder dynamically determines this dependency.","package":"typing-extensions","optional":true}],"imports":[{"note":"For type-hinting the S3 client returned by `boto3.client('s3')`.","symbol":"S3Client","correct":"from types_boto3_s3.client import S3Client"},{"note":"For type-hinting the S3 service resource returned by `boto3.resource('s3')`.","symbol":"S3ServiceResource","correct":"from types_boto3_s3.service_resource import S3ServiceResource"},{"note":"For type-hinting the response structure of `s3_client.list_buckets()`.","symbol":"ListBucketsOutputTypeDef","correct":"from types_boto3_s3.type_defs import ListBucketsOutputTypeDef"}],"quickstart":{"code":"import boto3\nfrom typing import TYPE_CHECKING\n\n# Only import type stubs during type checking to avoid runtime dependency\nif TYPE_CHECKING:\n    from types_boto3_s3.client import S3Client\n    from types_boto3_s3.type_defs import ListBucketsOutputTypeDef\n\ndef list_s3_bucket_names() -> list[str]:\n    # The actual boto3 client is used at runtime\n    s3_client: 'S3Client' = boto3.client(\n        \"s3\",\n        aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),\n        aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),\n        region_name=os.environ.get('AWS_REGION', 'us-east-1')\n    )\n\n    print(\"Listing S3 buckets...\")\n    response: 'ListBucketsOutputTypeDef' = s3_client.list_buckets()\n    bucket_names = [bucket['Name'] for bucket in response.get('Buckets', [])]\n    return bucket_names\n\nif __name__ == \"__main__\":\n    import os\n    # Ensure AWS credentials and region are set in environment variables for a runnable example\n    # e.g., export AWS_ACCESS_KEY_ID='YOUR_KEY' AWS_SECRET_ACCESS_KEY='YOUR_SECRET' AWS_REGION='us-east-1'\n    if not all(os.environ.get(k) for k in ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_REGION']):\n        print(\"Please set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION environment variables.\")\n    else:\n        try:\n            buckets = list_s3_bucket_names()\n            if buckets:\n                print(f\"Found buckets: {', '.join(buckets)}\")\n            else:\n                print(\"No S3 buckets found.\")\n        except Exception as e:\n            print(f\"An error occurred: {e}\")\n\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or higher.","message":"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.","severity":"breaking","affected_versions":">=8.12.0 (builder), >=1.42.85 (types-boto3-s3)"},{"fix":"Review and update `TypeDef` import paths and names in your code to match the new conventions.","message":"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.","severity":"breaking","affected_versions":">=8.9.0 (builder)"},{"fix":"Ensure `boto3` is installed in your runtime environment (e.g., `pip install boto3`).","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Wrap type stub imports like `from types_boto3_s3.client import S3Client` with `if TYPE_CHECKING: ...`.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider `pip uninstall types-boto3-s3` and `pip install types-boto3-lite[s3]` if experiencing PyCharm performance issues.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}