boto3-assume

0.2.1 · active · verified Fri Apr 17

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.

Common errors

```
AttributeError: module 'boto3_assume' has no attribute 'assume_role_session'
```
cause 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'
```
cause `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
```
cause 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.

Warnings

breaking The 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`.
breaking Asynchronous (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.
breaking Support 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.
gotcha Previous 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`).

Install

pip install boto3-assume Install stable version

Imports

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

Quickstart

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.")

view raw JSON →