{"id":4902,"library":"boto-session-manager","title":"Boto Session Manager","description":"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.","status":"active","version":"1.8.1","language":"en","source_language":"en","source_url":"https://github.com/aws-samples/boto_session_manager-project","tags":["aws","boto3","session management","developer tools","cloud"],"install":[{"cmd":"pip install boto-session-manager","lang":"bash","label":"Install core library"},{"cmd":"pip install \"boto3-stubs[all]\"","lang":"bash","label":"Install for Client method auto-complete and Arguments type hints"}],"dependencies":[{"reason":"The library is a wrapper/enhancement for boto3, implicitly relying on its functionality.","package":"boto3","optional":false},{"reason":"Required for full client method auto-complete and argument type hints in development environments.","package":"boto3-stubs","optional":true}],"imports":[{"symbol":"BotoSesManager","correct":"from boto_session_manager import BotoSesManager"},{"symbol":"AwsServiceEnum","correct":"from boto_session_manager import AwsServiceEnum"}],"quickstart":{"code":"from boto_session_manager import BotoSesManager\n\n# Initialize the session manager (uses default AWS credentials chain)\nbsm = BotoSesManager()\n\n# Get an S3 client. Clients are cached for reuse.\ns3_client = bsm.get_client(\"s3\")\n\n# Alternatively, use attribute access for common services for auto-complete\n# s3_client = bsm.s3_client\n\n# Example: List S3 buckets\ntry:\n    response = s3_client.list_buckets()\n    print(\"S3 Buckets:\")\n    for bucket in response.get(\"Buckets\", []):\n        print(f\"- {bucket['Name']}\")\nexcept Exception as e:\n    print(f\"Error listing buckets: {e}\")\n\n# Example: Assuming an IAM role\n# This assumes 'MY_ASSUME_ROLE_ARN' environment variable is set\n# or replaced with a valid ARN.\nassume_role_arn = os.environ.get('MY_ASSUME_ROLE_ARN', 'arn:aws:iam::123456789012:role/MyTestRole')\nif '123456789012' not in assume_role_arn: # Simple check to avoid running with dummy ARN\n    try:\n        print(f\"\\nAttempting to assume role: {assume_role_arn}\")\n        assumed_bsm = bsm.assume_role(\n            RoleArn=assume_role_arn,\n            RoleSessionName=\"my-assumed-session\"\n        )\n        ec2_client_assumed = assumed_bsm.get_client(\"ec2\")\n        print(f\"Successfully obtained EC2 client with assumed role: {ec2_client_assumed}\")\n    except Exception as e:\n        print(f\"Error assuming role: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.5.1"},{"fix":"Run `pip install \"boto3-stubs[all]\"` in your development environment. This is a development-time dependency and usually not required in production.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}