Registry / type-stubs / mypy-boto3-s3

mypy-boto3-s3

JSON →
library1.42.67pypypiunverified

mypy-boto3-s3 provides comprehensive type annotations for the `boto3` AWS S3 service, enhancing type checking, code completion, and error detection in Python projects. It is generated by `mypy-boto3-builder`, ensuring compatibility with popular IDEs (VSCode, PyCharm) and type checkers (mypy, pyright). The library version typically mirrors the corresponding `boto3` version, indicating active and frequent releases in sync with AWS SDK updates.

type-stubsaws
pip install mypy-boto3-s3 boto3
Install & Compatibility
Where this runs
tested against v1.43.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.950 runs
installs and imports cleanly · install 0.0s · import 1.032s · 53.9MB
glibc
py 3.103.950 runs
installs and imports cleanly · install 5.6s · import 0.914s · 54MB
52MB installed
● package 52MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

S3Client
from mypy_boto3_s3.client import S3Client
from 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
from boto3.s3.service_resource import S3ServiceResource
The correct type annotation for a boto3 S3 service resource is provided by `mypy-boto3-s3`.

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}")
Debug
Known issues
breakingSupport 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).
affects: mypy-boto3-builder >= 8.12.0
breakingType 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.
affects: mypy-boto3-builder >= 8.9.0
deprecatedThe 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.
affects: < 8.9.0 (for `mypy-boto3` itself)
gotchaPyCharm 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.
affects: All versions with PyCharm
gotchaAs 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.
affects: mypy-boto3-builder >= 8.12.0
gotchaInteracting with AWS services (e.g., listing S3 buckets) requires valid AWS credentials to be configured in the environment (e.g., via AWS environment variables, shared credential files, or IAM roles). Without credentials, `boto3` operations will fail with an `Unable to locate credentials` error.
fix
Ensure AWS credentials are properly configured in your environment. Refer to the AWS SDK documentation for Python for guidance on credential configuration.
affects: All versions of `boto3` and `mypy-boto3-*` when interacting with AWS
gotchaThe application failed to locate AWS credentials, which are required for authenticating with AWS services like S3. This is a common runtime configuration issue with `boto3` itself, independent of `mypy-boto3-s3` type stubs.
fix
Ensure AWS credentials are configured correctly in your environment. This can be achieved through environment variables (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), shared credential files (`~/.aws/credentials`), IAM roles (for EC2 instances or other AWS services), or AWS Single Sign-On (SSO). Refer to the official `boto3` documentation for detailed credential configuration methods.
affects: All versions of `boto3` (and consequently any related stub packages like `mypy-boto3-s3`)
Upgrade
Version history
1.43.14latest on PyPI
Audit
Dependencies
boto3requiredThis package provides type annotations for the boto3 library, so boto3 is required for runtime functionality.
typing-extensionsoptionalRequired for older Python versions to support newer typing features. Automatically managed by install_requires.
Agent activity
22 hits · last 30 days
node
6
seranking-bot
3
ahrefsbot
2
Amazon
1
googlebot
1
Resources