| 1 |
.. _guide_session: |
| 2 |
|
| 3 |
Session |
| 4 |
======= |
| 5 |
|
| 6 |
Overview |
| 7 |
--------- |
| 8 |
|
| 9 |
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: |
| 10 |
|
| 11 |
* Credentials |
| 12 |
* AWS Region |
| 13 |
* Other configurations related to your profile |
| 14 |
|
| 15 |
|
| 16 |
Default session |
| 17 |
---------------- |
| 18 |
|
| 19 |
Boto3 acts as a proxy to the default session. This is created automatically when you create a low-level client or resource client:: |
| 20 |
|
| 21 |
import boto3 |
| 22 |
|
| 23 |
# Using the default session |
| 24 |
sqs = boto3.client('sqs') |
| 25 |
s3 = boto3.resource('s3') |
| 26 |
|
| 27 |
|
| 28 |
Custom session |
| 29 |
--------------- |
| 30 |
|
| 31 |
You can also manage your own session and create low-level clients or resource clients from it:: |
| 32 |
|
| 33 |
|
| 34 |
import boto3 |
| 35 |
import boto3.session |
| 36 |
|
| 37 |
# Create your own session |
| 38 |
my_session = boto3.session.Session() |
| 39 |
|
| 40 |
# Now we can create low-level clients or resource clients from our custom session |
| 41 |
sqs = my_session.client('sqs') |
| 42 |
s3 = my_session.resource('s3') |
| 43 |
|
| 44 |
|
| 45 |
Session configurations |
| 46 |
------------------------ |
| 47 |
|
| 48 |
You can configure each session with specific credentials, AWS Region information, or profiles. The most common configurations you might use are: |
| 49 |
|
| 50 |
* ``aws_access_key_id`` - A specific AWS access key ID. |
| 51 |
* ``aws_secret_access_key`` - A specific AWS secret access key. |
| 52 |
* ``region_name`` - The AWS Region where you want to create new connections. |
| 53 |
* ``profile_name`` - The profile to use when creating your session. |
| 54 |
|
| 55 |
|
| 56 |
.. note:: |
| 57 |
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. |
| 58 |
|
| 59 |
For a detailed list of per-session configurations, see the `Session core reference <https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html>`_. |
| 60 |
|
| 61 |
|
| 62 |
Multithreading or multiprocessing with sessions |
| 63 |
----------------------------------------------- |
| 64 |
|
| 65 |
Similar to ``Resource`` objects, ``Session`` objects are not thread safe |
| 66 |
and should not be shared across threads and processes. It's recommended |
| 67 |
to create a new ``Session`` object for each thread or process:: |
| 68 |
|
| 69 |
import boto3 |
| 70 |
import boto3.session |
| 71 |
import threading |
| 72 |
|
| 73 |
class MyTask(threading.Thread): |
| 74 |
def run(self): |
| 75 |
# Here we create a new session per thread |
| 76 |
session = boto3.session.Session() |
| 77 |
|
| 78 |
# Next, we create a resource client using our thread's session object |
| 79 |
s3 = session.resource('s3') |
| 80 |
|
| 81 |
# Put your thread-safe code here |