Part 2 of the updates for the Python 2.7 deprecation (#2742)

* Part 2 of the updates for the Python 2.7 deprecation

.gitignore

@@ -20,9 +20,16 @@ venv
 env2
 env3
 
+# Virtualenv support files and directories
+.python-version
+
 # IntelliJ / PyCharm IDE
 .idea/
 
 # Visual Studio used to edit docs
 docs/source/.vs
 .vscode
+
+# Project-specific
+.doctrees
+source/_build

docs/source/guide/migrationpy3.rst

@@ -1,39 +1,45 @@
 .. _guide_migration_py3:
 
-Migrating from Python 2.7 to Python 3
-=====================================
-Python 2.7 was deprecated by the `Python Software Foundation <https://www.python.org/psf-landing/>`_ back on January 1, 2020 following a multi-year process of phasing it out. Because of this, AWS has deprecated support for Python 2.7, so versions of boto3 and botocore released after the deprecation date will no longer work with Python 2.7.
+Migrating to Python 3
+=====================
 
-Timeline
---------
-Going forward, all projects using the AWS SDK for Python need to transition to using Python 3, with Python 3.6 becoming the minimum by the end of the transition. The deprecation dates for the affected versions of Python are:
+Python 2.7 was deprecated by the `Python Software Foundation <https://www.python.org/psf-landing/>`_
+on January 1, 2020 following a multi-year process of phasing it out. Because of this, AWS has
+deprecated support for Python 2.7, which means that releases of Boto3 issued after the deprecation
+date will no longer work on Python 2.7.
 
-==================     ===================
-Python version         Deprecation date
-==================     ===================
-Python 2.7             July 15, 2021
-Python 3.4 and 3.5     February 1, 2021
-==================     ===================
+This affects both modules that comprise the AWS SDK for Python: Botocore (the underlying low-level
+module) and Boto3 (which implements the API functionality and higher-level features).
 
-As shown in the table, Python 2.7 projects must transition to Python 3.6 by July 15, 2021, while Python 3.4 and 3.5 projects need to be updated to Python 3.6 by February 1, 2021.
+Timeline
+--------
+Going forward, all projects using Boto3 need to transition to Python 3.6 or later. Boto3 and
+Botocore support for Python 3.4 and 3.5 has already ended, and support for Python 2.7 will end effective July 15, 2021.
 
 Updating your project to use Python 3
 -------------------------------------
-Before you begin to update your project and environment, make sure you’ve installed or updated to Python 3.6 or later as described in :ref:`upgrade to Python 3 <quickstart_install_python>`. You can get Python from the `PSF web site <https://www.python.org/downloads>`_ or using your local package manager.
 
-Update boto3 and botocore
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Once you're sure you have Python 3 installed, you can proceed to upgrade boto3 and botocore. You can do this globally, or within your virtual environment if you use one for your project.
+Before you begin to update your project and environment, make sure you’ve installed or updated to
+Python 3.6 or later as described in :ref:`upgrade to Python 3 <quickstart_install_python>`. You can
+get Python from the `PSF web site <https://www.python.org/downloads>`_ or using your local package
+manager.
+
+After you have installed Python 3, you can upgrade the SDK. To do so, you need to update the Boto3
+Python package. You can do this globally or within your virtual environment if you use one for your
+project.
 
-1. Begin by uninstalling the currently installed copies of boto3 and botocore::
+To update the AWS SDK for Python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Uninstall the currently installed copies of Boto3 and Botocore::
 
     $ python -m pip uninstall boto3 botocore
 
-2. Then install the new version of boto3. This will also install botocore, which it requires::
+2. Install the new version of Boto3. This will also install Botocore, which it requires::
 
     $ python3 -m pip install boto3
 
-3. You can optionally verify that the freshly installed copy of Boto3 is using the correct version of Python. One way to do that is to run a snippet of code that uses boto3 and outputs the Python and boto3 versions, such as the following::
+3. (Optional) Verify that the SDK is using the correct version of Python::
 
     $ python3 -c "import boto3, sys; print(f'{sys.version} \nboto3: {boto3.__version__}')"
     3.8.6 (default, Jan  7 2021, 17:11:21)
@@ -42,14 +48,26 @@ Once you're sure you have Python 3 installed, you can proceed to upgrade boto3 a
 
 If you're unable to upgrade to Python 3
 ---------------------------------------
-It may be possible that you're unable to upgrade to Python 3. If you have a large project that's heavily dependent on syntax or features that no longer work as desired in Python 3, for example, you may need to keep using Python 2.7. It's also possible that you need to postpone the Python transition while you finish updates to your code.
 
-Under these circumstances, you should be prepared for the deprecation date in order to not be inconvenienced when the time arrives. If you've kept all software up-to-date, you shouldn't need to do anything. If you're using an existing installation of boto3 on Python 2, you can keep using it even after the deprecation date. That version of boto3, however, will not receive further feature or security updates, so you should consider migrating to Python 3 as soon as possible.
+It may be that you're unable to upgrade to Python 3, for example if you have a large project that's
+heavily dependent on syntax or features that no longer work as desired in Python 3. It's also
+possible that you need to postpone the Python transition while you finish updates to your code.
+
+Under these circumstances, you should plan on pinning your project's install of Boto3 to the last
+release that supports the Python version you use, then not updating Boto3 further. You can then keep
+using an existing installation of Boto3 on Python 2, even after its deprecation date, with the
+understanding that deprecated versions of Boto3 will not receive further feature or security
+updates.
 
 pip-based installations
 ~~~~~~~~~~~~~~~~~~~~~~~
-If you installed boto3 using :command:`pip` 10.0 or later, you'll automatically stop receiving boto3 updates after the last Python 2 compatible version of boto3 is installed. If you're using an older version of :command:`pip`, you need to pin your boto3 install to no later than version 1.17.
+
+If you installed Boto3 using :command:`pip` 10.0 or later, you'll automatically stop receiving Boto3
+updates after the last Python 2 compatible version of the SDK is installed. If you're using an older
+version of :command:`pip`, you need to pin your Boto3 install to no later than version 1.17.
 
 Other installation methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-If install boto3 from source or using any other approach, be sure you download and install a version released prior to the Python 2.7 deprecation date.
+
+If you installed Boto3 and Botocore from source or by any other method, be sure to download and
+install a version released prior to the Python 2.7 deprecation date.

docs/source/guide/quickstart.rst

@@ -2,101 +2,118 @@
 
 Quickstart
 ==========
-Getting started with Boto3 is easy, but requires a few steps.
+
+This guide details the steps needed to install or update the AWS SDK for Python.
+
+The SDK is composed of two key Python packages: Botocore (the library providing the low-level
+functionality shared between the Python SDK and the AWS CLI) and Boto3 (the package implementing the
+Python SDK itself).
+
+.. note::
+
+    Documentation and developers tend to refer to the AWS SDK for Python as "Boto3," and this
+    documentation often does so as well.
 
 Installation
 ------------
-Prior to using Boto3, you need to install it and its dependencies.
+
+To use Boto3, you first need to install it and its dependencies.
 
 .. _quickstart_install_python:
 
 Install or update Python
 ~~~~~~~~~~~~~~~~~~~~~~~~
-Before installing Boto3, ensure that you're using an up-to-date version of
-Python. Unless you have specific reasons to use another version of Python, you
-should be using Python 3.7 or later. Boto3 support for Python 2.7 is
-deprecated and will end effective July 15, 2021. See :ref:`guide_migration_py3`
-for more details, including timeline information and guidance regarding how to
-transition to Python 3 if you haven't done so yet.
 
-For more information on how to get the latest version of Python, please refer
-to the official `Python documentation <https://www.python.org/downloads/>`_. 
+Before installing Boto3, install Python 3.6 or later; support for Python 2.7 and Python 3.5 and
+earlier is deprecated. After the deprecation date listed for each Python version, new releases of
+Boto3 will not include support for that version of Python. For details, including the deprecation
+schedule and how to update your project to use Python 3.6, see :ref:`guide_migration_py3`.
+
+For information about how to get the latest version of Python, see the official `Python
+documentation <https://www.python.org/downloads/>`_. 
 
 Install Boto3
 ~~~~~~~~~~~~~
+
 Install the latest Boto3 release via :command:`pip`::
 
     pip install boto3
 
-You may also install a specific version::
+If your project requires a specific version of Boto3, or has compatibility concerns with
+certain versions, you may provide constraints when installing::
 
+    # Install Boto3 version 1.0 specifically
     pip install boto3==1.0.0
 
+    # Make sure Boto3 is no older than version 1.15.0
+    pip install boto3>=1.15.0
+
+    # Avoid versions of Boto3 newer than version 1.15.3
+    pip install boto3<=1.15.3
+
 .. note::
 
-   The latest development version of Boto3 can always be found on
-   `GitHub <https://github.com/boto/boto3>`_.
+   The latest development version of Boto3 is on `GitHub <https://github.com/boto/boto3>`_.
 
 Configuration
 -------------
-Before you can begin using Boto3, you should set up authentication
-credentials. Credentials for your AWS account can be found in the
-`IAM Console <https://console.aws.amazon.com/iam/home>`_. You can
-create or use an existing user. Go to manage access keys and
-generate a new set of keys.
 
-If you have the `AWS CLI <http://aws.amazon.com/cli/>`_
-installed, then you can use it to configure your credentials file::
+Before using Boto3, you need to set up authentication credentials for your AWS account using either
+the `IAM Console <https://console.aws.amazon.com/iam/home>`_ or the AWS CLI. You can either choose
+an existing user or create a new one.
+
+For instructions about how to create a user using the IAM Console, see `Creating IAM users
+<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console>`_.
+Once the user has been created, see `Managing access keys
+<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey>`_
+to learn how to create and retrieve the keys used to authenticate the user.
+
+If you have the `AWS CLI <http://aws.amazon.com/cli/>`_ installed, then you can use the
+:command:`aws configure` command to configure your credentials file::
 
     aws configure
 
-Alternatively, you can create the credential file yourself. By default,
-its location is at ``~/.aws/credentials``::
+Alternatively, you can create the credentials file yourself. By default, its location is
+``~/.aws/credentials``. At a minimum, the credentials file should specify the access key and secret
+access key. In this example, the key and secret key for the account are specified the ``default`` profile::
 
     [default]
     aws_access_key_id = YOUR_ACCESS_KEY
     aws_secret_access_key = YOUR_SECRET_KEY
 
-You may also want to set a default region. This can be done in the
-configuration file. By default, its location is at ``~/.aws/config``::
+You may also want to add a default region to the AWS configuration file, which is located by default
+at ``~/.aws/config``::
 
     [default]
     region=us-east-1
 
-Alternatively, you can pass a ``region_name`` when creating clients
-and resources.
+Alternatively, you can pass a ``region_name`` when creating clients and resources.
 
-This sets up credentials for the default profile as well as a default
-region to use when creating connections. See
-:ref:`guide_configuration` for in-depth configuration sources and
-options.
+You have now configured credentials for the default profile as well as a default region to use when
+creating connections. See :ref:`guide_configuration` for in-depth configuration sources and options.
 
 Using Boto3
 ------------
-To use Boto3, you must first import it and tell it what service you are
-going to use::
+
+To use Boto3, you must first import it and indicate which service or services you're going to use::
 
     import boto3
 
     # Let's use Amazon S3
     s3 = boto3.resource('s3')
 
-Now that you have an ``s3`` resource, you can make requests and process
-responses from the service. The following uses the ``buckets`` collection
-to print out all bucket names::
+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::
 
     # Print out bucket names
     for bucket in s3.buckets.all():
         print(bucket.name)
 
-It's also easy to upload and download binary data. For example, the
-following uploads a new file to S3. It assumes that the bucket ``my-bucket``
-already exists::
+You can also upload and download binary data. For example, the following uploads a new file to S3,
+assuming that the bucket ``my-bucket`` already exists::
 
     # Upload a new file
     data = open('test.jpg', 'rb')
     s3.Bucket('my-bucket').put_object(Key='test.jpg', Body=data)
 
-:ref:`guide_resources` and :ref:`guide_collections` will be covered in more
-detail in the following sections, so don't worry if you do not completely
-understand the examples.
+:ref:`guide_resources` and :ref:`guide_collections` are covered in more detail in the following
+sections.

docs/source/index.rst

@@ -5,10 +5,15 @@
 
 Boto3 documentation
 ====================
-Boto is the Amazon Web Services (AWS) SDK for Python. It enables Python
-developers to create, configure, and manage AWS services, such as EC2 
-and S3. Boto provides an easy to use, object-oriented API, as well as 
-low-level access to AWS services.
+
+You use the AWS SDK for Python (Boto3) to create, configure, and manage AWS services, such as Amazon
+Elastic Compute Cloud (Amazon EC2) and Amazon Simple Storage Service (Amazon S3). The SDK provides
+an object-oriented API as well as low-level access to AWS services.
+
+.. note::
+
+    Documentation and developers tend to refer to the AWS SDK for Python as "Boto3," and this
+    documentation often does so as well.
 
 Quickstart
 ----------