<commit_before>django-s3-storage
=================

**django-s3-storage** provides a Django Amazon S3 file storage.


Features
--------

- Django file storage for Amazon S3.
- Django static file storage for Amazon S3.
- Works in Python 3!


Installation
------------

1. Install using ``pip install django-s3-storage``.
2. Add ``'django_s3_storage'`` to your ``INSTALLED_APPS`` setting.
3. Set your ``DEFAULT_FILE_STORAGE`` setting to ``"django_s3_storage.storage.S3Storage"``.
4. Set your ``STATICFILES_STORAGE`` setting to ``"django_s3_storage.storage.StaticS3Storage"`` or ``"django_s3_storage.storage.ManifestStaticS3Storage"``.
5. Configure your Amazon S3 settings (see Available settings, below).


Authentication settings
-----------------------

Use the following settings to authenticate with Amazon AWS.

.. code:: python

    # The AWS region to connect to.
    AWS_REGION = "us-east-1"

    # The AWS access key to use.
    AWS_ACCESS_KEY_ID = ""

    # The AWS secret access key to use.
    AWS_SECRET_ACCESS_KEY = ""

    # The optional AWS session token to use.
    AWS_SESSION_TOKEN = ""


File storage settings
---------------------

Use the following settings to configure the S3 file storage. You must provide at least ``AWS_S3_BUCKET_NAME``.

.. code:: python

    # The name of the bucket to store files in.
    AWS_S3_BUCKET_NAME = ""

    # How to construct S3 URLs ("auto", "path", "virtual").
    AWS_S3_ADDRESSING_STYLE = "auto"

    # The full URL to the S3 endpoint. Leave blank to use the default region URL.
    AWS_S3_ENDPOINT_URL = ""

    # A prefix to be applied to every stored file. This will be joined to every filename using the "/" separator.
    AWS_S3_KEY_PREFIX = ""

    # Whether to enable authentication for stored files. If True, then generated URLs will include an authentication
    # token valid for `AWS_S3_MAX_AGE_SECONDS`. If False, then generated URLs will not include an authentication token,
    # and their permissions will be set to "public-read".
    AWS_S3_BUCKET_AUTH = True

    # How long generated URLs are valid for. This affects the expiry of authentication tokens if `AWS_S3_BUCKET_AUTH`
    # is True. It also affects the "Cache-Control" header of the files.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_MAX_AGE_SECONDS = 60 * 60  # 1 hours.

    # A URL prefix to be used for generated URLs. This is useful if your bucket is served through a CDN. This setting
    # cannot be used with `AWS_S3_BUCKET_AUTH`.
    AWS_S3_PUBLIC_URL = ""

    # If True, then files will be stored with reduced redundancy. Check the S3 documentation and make sure you
    # understand the consequences before enabling.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_REDUCED_REDUNDANCY = False

    # The Content-Disposition header used when the file is downloaded. This can be a string, or a function taking a
    # single `name` argument.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_CONTENT_DISPOSITION = ""

    # The Content-Language header used when the file is downloaded. This can be a string, or a function taking a
    # single `name` argument.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_CONTENT_LANGUAGE = ""

    # A mapping of custom metadata for each file. Each value can be a string, or a function taking a
    # single `name` argument.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_METADATA = {}

    # If True, then files will be stored using server-side encryption.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_ENCRYPT_KEY = False

    # If True, then text files will be stored using gzip content encoding. Files will only be gzipped if their
    # compressed size is smaller than their uncompressed size.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_GZIP = True

    # The signature version to use for S3 requests.
    AWS_S3_SIGNATURE_VERSION = None

    # If True, then files with the same name will overwrite each other. By default it's set to False to have
    # extra characters appended.
    AWS_S3_FILE_OVERWRITE =  False

**Important:** Several of these settings (noted above) will not affect existing files. To sync the new settings to
existing files, run ``./manage.py s3_sync_meta django.core.files.storage.default_storage``.


Staticfiles storage settings
----------------------------

All of the file storage settings are available for the staticfiles storage, suffixed with ``_STATIC``.
You must provide at least ``AWS_S3_BUCKET_NAME_STATIC``. Remember to run `./manage.py collectstatic` after changing your
staticfiles storage backend.

The following staticfiles storage settings have different default values to their file storage counterparts.

.. code:: python

    AWS_S3_BUCKET_AUTH_STATIC = False


The following additional staticfiles storage settings also exist:

.. code:: python
<commit_msg>Updating readme to reference collectstatic.<commit_after>django-s3-storage
=================

**django-s3-storage** provides a Django Amazon S3 file storage.


Features
--------

