{"id":1753,"library":"types-aiobotocore-s3","title":"types-aiobotocore-s3 Type Stubs","description":"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.","status":"active","version":"3.4.0","language":"en","source_language":"en","source_url":"https://github.com/youtype/mypy_boto3_builder","tags":["aws","s3","aiobotocore","type-hints","mypy","stub","async"],"install":[{"cmd":"pip install types-aiobotocore-s3","lang":"bash","label":"Install type stubs"}],"dependencies":[{"reason":"Provides the underlying asynchronous AWS client library for which these are type stubs.","package":"aiobotocore","optional":false},{"reason":"Required for compatibility with older Python versions, though types-aiobotocore-s3 now requires Python >=3.9, it's still listed as a dependency in its pyproject.toml.","package":"typing_extensions","optional":false}],"imports":[{"note":"While `aiobotocore.client` provides the runtime client, `types_aiobotocore_s3.client` provides the explicit type for static analysis.","wrong":"from aiobotocore.client import S3Client","symbol":"S3Client","correct":"from types_aiobotocore_s3.client import S3Client"},{"note":"AioSession is obtained via `get_session()`. The type stubs automatically apply to the objects returned by `aiobotocore` functions and methods.","symbol":"AioSession","correct":"from aiobotocore.session import get_session"}],"quickstart":{"code":"import asyncio\nfrom os import environ\nfrom typing import TYPE_CHECKING\n\n# Only import S3Client for type checking, not for runtime\nif TYPE_CHECKING:\n    from types_aiobotocore_s3.client import S3Client\n\nfrom aiobotocore.session import get_session\n\nasync def list_s3_buckets():\n    session = get_session()\n    async with session.create_client(\"s3\", region_name=\"us-east-1\") as client:\n        # The 'client' object is automatically typed as S3Client\n        # if types-aiobotocore-s3 is installed.\n        # Explicit annotation for clarity:\n        s3_client: S3Client = client\n        response = await s3_client.list_buckets()\n        for bucket in response.get(\"Buckets\", []):\n            print(f\"Bucket Name: {bucket['Name']}\")\n\n        # Example of type-checked operation\n        # await s3_client.non_existent_method() # MyPy would flag this\n\nif __name__ == \"__main__\":\n    # Set dummy credentials for quickstart if not already set\n    environ.setdefault('AWS_ACCESS_KEY_ID', 'testing')\n    environ.setdefault('AWS_SECRET_ACCESS_KEY', 'testing')\n    environ.setdefault('AWS_SECURITY_TOKEN', 'testing')\n    environ.setdefault('AWS_DEFAULT_REGION', 'us-east-1')\n\n    asyncio.run(list_s3_buckets())\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=3.4.0 (for types-aiobotocore-s3), >=8.12.0 (for mypy-boto3-builder)"},{"fix":"If you explicitly import or reference TypeDefs from the stub package, update their names according to the new conventions.","message":"TypeDef names for packed method arguments changed in `mypy-boto3-builder` 8.9.0, adopting shorter names. For example, `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`.","severity":"breaking","affected_versions":">=2.17.0 (for types-aiobotocore-s3), >=8.9.0 (for mypy-boto3-builder)"},{"fix":"Ensure your packaging and type-checking tools are compatible with PEP 561 stub packages. Most modern tools should handle this automatically.","message":"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.","severity":"breaking","affected_versions":">=3.4.0 (for types-aiobotocore-s3), >=8.12.0 (for mypy-boto3-builder)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}