Boto Session Manager

Warnings

• gotcha The 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.
• gotcha For '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.
• gotcha While `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.
• gotcha The `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.

Install

• pip install boto-session-manager Install core library
• pip install "boto3-stubs[all]" Install for Client method auto-complete and Arguments type hints

Imports

• BotoSesManager

  from boto_session_manager import BotoSesManager

• AwsServiceEnum

  from boto_session_manager import AwsServiceEnum

Quickstart

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