Skip to main content

A django widget library for securely uploading files directly to S3 (or MinIO).

Project description

django-s3-file-field

PyPI version shields.io PyPI - Python Version PyPI - Django Version

django-s3-file-field is a Django widget library for uploading files directly to S3 (or MinIO) through the browser. django-s3-file-field heavily depends on the django-storages package.

Quickstart

Ensure you've configured your Django installation to use django-storages for S3 access: https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html.

Install the django-s3-file-field package:

pip install django-s3-file-field

Add s3_file_field to your INSTALLED_APPS:

INSTALLED_APPS = [
 ...
 's3_file_field',
]

Add the required settings:

S3FF_UPLOAD_STS_ARN = '' # see STS Role section below (not required for minio)

Add the appropriate routes to urls.py:

urlpatterns = [
    ...
    path('api/s3-upload/', include('s3_file_field.urls')),
]

Usage

from s3_file_field import S3FileField

class Car(db.Model):
    ...
    owners_manual = S3FileField()

Running checks

django-s3-file-field can detect common misconfigurations using Django's built in System check framework. To confirm your configuration is correct, run:

./manage.py check

Advanced Topics

Advanced configuration

Key Default Description
S3FF_UPLOAD_STS_ARN none ...

STS configuration

CORS configuration

This is a minimal function CORS configuration for an S3 bucket to be compatible with django-s3-file-field:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
    <AllowedHeader>*</AllowedHeader>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedOrigin>*</AllowedOrigin>
    <ExposeHeader>Connection</ExposeHeader>
    <ExposeHeader>Content-Length</ExposeHeader>
    <ExposeHeader>Date</ExposeHeader>
    <ExposeHeader>ETag</ExposeHeader>
    <ExposeHeader>Server</ExposeHeader>
    <ExposeHeader>x-amz-delete-marker</ExposeHeader>
    <ExposeHeader>x-amz-version-id</ExposeHeader>
    <MaxAgeSeconds>600</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

Note: These are insecure defaults, the allowed origin and headers should not be a wildcard but instead modified for your specific deployment(s).

MinIO support

MinIO support depends on the django-minio-storage config (see https://django-minio-storage.readthedocs.io/en/latest/usage/), following settings are used

Security considerations

Integrating with forms

If you want to use an S3FileField in a form, some extra client code needs to be injected into your frontend. The form submission only communicates with Django, so the web client has to somehow send that data directly to S3 before the form is submitted. The necessary <script> is available in templates as form.media, which should be embedded into your form template similarly to this:

...
<head>
  {{ form.media }}
</head>
...

The script will detect any S3FileFields being rendered in forms and dynamically rewrite them so that they upload data directly to S3 whenever a file is selected.

Extending

django-s3-file-field sends out two signals when its REST api is called:

s3_file_field_upload_prepare(name: str, object_key: str)
s3_file_field_upload_finalize(name: str, object_key: str, status: string)

API Reference

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-s3-file-field-0.1.1.tar.gz (147.1 kB view details)

Uploaded Source

Built Distribution

django_s3_file_field-0.1.1-py3-none-any.whl (30.8 kB view details)

Uploaded Python 3

File details

Details for the file django-s3-file-field-0.1.1.tar.gz.

File metadata

  • Download URL: django-s3-file-field-0.1.1.tar.gz
  • Upload date:
  • Size: 147.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.9.1

File hashes

Hashes for django-s3-file-field-0.1.1.tar.gz
Algorithm Hash digest
SHA256 a6d22181cba925bb6315d72d55c2b0e886b3e3bd772863269a17402a072acc26
MD5 0dca9ae1983b931129cd1b07193f51c0
BLAKE2b-256 50c5eda5d692e41ca3b445fb679240561a872266b56b9d0ffc32ed8345aaa3ce

See more details on using hashes here.

File details

Details for the file django_s3_file_field-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: django_s3_file_field-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 30.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.9.1

File hashes

Hashes for django_s3_file_field-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 c1dc72c5adb480e921a021aac419c69327a24bcca75a4d8c4ea2ad1180cbe55a
MD5 af3114af0c410fa139503b638303a708
BLAKE2b-256 1fc5ed0f56e3bd79ef68ee872f5afba54007bff2fc6422f8ac08a572c8a1be41

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page