Usage

To use boto3-refresh-session, you must have AWS credentials configured locally. Refer to the authorization documentation for details on supported authentication methods.

Basic Initialization

Everything in boto3 is ultimately built on the boto3.session.Session object — including Client and Resource objects. boto3-refresh-session extends this interface while adding automatic credential refresh.

Creating a session is straightforward:

from boto3_refresh_session import RefreshableSession

assume_role_kwargs = {
    "RoleArn": "<your-role-arn>",
    "RoleSessionName": "<your-role-session-name>",
}

session = RefreshableSession(
    assume_role_kwargs=assume_role_kwargs
)

s3 = session.client('s3')

You can also create a Resource the same way:

s3 = session.resource('s3')

Optional: set this session globally as the default for boto3:

import boto3
boto3.DEFAULT_SESSION = session
s3 = boto3.client('s3')  # will use the custom session automatically

Parameters

At a minimum, you must provide parameters for the STS assume_role call via assume_role_kwargs:

assume_role_kwargs = {
    "RoleArn": "<your-role-arn>",
    "RoleSessionName": "<your-session-name>",
    "DurationSeconds": 3600,  # optional
}

Optional keyword arguments for the underlying boto3.client("sts") can be passed via sts_client_kwargs:

sts_client_kwargs = {
    "config": Config(retries={"max_attempts": 5})
}

And any arguments accepted by boto3.session.Session (e.g., region_name, etc.) can be passed directly:

session = RefreshableSession(
    assume_role_kwargs=assume_role_kwargs,
    sts_client_kwargs=sts_client_kwargs,
    region_name="us-east-1"
)

Refresh Behavior

There are two ways to trigger automatic credential refresh:

1. Deferred (default) — Refresh occurs only when credentials are required

2. Eager — Credentials are refreshed as soon as they expire

Set defer_refresh to False to enable eager refresh:

session = RefreshableSession(
    defer_refresh=False,
    assume_role_kwargs=assume_role_kwargs
)

Warning

It is highly recommended to use the default: defer_refresh=True. Eager refresh adds overhead and is only suitable for low-latency systems that cannot tolerate refresh delays.

Parallel Usage and Performance

If you’re working with large datasets and sensitive value detection or redaction, you may wish to use boto3-refresh-session in parallel.

The core session class is thread-safe and compatible with Python’s concurrent.futures or multiprocessing.

To maximize throughput:

• Reuse a single RefreshableSession object across threads or subprocesses

• Use defer_refresh=True to avoid concurrent refreshes at process boundaries

• Mount the session into a poolable or global shared object

Example (using concurrent.futures):

from concurrent.futures import ThreadPoolExecutor
from boto3_refresh_session import RefreshableSession

session = RefreshableSession(assume_role_kwargs={...})

def upload_one(bucket, key, body):
    s3 = session.client("s3")
    s3.put_object(Bucket=bucket, Key=key, Body=body)

with ThreadPoolExecutor() as executor:
    futures = [
        executor.submit(upload_one, "my-bucket", f"file-{i}", b"data")
        for i in range(10)
    ]

for future in futures:
    future.result()

Note

For process-based concurrency (e.g., ProcessPoolExecutor), initialize the session before spawning or forking the pool. This ensures memory is shared efficiently via copy-on-write, and avoids unnecessary duplication of temporary credentials.