Type annotations for boto3 STS

raw JSON →
1.42.3 verified Tue May 12 auth: no python install: verified

mypy-boto3-sts provides PEP 561-compliant type annotations for the `boto3` STS (AWS Security Token Service) client, compatible with mypy, pyright, VSCode, PyCharm, and other type-checking tools. It ensures type safety and offers enhanced code completion for `boto3.client("sts")` operations. The current version, 1.42.3, aligns with boto3 1.42.3 and is generated by mypy-boto3-builder 8.12.0. The library follows the release cadence of `boto3` and its builder.

pip install mypy-boto3-sts boto3

Common errors

error error: Skipping analyzing "boto3": module is installed, but missing library stubs or py.typed marker [import-untyped] ↓
cause Mypy is unable to find and apply the type stub files for `boto3`, often because the service-specific stub package (`mypy-boto3-sts` or `boto3-stubs[sts]`) was not installed, or mypy's environment isn't correctly configured to find them.
fix
Ensure you have installed the core boto3-stubs package with the STS extra, or the standalone mypy-boto3-sts package: python -m pip install 'boto3-stubs[sts]' or python -m pip install mypy-boto3-sts.
error ModuleNotFoundError: No module named 'mypy_boto3_sts' ↓
cause The `mypy_boto3_sts` package or `boto3-stubs[sts]` was not installed in your Python environment, or the environment where you're running your code/type checker doesn't have it available.
fix
Install the mypy-boto3-sts package directly, or install boto3-stubs with the STS extra: python -m pip install mypy-boto3-sts or python -m pip install 'boto3-stubs[sts]'.
error AttributeError: 'STSClient' object has no attribute 'non_existent_method' ↓
cause While `mypy-boto3-sts` provides type hints for the correct `STSClient` methods, this error indicates you are attempting to call a method that does not exist on the AWS STS client, or you are using an outdated version of the stubs that doesn't reflect the latest `boto3` client methods.
fix
Check the boto3 documentation for the correct method names and their parameters. Ensure your mypy-boto3-sts (or boto3-stubs) and boto3 packages are up-to-date to reflect the latest AWS API: python -m pip install --upgrade boto3 mypy-boto3-sts.
error error: Missing type parameters for generic type "dict" [type-arg] ↓
cause This is a general `mypy` error that occurs when generic types like `list` or `dict` are used without specifying their type arguments (e.g., `dict` instead of `dict[str, Any]`), especially when strict `mypy` flags like `--disallow-any-generics` are enabled. This can happen when processing responses from boto3 calls if intermediate types are not fully annotated.
fix
Explicitly specify the type parameters for generic types, especially when dealing with nested structures in Boto3 responses. For example, use Dict[str, Any] or Dict[str, SpecificResponseTypeDef] instead of just dict. You can import TypedDict for precise response typing from mypy_boto3_sts.type_defs.
error Undefined variable 'STSClient' (for pylint) ↓
cause When using `typing.TYPE_CHECKING` to conditionally import `mypy-boto3-sts` types for static analysis only, linters like Pylint may report 'Undefined variable' errors for the types in the `else` block if they are not defined there.
fix
Provide a fallback definition for the type outside the TYPE_CHECKING block, typically by assigning object to the type: if TYPE_CHECKING: from mypy_boto3_sts.client import STSClient else: STSClient = object.

Warnings

