Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

S3: Deprecate S3BotoStorage #578

Merged
merged 1 commit into from
Sep 3, 2018
Merged

S3: Deprecate S3BotoStorage #578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 33 additions & 18 deletions docs/backends/amazon-S3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,9 +133,11 @@ Available are numerous settings. It should be especially noted the following:

``AWS_S3_SIGNATURE_VERSION`` (optional - boto3 only)

All AWS regions support v4 of the signing protocol. To use it set this to ``'s3v4'``. It is recommended
to do this for all new projects and required for all regions launched after January 2014. To see
if your region is one of them you can view the `S3 region list`_.
As of ``boto3`` version 1.4.4 the default signature version is ``s3v4``.

Set this to use an alternate version such as ``s3``. Note that only certain regions
support the legacy ``s3`` (also known as ``v2``) version. You can check to see
if your region is one of them in the `S3 region list`_.

.. note::

Expand All @@ -145,8 +147,35 @@ Available are numerous settings. It should be especially noted the following:
.. _AWS Signature Version 4: https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html
.. _S3 region list: http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region

.. _migrating-boto-to-boto3:

Migrating from Boto to Boto3
----------------------------

Migration from the boto-based to boto3-based backend should be straightforward and painless.

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`` to ``AWS_S3_REGION_NAME``
* If ``AWS_S3_CALLING_FORMAT`` is set to ``VHostCallingFormat`` set ``AWS_S3_ADDRESSING_STYLE``
to ``virtual``
* Replace ``AWS_S3_HOST`` and ``AWS_S3_PORT`` with ``AWS_S3_ENDPOINT_URL`` (this is not necessary if
``AWS_S3_HOST`` is only set in order to handle signature versions)
* 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``
* Update ``DEFAULT_FILE_STORAGE`` and/or ``STATICFILES_STORAGE`` to ``storages.backends.boto3.S3Boto3Storage``

Additionally you must install ``boto3`` (``boto`` is no longer required). In order to use
all currently supported features ``1.4.4`` is the minimum required version although we
always recommend the most recent.

Please open an issue on the GitHub repo if any further issues are encountered or steps were omitted.

CloudFront
~~~~~~~~~~
----------

If you're using S3 as a CDN (via CloudFront), you'll probably want this storage
to serve those files using that::
Expand Down Expand Up @@ -250,20 +279,6 @@ Default values allow an object to access a single file::
>>> obj3.default.read()
'default content'

But it shouldn't be deleted, even if there are no more objects using it::

>>> obj3.delete()
>>> obj3 = MyStorage()
>>> obj3.default.read()
'default content'

Verify the fix for #5655, making sure the directory is only determined once::

>>> obj4 = MyStorage()
>>> obj4.random.save('random_file', ContentFile('random content'))
>>> obj4.random
<FieldFile: .../random_file>

Clean up the temporary files::

>>> obj1.normal.delete()
Expand Down
10 changes: 10 additions & 0 deletions storages/backends/s3boto.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,16 @@
raise ImproperlyConfigured("The installed Boto library must be 2.32 or "
"higher.\nSee https://github.com/boto/boto")

warnings.warn(
"The S3BotoStorage backend is deprecated in favor of the S3Boto3Storage backend "
"and will be removed in django-storages 2.0. This backend is mostly in bugfix only "
"mode and has been for quite a while (in much the same way as its underlying "
"library 'boto'). For performance, security and new feature reasons it is _strongly_ "
"recommended that you update to the S3Boto3Storage backend. Please see the migration docs "
"https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html#migrating-boto-to-boto3.",
DeprecationWarning
)


@deconstructible
class S3BotoStorageFile(File):
Expand Down