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.
Install & Compatibility
Where this runs
tested against v1.43.0 · 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
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.592s · 51.2MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 3.8s · import 0.556s · 52MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
STSClient
✓ from mypy_boto3_sts.client import STSClient
Imports the type for the STS client returned by `boto3.client("sts")`.
AssumeRoleResponseTypeDef
✓ from mypy_boto3_sts.type_defs import AssumeRoleResponseTypeDef
Imports a TypedDict representing the structure of the `assume_role` response for precise type checking.
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}")
Debug
Known issues
breakingStarting 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.fixUpgrade to Python 3.9 or newer.
affects: >=8.12.0 of mypy-boto3-builder (affecting mypy-boto3-sts 1.42.3 and newer)
breakingTypedDict 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.fixUpdate import paths and type references to the new, shorter TypedDict names.
affects: >=8.9.0 of mypy-boto3-builder (affecting generated packages)
gotchaFor 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.fixAdd explicit type annotations like `client: STSClient = session.client("sts")`. affects: All
gotchaWhen 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.fixWrap type-only imports in `if TYPE_CHECKING:` blocks and define fallback `object` aliases for runtime compatibility (see `mypy-boto3` documentation for examples).
affects: All
breakingRuntime 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.fixEnsure 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.
affects: All
breakingRuntime 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.fixEnsure `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).
affects: All
Audit
Dependencies
boto3requiredProvides the underlying AWS SDK for which type annotations are generated.
typing-extensionsoptionalRequired for certain type features on older Python versions, though less critical for Python 3.9+.