Botocore Stubs

1.42.41 · active · verified Sat Mar 28

Botocore Stubs provides comprehensive type annotations and code completion for the `botocore` library, the low-level interface to Amazon Web Services. This package, part of the `mypy_boto3_builder` project, is designed to enhance static type analysis with tools like MyPy and Pyright, and improve IDE auto-completion for `botocore`'s dynamically generated classes. It is actively maintained with versions aligned to corresponding `botocore` releases, with the current version being 1.42.41.

Warnings

gotcha botocore-stubs only provides type hints for the low-level `botocore` library, not for the higher-level `boto3` library. Boto3 includes additional abstractions (e.g., `resource` objects, specific helper methods like `upload_file`) that `botocore-stubs` will not type. For `boto3` specific typing, consider `boto3-stubs` (part of the same `mypy_boto3_builder` project).
Fix: If using `boto3`, install `boto3-stubs` (e.g., `pip install boto3-stubs[essential]`) in addition to or instead of `botocore-stubs`.
gotcha Type stubs are only effective when used with a compatible static type checker (e.g., MyPy, Pyright) or an IDE with strong type-hinting support. Installing `botocore-stubs` alone will not provide runtime changes or visual hints without these tools.
Fix: Integrate a type checker like MyPy (`pip install mypy`) or Pyright (`npm install -g pyright`) into your development workflow. Configure your IDE (e.g., VSCode with Pylance, PyCharm) to use these tools.
gotcha The version of `botocore-stubs` should ideally align with the version of your installed `botocore` library. Mismatched versions may lead to incomplete or incorrect type hints, especially for new features or deprecated APIs in `botocore`.
Fix: Ensure `botocore-stubs` is updated alongside `botocore`. Use `pip install --upgrade botocore-stubs botocore` to keep them synchronized, or specify exact versions in your `requirements.txt`.
breaking Version 1.29.0 removed deprecated stubs for client and endpoint_provider modules. If you were relying on type hints for previously deprecated interfaces within these modules, your type checking might now fail or report missing attributes.
Fix: Update your code to use the non-deprecated `botocore` APIs. Consult the `botocore` documentation and `botocore-stubs` changelog for details on specific removed stubs.
breaking Version 1.29.26 included a fix for `RuleSetStandardLibrary` naming within the `endpoint_provider` module. If your code directly referenced this internal naming for type hints before this fix, it might now cause type checker errors due to the correction.
Fix: Review any direct type references to `botocore.endpoint_provider.RuleSetStandardLibrary` or related components and adjust to the corrected naming, if applicable. Direct interaction with these internal components is generally discouraged.

Install

pip install botocore-stubs Install latest version

Imports

S3Client
```
from botocore.client import S3Client
```
botocore-stubs integrates directly with botocore; type checkers automatically use the stubs for standard botocore imports. Explicitly importing types for annotation (e.g., in a function signature) uses the original botocore module path.
Session
```
from botocore.session import Session
```
Standard botocore session import, which then uses the stubs for client creation methods.

Quickstart

This quickstart demonstrates how to initialize a botocore session and create an S3 client. With `botocore-stubs` installed, type checkers like MyPy or Pyright will provide full code completion and static analysis for the `s3_client` object and its methods, such as `list_buckets()`.

import os
from botocore.session import Session
from botocore.client import S3Client # For type hinting the client

def get_s3_client() -> S3Client:
    """
    Returns a typed S3 client from botocore. 
    botocore-stubs provides the type hints for S3Client.
    """
    # Ensure AWS credentials are set up, e.g., via environment variables
    # AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
    session = Session()
    # The return type of session.create_client('s3') is dynamically generated.
    # The type checker uses botocore-stubs to infer it as S3Client.
    return session.create_client('s3', region_name=os.environ.get('AWS_REGION', 'us-east-1'))

if __name__ == "__main__":
    s3_client = get_s3_client()
    try:
        # This call will have type hints thanks to botocore-stubs
        response = s3_client.list_buckets()
        print("Successfully listed S3 buckets:")
        for bucket in response.get('Buckets', []):
            print(f"- {bucket['Name']}")
    except Exception as e:
        print(f"Error listing S3 buckets: {e}")
        print("Ensure you have AWS credentials configured (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION environment variables).")

view raw JSON →