Skip to main content

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

Project description

django-s3-file-field

PyPI

django-s3-file-field is a Django library for uploading files directly to AWS S3 or MinIO Storage from HTTP clients (browsers, CLIs, etc.).

Benefits

django-s3-file-field makes long-running file transfers (with large files or slow connections) more efficient, as the file content is no longer proxied through the Django server. This also frees Django from needing to maintain active HTTP requests during file upload, decreasing server load and facilitating deployment to environments like Heroku, which have short, strict request timeouts.

Scope

The principal API of django-s3-file-field is the S3FileField, which is a subclass of Django's FileField. django-s3-file-field does not affect any operations other than uploading from external HTTP clients; for all other file operations (downloading, uploading from the Python API, etc.), refer to Django's file management documentation.

django-s3-file-field supports both the creation and modification (by overwrite) of S3FileField-containing Model instances. It supports server-rendered views, via the Forms API, with Form Field and Widget subclasses which will automatically be used for ModelForm instances. It also supports RESTful APIs, via Django Rest Framework's Serializer API, with a Serializer Field subclass which will automatically be used for ModelSerializer instances.

Installation

django-s3-file-field must be used with a compatible Django Storage, which are:

After the appropriate Storage is installed and configured, install django-s3-file-field, using the corresponding extra:

pip install django-s3-file-field[boto3]

or

pip install django-s3-file-field[minio]

Enable django-s3-file-field as an installed Django app:

# settings.py
INSTALLED_APPS = [
    ...,
    's3_file_field',
]

Add django-s3-file-field's URLconf to the root URLconf; the path prefix ('api/s3-upload/') can be changed arbitrarily as desired:

# urls.py
from django.urls import include, path

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

Usage

For all usage, define an S3FileField on a Django Model, instead of a FileField:

from django.db import models
from s3_file_field import S3FileField

class Resource(models.Model):
    blob = S3FileField()

Django Forms

When defining a Django ModelForm, the appropriate Form Field will be automatically used:

from django.forms import ModelForm
from .models import Resource

class ResourceForm(ModelForm):
    class Meta:
        model = Resource
        fields = ['blob']

Forms using django-s3-file-field include additional assets, which it's essential to render along with the Form. Typically, this can be done in any Form-containing Template as:

<head>
  {# Assuming the Form is availible in context as "form" #}
  {{ form.media }}
</head>

Django Rest Framework

When defining a Django Rest Frameowrk ModelSerializer, the appropriate Serializer Field will be automatically used:

from rest_framework import serializers
from .models import Resource

class ResourceSerializer(serializers.ModelSerializer):
    class Meta:
        model = Resource
        fields = ['blob']

Clients interacting with these RESTful APIs will need to use a corresponding django-s3-file-field client library. Client libraries (and associated documentation) are available for:

Project details


Download files

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

Files for django-s3-file-field, version 0.1.2
Filename, size File type Python version Upload date Hashes
Filename, size django_s3_file_field-0.1.2-py3-none-any.whl (32.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-s3-file-field-0.1.2.tar.gz (151.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page