Registry / aws / boto3-assume

boto3-assume

JSON →
library0.2.1pypypi✓ verified 85d ago

boto3-assume is a Python library that simplifies creating boto3 assume role sessions with automatic credential refreshing. It provides a convenient API for managing temporary AWS credentials via IAM roles. The library is actively maintained with frequent, small releases.

pip install boto3-assume
INSTALL
IMPORT
SIG · BOTO3-ASSUME
B
boto3-assume
awspythonv0.2.1
Install
3.8s avg
Import
723ms
Disk
49MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.760s · 50.9MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.8s · import 0.686s · 51MB
49MB installed
● package 49MB
Code
Verified usage

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

assume_role
from boto3_assume import assume_role
from boto3_assume import assume_role_session
`assume_role_session` was deprecated in v0.2.0 and replaced by `assume_role`.
assume_role_aio_session
from aioboto3_assume import assume_role_aio_session
from boto3_assume import assume_role_aio_session
`assume_role_aio_session` was moved to the `aioboto3-assume` package in v0.2.0.

This quickstart demonstrates how to use `boto3-assume.assume_role` to obtain a boto3 session with temporary credentials from an assumed IAM role, and then use that session to interact with an AWS service like S3. Ensure your environment has AWS credentials configured (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or `AWS_PROFILE`) and replace the placeholder `role_arn`.

import boto3_assume import boto3 import os # Replace with your actual role ARN and session name # For local testing, ensure your AWS credentials are configured (e.g., via ~/.aws/credentials or environment variables) role_arn = os.environ.get('AWS_ASSUME_ROLE_ARN', 'arn:aws:iam::123456789012:role/MyTestRole') role_session_name = os.environ.get('AWS_ASSUME_SESSION_NAME', 'Boto3AssumeQuickstartSession') if not role_arn.startswith('arn:aws:iam::'): print("Warning: AWS_ASSUME_ROLE_ARN not set or invalid. Using a placeholder ARN. This example will likely fail unless configured correctly.") try: # Assume the role and get a boto3 session object assumed_session = boto3_assume.assume_role( role_arn=role_arn, role_session_name=role_session_name ) # Use the assumed session to create a client (e.g., S3) s3_client = assumed_session.client('s3') print(f"Successfully assumed role '{role_arn}' with session name '{role_session_name}'.") # Example: List S3 buckets using the assumed role print("Attempting to list S3 buckets...") buckets_response = s3_client.list_buckets() bucket_names = [b['Name'] for b in buckets_response.get('Buckets', [])] print(f"Found {len(bucket_names)} S3 buckets: {bucket_names[:3]}...") except Exception as e: print(f"An error occurred: {e}") print("Please ensure your AWS credentials are configured and the role ARN is correct and accessible.")
Debug
Known issues
breakingThe primary function `assume_role_session` was deprecated and replaced by `assume_role` in v0.2.0. The new `assume_role` function offers more flexibility.
fix
Update your code to use `from boto3_assume import assume_role` and call `boto3_assume.assume_role(...)` instead of `assume_role_session`.
affects: >=0.2.0
breakingAsynchronous (aioboto3) functionality, specifically `assume_role_aio_session`, was moved to a separate package `aioboto3-assume` to simplify dependencies.
fix
If you need async assume role functionality, install `aioboto3-assume` (`pip install aioboto3-assume`) and import `assume_role_aio_session` from there.
affects: >=0.2.0
breakingSupport for Python versions 3.7-3.9 was removed in v0.1.3.
fix
Upgrade your Python environment to 3.10 or newer to use versions 0.1.3 and above.
affects: >=0.1.3
gotchaPrevious versions (before v0.1.2) had non-functional `boto3` and `aioboto3` package extras which were removed. These extras were not needed as `boto3` is a core dependency.
fix
No action needed for newer versions. If on an older version and trying to use extras, simply remove the extra specification in your `pip install` command (e.g., `pip install boto3-assume`).
affects: <0.1.2
Errors
Common errors & fixes
AttributeError: module 'boto3_assume' has no attribute 'assume_role_session'
You are using version 0.2.0 or newer of boto3-assume, but your code is still calling the deprecated `assume_role_session` function.
fix
Update your import and function call to `from boto3_assume import assume_role` and use `boto3_assume.assume_role(...)`.
ImportError: cannot import name 'assume_role_aio_session' from 'boto3_assume'
`assume_role_aio_session` was moved to a new package, `aioboto3-assume`, in version 0.2.0.
fix
Install `aioboto3-assume` (`pip install aioboto3-assume`) and change your import to `from aioboto3_assume import assume_role_aio_session`.
SyntaxError: future feature annotations is not defined
Your Python version is too old (e.g., 3.7-3.9) for boto3-assume versions 0.1.3 and above, which dropped support for these Python versions.
fix
Upgrade your Python environment to version 3.10 or newer.
Upgrade
Version history
0.2.1latest on PyPI · released Jan 15, 2026
Audit
Dependencies
boto3requiredCore dependency for AWS SDK functionality, used for creating and managing AWS sessions.
Agent activity
14 hits · last 30 days
node
14
Resources
boto3-assume — pip install boto3-assume · libregistry