Quick start

1. Install the package:

   pip install s3chunkuploader

2. Set the Django FILE_UPLOAD_HANDLERS setting:

   FILE_UPLOAD_HANDLERS = (‘s3chunkuploader.file_handler.S3FileUploadHandler’,)

How it works

The File Handler intercepts the file upload multipart request at the door, and as chunks of the file are received from the browser, they are collectd into an internal queue within custom ThreadPoolWorker. When the queue surpasses a configurable size (by default 5MB which is the minimum Part size for S3 multipart upload), it is submitted to the Thread Pool as a Future which will then resolve. Once all the chunks are uploaded and all the futures are resolved the upload is complete. By default 10 threads are used which means a 100MB file upload can be potentially sent as 20 5MB parts to S3.

The FileHandler ultimately returns a ‘dummy’ django-storages S3Boto3StorageFile which is compatible with the storages S3 File Field, but was not actually used to upload a full file. The file is also enhanced with two additional attributes:

original_name: The original file name uploaded file_size: The actual full file size uploaded

It is recommended to bypass csrf checks on the upload file view as the csrf check will read the POST params before the handler is used. A replacement file field S3FileField is provided in fields.py and is satisfied with the S3 object key

By default the S3 key will be generated based on the settings provided. However, it is possible to define a custom function to derive the S3 object key by providing a full dot notated path to the function in the S3_GENERATE_OBJECT_KEY_FUNCTION settings parameter.

Settings

The following settings are expected in your Django application (only 2 are required)

Unit Tests

Unit tests can be executing by running python -m unittest from the projects root

Change Log

• 0.9: The optional setting S3_ENDPOINT_URL was renamed to AWS_S3_ENDPOINT_URL to align with django-storages .

• 0.10: If content_length is not provided MAX_UPLOAD_SIZE cannot evaluate against it.

• 0.11: Prefixed settings keys