Debian Codegraph @

docs/source/guide/quickstart.rst

raw
1 .. _guide_quickstart:
2
3 Quickstart
4 ==========
5
6 This guide details the steps needed to install or update the AWS SDK for Python.
7
8 The SDK is composed of two key Python packages: Botocore (the library providing the low-level
9 functionality shared between the Python SDK and the AWS CLI) and Boto3 (the package implementing the
10 Python SDK itself).
11
12 .. note::
13
14 Documentation and developers tend to refer to the AWS SDK for Python as "Boto3," and this
15 documentation often does so as well.
16
17 Installation
18 ------------
19
20 To use Boto3, you first need to install it and its dependencies.
21
22 .. _quickstart_install_python:
23
24 Install or update Python
25 ~~~~~~~~~~~~~~~~~~~~~~~~
26
27 Before installing Boto3, ensure you're using Python 3.10 or later.
28 For details on how to update your project from older versions of Python,
29 see :ref:`guide_migration_py3`.
30
31 For information about how to get the latest version of Python, see the official `Python
32 documentation <https://www.python.org/downloads/>`_.
33
34 Setup a virtual environment
35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
36
37 Once you have a supported version of Python installed, you should set up
38 your workspace by creating a virtual environment and activate it::
39
40 $ python -m venv .venv
41 ...
42 $ source .venv/bin/activate
43
44 This provides an isolated space for your installation that will avoid unexpected
45 interactions with packages installed at the system level. Skipping this step may
46 result in unexpected dependency conflicts or failures with other tools installed
47 on your system.
48
49 Install Boto3
50 ~~~~~~~~~~~~~
51
52 Install the latest Boto3 release via :command:`pip`::
53
54 pip install boto3
55
56 If your project requires a specific version of Boto3, or has compatibility concerns with
57 certain versions, you may provide constraints when installing::
58
59 # Install Boto3 version 1.0 specifically
60 pip install boto3==1.0.0
61
62 # Make sure Boto3 is no older than version 1.15.0
63 pip install boto3>=1.15.0
64
65 # Avoid versions of Boto3 newer than version 1.15.3
66 pip install boto3<=1.15.3
67
68 .. note::
69
70 The latest development version of Boto3 is on `GitHub <https://github.com/boto/boto3>`_.
71
72 Using the AWS Common Runtime (CRT)
73 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
74
75 In addition to the default install of Boto3, you can choose to include the new `AWS Common Runtime <https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html>`_
76 (CRT). The AWS CRT is a collection of modular packages that serve as a new foundation for AWS SDKs.
77 Each library provides better performance and minimal footprint for the functional area it
78 implements. Using the CRT, SDKs can share the same base code when possible, improving consistency
79 and throughput optimizations across AWS SDKs.
80
81 When the AWS CRT is included, Boto3 uses it to incorporate features not otherwise
82 available in the AWS SDK for Python.
83
84 You'll find it used in features like:
85
86 - `Amazon S3 Multi-Region Access Points <https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiRegionAccessPoints.html>`_
87 - `Amazon S3 Object Integrity <https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html>`_
88 - Amazon EventBridge Global Endpoints
89
90 However, Boto3 doesn't use the AWS CRT by default but you can opt into using it by specifying the
91 :code:`crt` `extra feature <https://www.python.org/dev/peps/pep-0508/#extras>`_ when installing Boto3::
92
93 pip install boto3[crt]
94
95 To revert to the non-CRT version of Boto3, use this command::
96
97 pip uninstall awscrt
98
99 If you need to re-enable CRT, reinstall :code:`boto3[crt]` to ensure you get a compatible version of :code:`awscrt`::
100
101 pip install boto3[crt]
102
103 Configuration
104 -------------
105
106 Before using Boto3, you need to set up authentication credentials for your AWS account using either
107 the `IAM Console <https://console.aws.amazon.com/iam/home>`_ or the AWS CLI. You can either choose
108 an existing user or create a new one.
109
110 For instructions about how to create a user using the IAM Console, see `Creating IAM users
111 <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console>`_.
112 Once the user has been created, see `Managing access keys
113 <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey>`_
114 to learn how to create and retrieve the keys used to authenticate the user.
115
116 If you have the `AWS CLI <http://aws.amazon.com/cli/>`_ installed, then you can use the
117 :command:`aws configure` command to configure your credentials file::
118
119 aws configure
120
121 Alternatively, you can create the credentials file yourself. By default, its location is
122 ``~/.aws/credentials``. At a minimum, the credentials file should specify the access key and secret
123 access key. In this example, the key and secret key for the account are specified in the ``default`` profile::
124
125 [default]
126 aws_access_key_id = YOUR_ACCESS_KEY
127 aws_secret_access_key = YOUR_SECRET_KEY
128
129 You may also want to add a default region to the AWS configuration file, which is located by default
130 at ``~/.aws/config``::
131
132 [default]
133 region=us-east-1
134
135 Alternatively, you can pass a ``region_name`` when creating clients and resources.
136
137 You have now configured credentials for the default profile as well as a default region to use when
138 creating connections. See :ref:`guide_configuration` for in-depth configuration sources and options.
139
140 Using Boto3
141 ------------
142
143 To use Boto3, you must first import it and indicate which service or services you're going to use::
144
145 import boto3
146
147 # Let's use Amazon S3
148 s3 = boto3.resource('s3')
149
150 Now that you have an ``s3`` resource, you can make send requests to the service. The following code uses the ``buckets`` collection to print out all bucket names::
151
152 # Print out bucket names
153 for bucket in s3.buckets.all():
154 print(bucket.name)
155
156 You can also upload and download binary data. For example, the following
157 uploads a new file to S3, assuming that the bucket ``amzn-s3-demo-bucket``
158 already exists::
159
160 # Upload a new file
161 with open('test.jpg', 'rb') as data:
162 s3.Bucket('amzn-s3-demo-bucket').put_object(Key='test.jpg', Body=data)
163
164 :ref:`guide_resources` and :ref:`guide_collections` are covered in more detail in the following
165 sections.