From f38067f164130175ec2d0ffc5efda1754da7e1c6 Mon Sep 17 00:00:00 2001 From: Josh Schneier Date: Thu, 6 Sep 2018 03:01:08 -0400 Subject: [PATCH] Update boto migration instruction and mention deprecation in docs --- docs/backends/amazon-S3.rst | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/backends/amazon-S3.rst b/docs/backends/amazon-S3.rst index 2740d574d..4aa0faca7 100644 --- a/docs/backends/amazon-S3.rst +++ b/docs/backends/amazon-S3.rst @@ -4,22 +4,16 @@ Amazon S3 Usage ***** -There are two backends for interacting with Amazon's S3, one based -on boto3 and an older one based on boto. It is highly recommended that all -new projects (at least) use the boto3 backend since it has many bug fixes -and performance improvements over boto and is the future; boto is lightly -maintained if at all. The boto3 based backend will continue to be maintained -for the foreseeable future. +There is only one supported backend for interacting with Amazon's S3, +``S3Boto3Storage``, based on the boto3 library. The backend based on the boto +library has now been officially deprecated and is due to be removed shortly. + +All current users of the legacy ``S3BotoStorage`` backend are encouraged to migrate +to the ``S3Boto3Storage`` backend by following the :ref:`migration instructions `. For historical completeness an extreme legacy backend was removed in version 1.2 -If using the boto backend on a new project (not recommended) it is recommended -that you configure it to also use `AWS Signature Version 4`_. This can be done -by adding ``S3_USE_SIGV4 = True`` to your settings and setting the ``AWS_S3_HOST`` -configuration option. For regions created after January 2014 this is your only -option if you insist on using the boto backend. - Settings -------- @@ -176,10 +170,10 @@ The following adjustments to settings are required: - Rename ``AWS_HEADERS`` to ``AWS_S3_OBJECT_PARAMETERS`` and change the format of the key names as in the following example: ``cache-control`` becomes ``CacheControl``. -- Rename ``AWS_ORIGIN`` and ``AWS_S3_HOST`` to ``AWS_S3_REGION_NAME`` -- If ``AWS_S3_CALLING_FORMAT`` is set to ``VHostCallingFormat`` set ``AWS_S3_ADDRESSING_STYLE`` - to ``virtual`` +- Raname ``AWS_ORIGIN`` to ``AWS_S3_REGION_NAME`` +- If ``AWS_S3_CALLING_FORMAT`` is set to ``VHostCallingFormat`` set ``AWS_S3_ADDRESSING_STYLE`` to ``virtual`` - Replace the combination of ``AWS_S3_HOST`` and ``AWS_S3_PORT`` with ``AWS_S3_ENDPOINT_URL`` +- Extract the region name from ``AWS_S3_HOST`` and set ``AWS_S3_REGION_NAME`` - Replace ``AWS_S3_PROXY_HOST`` and ``AWS_S3_PROXY_PORTY`` with ``AWS_S3_PROXIES`` - If using signature version ``s3v4`` you can remove ``S3_USE_SIGV4`` - If you persist urls and rely on the output to use the signature version of ``s3`` set ``AWS_S3_SIGNATURE_VERSION`` to ``s3``