Metadata-Version: 2.3
Name: boto3-refresh-session
Version: 1.0.27
Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
License: MIT
Keywords: boto3,botocore,aws
Author: Mike Letts
Author-email: lettsmt@gmail.com
Maintainer: Michael Letts
Maintainer-email: lettsmt@gmail.com
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: boto3
Requires-Dist: botocore
Project-URL: Documentation, https://michaelthomasletts.github.io/boto3-refresh-session/index.html
Project-URL: Repository, https://github.com/michaelthomasletts/boto3-refresh-session
Description-Content-Type: text/markdown

# boto3-refresh-session

![PyPI - Version](https://img.shields.io/pypi/v/boto3-refresh-session)
[![Workflow](https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github)](https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push.yml)
![Python Version](https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi)
![GitHub last commit](https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github)
[![PyPI Downloads](https://static.pepy.tech/badge/boto3-refresh-session)](https://pepy.tech/projects/boto3-refresh-session)

<p align="center">
  <img src="https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png" />
</p>

A simple Python package for refreshing the temporary security credentials in a `boto3.session.Session` object automatically.

- [Official Documentation](https://michaelthomasletts.github.io/boto3-refresh-session/index.html)
- [Q&A](https://michaelthomasletts.github.io/boto3-refresh-session/qanda.html)
- [Source Code](https://github.com/michaelthomasletts/boto3-refresh-session)
- [PyPI](https://pypi.org/project/boto3-refresh-session/)
- [Contributing](https://michaelthomasletts.github.io/boto3-refresh-session/contributing.html)
- [Authorization](https://michaelthomasletts.github.io/boto3-refresh-session/authorization.html)

### Testimonials

_"Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive . . . we're using the RefreshableSession class as part of a client cache construct . . . we're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions."_

### Installation

```bash
pip install boto3-refresh-session
```

### Usage

```python
import boto3_refresh_session as brs

# you can pass all of the params associated with boto3.session.Session
profile_name = '<your-profile-name>'
region_name = 'us-east-1'
...

# as well as all of the params associated with STS.Client.assume_role
assume_role_kwargs = {
  'RoleArn': '<your-role-arn>',
  'RoleSessionName': '<your-role-session-name>',
  'DurationSeconds': '<your-selection>',
  ...
}

# as well as all of the params associated with STS.Client, except for 'service_name'
sts_client_kwargs = {
  'region_name': region_name,
  ...
}

# basic initialization of boto3.session.Session
session = brs.RefreshableSession(
  assume_role_kwargs=assume_role_kwargs, # required
  sts_client_kwargs=sts_client_kwargs,
  region_name=region_name,
  profile_name=profile_name,
  ...
)

# now you can create clients, resources, etc. without worrying about expired temporary 
# security credentials
s3 = session.client(service_name='s3')
buckets = s3.list_buckets()
```

### Raison d'être

It is common for data pipelines and workflows that interact with the AWS API via 
`boto3` to run for a long time and, accordingly, for temporary credentials to 
expire. 

Usually, engineers deal with that problem one of two ways: 

- `try except` blocks that catch `ClientError` exceptions
- A similar approach as that used in this project -- that is, using methods available 
  within `botocore` for refreshing temporary credentials automatically. 
  
Speaking personally, variations of the code found herein exists in code bases at 
nearly every company where I have worked. Sometimes, I turned that code into a module; 
other times, I wrote it from scratch. Clearly, that is inefficient.

I decided to finally turn that code into a proper Python package with unit testing, 
automatic documentation, and quality checks; the idea being that, henceforth, depending 
on my employer's open source policy, I may simply import this package instead of 
reproducing the code herein for the Nth time.

If any of that sounds relatable, then `boto3-refresh-session` should help you.