breaking Starting with `mypy-boto3-builder` 8.12.0 (which generates this package), support for Python 3.8 has been removed. Users on Python 3.8 should update their Python version. ↓
fix Upgrade to Python 3.9 or newer.
breaking TypedDict names for 'packed' method arguments may have changed, becoming shorter (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`). This was part of `mypy-boto3-builder` 8.9.0. ↓
fix Update import paths and type references to the new, shorter TypedDict names.
gotcha For optimal IDE support (especially VSCode) and `mypy` accuracy, it is recommended to explicitly annotate `boto3.client()` calls with the `STSClient` type, even though auto-discovery works for basic cases in tools like PyCharm. ↓
fix Add explicit type annotations like `client: STSClient = session.client("sts")`.
gotcha When using `mypy-boto3-sts` with Pylint, you might encounter 'undefined variable' warnings if the type stubs are not installed in the production environment. A common workaround is to use `if TYPE_CHECKING:` blocks. ↓
fix Wrap type-only imports in `if TYPE_CHECKING:` blocks and define fallback `object` aliases for runtime compatibility (see `mypy-boto3` documentation for examples).
breaking Runtime operations with `boto3` (and by extension, `mypy-boto3` usage) require valid AWS credentials to be configured. This error indicates that `boto3` could not find any credentials in the standard locations. ↓
fix Ensure AWS credentials are properly configured in the environment (e.g., environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, shared credential files like `~/.aws/credentials`, or IAM roles/profiles for EC2/ECS/EKS). Refer to the `boto3` documentation for credential configuration methods.
breaking Runtime errors related to missing AWS credentials can occur if `boto3` is not configured properly, as `mypy-boto3-sts` provides only type stubs and relies on `boto3` for actual runtime functionality. ↓
fix Ensure `boto3` is installed and properly configured with AWS credentials (e.g., via environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, a shared credentials file, or IAM roles).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.55s 51.0M
3.10 alpine (musl) - - 0.54s 50.8M
3.10 slim (glibc) wheel 4.1s 0.42s 52M
3.10 slim (glibc) - - 0.44s 51M
3.11 alpine (musl) wheel - 0.75s 54.0M
3.11 alpine (musl) - - 0.83s 53.8M
3.11 slim (glibc) wheel 3.8s 0.72s 55M
3.11 slim (glibc) - - 0.63s 54M
3.12 alpine (musl) wheel - 0.62s 45.3M
3.12 alpine (musl) - - 0.66s 45.1M
3.12 slim (glibc) wheel 3.3s 0.63s 46M
3.12 slim (glibc) - - 0.69s 46M
3.13 alpine (musl) wheel - 0.58s 45.0M
3.13 alpine (musl) - - 0.62s 44.7M
3.13 slim (glibc) wheel 3.0s 0.63s 46M
3.13 slim (glibc) - - 0.64s 45M
3.9 alpine (musl) wheel - 0.44s 50.4M
3.9 alpine (musl) - - 0.46s 50.3M
3.9 slim (glibc) wheel 4.7s 0.44s 51M
3.9 slim (glibc) - - 0.42s 51M

Imports

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to apply `mypy-boto3-sts` type hints to a `boto3` STS client and an `assume_role` call. It shows importing the `STSClient` type for the client object and a `TypeDef` for the method's response, enabling static analysis and IDE auto-completion. Remember to configure AWS credentials for `boto3` to function.

import boto3
from mypy_boto3_sts.client import STSClient
from mypy_boto3_sts.type_defs import AssumeRoleResponseTypeDef
from os import environ

# Instantiate a boto3 session and an STS client, with explicit type hinting.
# In a real scenario, boto3 would pick up credentials from environment variables,
# shared credential files, or IAM roles.
session = boto3.Session()
client: STSClient = session.client("sts")

try:
    # Example: Assume a role with type-hinted arguments and response.
    # Replace 'YOUR_ROLE_ARN' with an actual AWS IAM Role ARN for testing.
    role_arn = environ.get("AWS_STS_ROLE_ARN", "arn:aws:iam::123456789012:role/MyTestRole")
    
    response: AssumeRoleResponseTypeDef = client.assume_role(
        RoleArn=role_arn,
        RoleSessionName="MySessionName",
        DurationSeconds=900  # Minimum duration is 900 seconds (15 minutes)
    )

    print("Successfully assumed role.")
    print(f"Assumed Role User ARN: {response['AssumedRoleUser']['Arn']}")
    print(f"Credentials Expiration: {response['Credentials']['Expiration']}")
except client.exceptions.ClientError as e:
    print(f"AWS Client Error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
last verified Tue May 12
next check Sat Jun 27