A Django library for uploading files directly to AWS S3 or MinIO Storage from HTTP clients.

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for brianhelba from gravatar.com brianhelba Avatar for danlamanna from gravatar.com danlamanna Avatar for Zach.Mullen from gravatar.com Zach.Mullen

Unverified details

These details have not been verified by PyPI
Meta
  • License Expression: Apache-2.0
    SPDX License Expression
  • Maintainer: Kitware, Inc.
  • Tags django , django-widget , kitware-resonant , minio , resonant , s3
  • Requires: Python >=3.10
  • Provides-Extra: minio , pytest , s3
Classifiers
Report project as malware

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[s3]

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 Framework 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:

Pytest

When installed, django-s3-file-field makes several Pytest fixtures automatically available for use.

The s3ff_field_value fixture will return a valid input value for Django ModelForm or Django Rest Framework ModelSerializer subclasses:

from .forms import ResourceForm

def test_resource_form(s3ff_field_value: str) -> None:
    form = ResourceForm(data={'blob': s3ff_field_value})
    assert form.is_valid()

Alternatively, the s3ff_field_value_factory fixture transforms a File object into a valid input value (for Django ModelForm or Django Rest Framework ModelSerializer subclasses), providing more control over the uploaded file:

from django.core.files.storage import default_storage
from rest_framework.test import APIClient

def test_resource_create(s3ff_field_value_factory):
    client = APIClient()
    stored_file = default_storage.open('some_existing_file.txt')
    s3ff_field_value = s3ff_field_value_factory(stored_file)
    resp = client.post('/resource', data={'blob': s3ff_field_value})
    assert resp.status_code == 201

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for brianhelba from gravatar.com brianhelba Avatar for danlamanna from gravatar.com danlamanna Avatar for Zach.Mullen from gravatar.com Zach.Mullen

Unverified details

These details have not been verified by PyPI
Meta
  • License Expression: Apache-2.0
    SPDX License Expression
  • Maintainer: Kitware, Inc.
  • Tags django , django-widget , kitware-resonant , minio , resonant , s3
  • Requires: Python >=3.10
  • Provides-Extra: minio , pytest , s3
Classifiers

Release history Release notifications | RSS feed

This version

1.1.0

1.0.1

1.0.0

0.3.2

0.3.1

0.3.0

0.2.0

0.1.2

0.1.1

0.1.0

0.0.23

0.0.22

0.0.21

0.0.20

0.0.19

0.0.18

0.0.17

0.0.15

0.0.14

0.0.13

0.0.12

0.0.11

0.0.10

0.0.9

0.0.7

0.0.6

0.0.5

0.0.3

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-1.1.0.tar.gz (36.2 kB view details)

Uploaded Source

Built Distribution

django_s3_file_field-1.1.0-py3-none-any.whl (39.5 kB view details)

Uploaded Python 3

File details

Details for the file django_s3_file_field-1.1.0.tar.gz.

File metadata

  • Download URL: django_s3_file_field-1.1.0.tar.gz
  • Upload date:
  • Size: 36.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for django_s3_file_field-1.1.0.tar.gz
Algorithm Hash digest
SHA256 d3f9f9492875c6725433cc2ba21f1d8c24605eec968cbf33f7c14815388901db
MD5 41b11c45f6160fd80ac60a1af3546a8d
BLAKE2b-256 94c897674eefea66c69246a792f9b698d1a3e2a1ed37843045f27763788ef2e9

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_s3_file_field-1.1.0.tar.gz:

Publisher: release.yml on kitware-resonant/django-s3-file-field

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

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

File metadata

File hashes

Hashes for django_s3_file_field-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 655957fee0fd026eacdb03e75a333a615559f2ae32441fa69070e1ce55c0061b
MD5 7f0f4fdcf0e1b60b72dc7e903a31a7d8
BLAKE2b-256 fa041a5d8b6172e0e0016eabfbb7cd725e04082a1891e6f2a9ae110c54dc9fa7

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_s3_file_field-1.1.0-py3-none-any.whl:

Publisher: release.yml on kitware-resonant/django-s3-file-field

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

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