Session#

Overview#

A session manages state about a particular configuration. By default, a session is created for you when needed. However, it’s possible and recommended that in some scenarios you maintain your own session. Sessions typically store the following:

  • Credentials

  • AWS Region

  • Other configurations related to your profile

Default session#

Boto3 acts as a proxy to the default session. This is created automatically when you create a low-level client or resource client:

import boto3

# Using the default session
sqs = boto3.client('sqs')
s3 = boto3.resource('s3')

Custom session#

You can also manage your own session and create low-level clients or resource clients from it:

import boto3
import boto3.session

# Create your own session
my_session = boto3.session.Session()

# Now we can create low-level clients or resource clients from our custom session
sqs = my_session.client('sqs')
s3 = my_session.resource('s3')

Session configurations#

You can configure each session with specific credentials, AWS Region information, or profiles. The most common configurations you might use are:

  • aws_access_key_id - A specific AWS access key ID.

  • aws_secret_access_key - A specific AWS secret access key.

  • region_name - The AWS Region where you want to create new connections.

  • profile_name - The profile to use when creating your session.

Note

Only set the profile_name parameter when a specific profile is required for your session. To use the default profile, don’t set the profile_name parameter at all. If the profile_name parameter isn’t set and there is no default profile, an empty config dictionary will be used.

For a detailed list of per-session configurations, see the Session core reference.

Multithreading or multiprocessing with sessions#

Similar to Resource objects, Session objects are not thread safe and should not be shared across threads and processes. It’s recommended to create a new Session object for each thread or process:

import boto3
import boto3.session
import threading

class MyTask(threading.Thread):
    def run(self):
        # Here we create a new session per thread
        session = boto3.session.Session()

        # Next, we create a resource client using our thread's session object
        s3 = session.resource('s3')

        # Put your thread-safe code here