Registry / aws / boto-session-manager

boto-session-manager

JSON →
library2.0.1pypypi✓ verified 22d ago

boto_session_manager is a lightweight Python library designed to simplify the management of AWS boto3 sessions within application code. It enhances the native boto3 SDK by providing features such as boto3 Client auto-completion, cached boto3 Clients, in-application IAM role assumption, and temporary credential management for the AWS CLI. It aims to provide a more user-friendly development experience with boto3. It is currently at version 1.8.1 and actively maintained.

pip install boto-session-manager
INSTALL
IMPORT
SIG · BOTO-SESSION-MANAG
B
boto-session-manager
awspythonv2.0.1
Install
24.8s avg
Import
565ms
Disk
291MB
Pass rate
9/ 10
Env Coverage9 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.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
glibc
py 3.10
✓ 0.05s
✓ 49.95s
py 3.11
1/2 runs
✓ 49.55s
py 3.12
✓ 0.05s
✓ 23.85s
py 3.13
✓ —
✓ 20.65s
py 3.9
✓ 0.05s
✓ 54.3s
291MB installed
● package 291MB
Code
Verified usage

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

BotoSesManager
from boto_session_manager import BotoSesManager
from boto_session_manager import BotoSesManager

This quickstart demonstrates how to initialize the BotoSesManager, retrieve a cached boto3 client for a service (e.g., S3), and perform a basic operation. It also includes an example of assuming an IAM role, which is a key feature of the library, assuming a valid role ARN is provided via an environment variable or hardcoded for testing.

from boto_session_manager import BotoSesManager # Initialize the session manager (uses default AWS credentials chain) bsm = BotoSesManager() # Get an S3 client. Clients are cached for reuse. s3_client = bsm.get_client("s3") # Alternatively, use attribute access for common services for auto-complete # s3_client = bsm.s3_client # Example: List S3 buckets try: response = s3_client.list_buckets() print("S3 Buckets:") for bucket in response.get("Buckets", []): print(f"- {bucket['Name']}") except Exception as e: print(f"Error listing buckets: {e}") # Example: Assuming an IAM role # This assumes 'MY_ASSUME_ROLE_ARN' environment variable is set # or replaced with a valid ARN. assume_role_arn = os.environ.get('MY_ASSUME_ROLE_ARN', 'arn:aws:iam::123456789012:role/MyTestRole') if '123456789012' not in assume_role_arn: # Simple check to avoid running with dummy ARN try: print(f"\nAttempting to assume role: {assume_role_arn}") assumed_bsm = bsm.assume_role( RoleArn=assume_role_arn, RoleSessionName="my-assumed-session" ) ec2_client_assumed = assumed_bsm.get_client("ec2") print(f"Successfully obtained EC2 client with assumed role: {ec2_client_assumed}") except Exception as e: print(f"Error assuming role: {e}")
Debug
Known issues
gotchaThe auto-refreshable assumed role feature (introduced in v1.5.1) utilizes non-public APIs from `botocore`. These internal APIs are not officially supported and may lead to unstable behavior or breaking changes in future `botocore` updates.
fix
Be aware of potential instability. For critical production workflows requiring highly stable assumed roles, monitor upstream `botocore` changes or consider implementing custom refresh logic if issues arise.
affects: >=1.5.1
gotchaFor 'Client method auto complete' and 'Arguments type hint' features to work correctly in your IDE, you need to explicitly install `boto3-stubs` with the `[all]` extra (e.g., `pip install "boto3-stubs[all]"`). Without this, your IDE may not provide the expected autocompletion or type checking for boto3 clients obtained through `boto-session-manager`.
fix
Run `pip install "boto3-stubs[all]"` in your development environment. This is a development-time dependency and usually not required in production.
affects: All versions
gotchaWhile `boto-session-manager` helps manage `boto3` sessions, the underlying `boto3.client()` method (when called directly without a session, or if multiple `BotoSesManager` instances are created incorrectly in a multi-threaded application) is not strictly thread-safe during client *creation* (though the client object itself is thread-safe). This can lead to `KeyError: 'credential_provider'` in highly concurrent scenarios.
fix
Ensure that `BotoSesManager` instances are created once and reused across threads/processes, or that clients are obtained from a single, shared `BotoSesManager` instance. Avoid creating new `BotoSesManager` instances or directly calling `boto3.client()` within hot paths of multi-threaded code. `boto-session-manager`'s caching mechanism for clients inherently helps mitigate this if used properly.
affects: All versions
gotchaThe `BotoSesManager.awscli()` context manager temporarily modifies the default AWS CLI credentials to match the session defined by `BotoSesManager`. While designed to revert automatically, users should be mindful of this temporary state change, especially in environments where concurrent AWS CLI operations are expected.
fix
Ensure that operations that rely on a specific AWS CLI credential context are performed within the `with bsm.awscli():` block. Avoid relying on the modified CLI credentials outside of this context manager if other CLI operations might be affected.
affects: All versions
Upgrade
Version history
2.0.1latest on PyPI · released Apr 24, 2026
Audit
Dependencies
boto3requiredThe library is a wrapper/enhancement for boto3, implicitly relying on its functionality.
boto3-stubsoptionalRequired for full client method auto-complete and argument type hints in development environments.
Agent activity
16 hits · last 30 days
node
14
Resources
boto-session-manager — pip install boto-session-manager · libregistry