Debian Codegraph @

docs/source/guide/session.rst

raw
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