- Django file storage for Amazon S3.
- Django static file storage for Amazon S3.
- Works in Python 3!


Installation
------------

1. Install using ``pip install django-s3-storage``.
2. Add ``'django_s3_storage'`` to your ``INSTALLED_APPS`` setting.
3. Set your ``DEFAULT_FILE_STORAGE`` setting to ``"django_s3_storage.storage.S3Storage"``.
4. Set your ``STATICFILES_STORAGE`` setting to ``"django_s3_storage.storage.StaticS3Storage"`` or ``"django_s3_storage.storage.ManifestStaticS3Storage"``.
5. Configure your Amazon S3 settings (see Available settings, below).


Authentication settings
-----------------------

Use the following settings to authenticate with Amazon AWS.

.. code:: python

    # The AWS region to connect to.
    AWS_REGION = "us-east-1"

    # The AWS access key to use.
    AWS_ACCESS_KEY_ID = ""

    # The AWS secret access key to use.
    AWS_SECRET_ACCESS_KEY = ""

    # The optional AWS session token to use.
    AWS_SESSION_TOKEN = ""


File storage settings
---------------------

Use the following settings to configure the S3 file storage. You must provide at least ``AWS_S3_BUCKET_NAME``.

.. code:: python

    # The name of the bucket to store files in.
    AWS_S3_BUCKET_NAME = ""

    # How to construct S3 URLs ("auto", "path", "virtual").
    AWS_S3_ADDRESSING_STYLE = "auto"

    # The full URL to the S3 endpoint. Leave blank to use the default region URL.
    AWS_S3_ENDPOINT_URL = ""

    # A prefix to be applied to every stored file. This will be joined to every filename using the "/" separator.
    AWS_S3_KEY_PREFIX = ""

    # Whether to enable authentication for stored files. If True, then generated URLs will include an authentication
    # token valid for `AWS_S3_MAX_AGE_SECONDS`. If False, then generated URLs will not include an authentication token,
    # and their permissions will be set to "public-read".
    AWS_S3_BUCKET_AUTH = True

    # How long generated URLs are valid for. This affects the expiry of authentication tokens if `AWS_S3_BUCKET_AUTH`
    # is True. It also affects the "Cache-Control" header of the files.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_MAX_AGE_SECONDS = 60 * 60  # 1 hours.

    # A URL prefix to be used for generated URLs. This is useful if your bucket is served through a CDN. This setting
    # cannot be used with `AWS_S3_BUCKET_AUTH`.
    AWS_S3_PUBLIC_URL = ""

    # If True, then files will be stored with reduced redundancy. Check the S3 documentation and make sure you
    # understand the consequences before enabling.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_REDUCED_REDUNDANCY = False

    # The Content-Disposition header used when the file is downloaded. This can be a string, or a function taking a
    # single `name` argument.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_CONTENT_DISPOSITION = ""

    # The Content-Language header used when the file is downloaded. This can be a string, or a function taking a
    # single `name` argument.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_CONTENT_LANGUAGE = ""

    # A mapping of custom metadata for each file. Each value can be a string, or a function taking a
    # single `name` argument.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_METADATA = {}

    # If True, then files will be stored using server-side encryption.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_ENCRYPT_KEY = False

    # If True, then text files will be stored using gzip content encoding. Files will only be gzipped if their
    # compressed size is smaller than their uncompressed size.
    # Important: Changing this setting will not affect existing files.
    AWS_S3_GZIP = True

    # The signature version to use for S3 requests.
    AWS_S3_SIGNATURE_VERSION = None

    # If True, then files with the same name will overwrite each other. By default it's set to False to have
    # extra characters appended.
    AWS_S3_FILE_OVERWRITE =  False

**Important:** Several of these settings (noted above) will not affect existing files. To sync the new settings to
existing files, run ``./manage.py s3_sync_meta django.core.files.storage.default_storage``.


Staticfiles storage settings
----------------------------

All of the file storage settings are available for the staticfiles storage, suffixed with ``_STATIC``. You must provide
at least ``AWS_S3_BUCKET_NAME_STATIC``. Remember to run ``./manage.py collectstatic`` after changing your staticfiles
storage backend.

The following staticfiles storage settings have different default values to their file storage counterparts.

.. code:: python

    AWS_S3_BUCKET_AUTH_STATIC = False


The following additional staticfiles storage settings also exist:

.. code:: python

{'fraction_non_alphanumeric': 0.08496538081107814, 'fraction_numerical': 0.010484668644906034, 'mean_word_length': 3.358189655172414, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '850365', 'n_tokens_mistral': 2898, 'n_tokens_neox': 2797, 'n_words': 1224}