boto3-session

A wrapper library for the boto3.session.Session class in Python.

Requirement

• Python versions >=3.9
• uv (for development purposes)

Installation

To install boto3-session, run the following command:

$ pip install boto3-session

Usage

boto3_session.Session can be used similarly to boto3.Session:

from boto3_session import Session

session = Session()
s3 = session.resource('s3')
bucket = s3.Bucket(...)
...

The some of parameters for boto3_session.Session are akin to those for boto3.Session:

• profile_name: The AWS profile name.
• aws_access_key_id: The AWS access key ID.
• aws_secret_access_key: The AWS secret access key.
• aws_session_token: The AWS session token.
• region_name: The AWS region name.

Additionally, boto3_session.Session supports management of AssumeRole:

• role_arn: The AWS role ARN for AssumeRole. If set, aws_access_key_id, aws_secret_access_key, and aws_session_token are replaced with the AssumeRole credentials.
• session_name: The AWS session name, defaulting to "boto3_session".

boto3_session.Session includes client and resource methods, like boto3.Session. By default, the following configuration is passed to them:

Config(retries={'max_attempts': self.max_attempts, 'mode': self.retry_mode})

In boto3, the default values for max_attempts and mode are 5 and legacy, respectively. In boto3_session, they default to 3 and "standard".

These defaults can be overridden by passing the following parameters to boto3_session.Session:

• retry_mode: The retry mode for failed requests, defaulting to "standard".
• max_attempts: The maximum number of retry attempts for failed requests, defaulting to 10.

For SSO login:

• use_device_code: A boolean flag to force the use of the device authorization flow for SSO login. Defaults to False.

See the next section for details.

SSO Login

For configurations with SSO login, if the token is absent or expired, boto3_session.Session automatically orchestrates an IAM Identity Center login flow. By default the library re-implements the AWS CLI v2 PKCE authorization code flow (version 2.22.0 and newer) and opens the one-time verification URL in your browser. If the interactive flow cannot run for some reason, it falls back to invoking aws sso login.

If you need to force the older device authorization flow (for example when the browser-based PKCE flow is not available), set the use_device_code flag when creating the session:

Session(use_device_code=True)

This mirrors the --use-device-code option introduced in modern AWS CLI releases.

• Install or update the latest version of the AWS CLI - AWS Command Line Interface