django-upthor 0.9.1

django-upthor provides a django application for simple ajax file uploads.

django-upthor

django-upthor provides a django application for simple ajax file uploads. We use https://github.com/blueimp/jQuery-File-Upload for the upload functionality.

Warning: This isn’t close to being a complete app, but it’s getting there.

Usage

Step 1. Install

• pip install django-upthor

Now you have two options:

• If you want to encrypt FQ values, install pycrypto. pip install pycrypto==2.6.1

• Or you can, disable FQ encryption by adding THOR_DISABLE_FQ_ENCRYPT = True to your settings file.

Step 2. (Django 1.6+)

Add ‘upthor’ to your installed apps in settings.py:

INSTALLED_APPS = (
    ...
    "upthor",
)

Then:

python manage.py migrate

Step 3. Use it in your app’s models.

import os
import uuid

from django.db import models
from upthor import fields as thor_fields


def random_upload_path(instance, filename):
    # Split the uuid into two parts so that we won't run into subdirectory count limits. First part has 3 hex chars,
    #  thus 4k possible values.
    uuid_hex = uuid.uuid4().hex
    return os.path.join(uuid_hex[:3], uuid_hex[3:], filename)


def post_example_file_link(real_instance, temporary_instance, raw_file):
    """
        A callback called after linking the temporary file with the model.

        **Warning**: Don't call instances save method from here, cause it will cause an recursion error.

        @:param real_instance An instance of the model the file is attached to
        @:param temporary_instance An instance of TemporaryFileWrapper that the form links to.
        @:param raw_file The raw file that is being uploaded.

        @:return bool If True, the uploaded temporary file is removed once the linking is complete.
    """
    return True


def get_file_image(file_path):
    """ An optional function that returns the display image html for files after uploading is complete"""

    return '<i class="fa fa-file"></i>'


class ExampleModelWithFile(models.Model):
    name = models.CharField(max_length=50)
    file = thor_fields.ThorFileField(upload_to=random_upload_path,
                                   allowed_types=['*'], widget=thor_fields.ThorSingleUploadWidget,
                                   post_link=post_product_file_link,
                                   get_upload_image=get_file_image)

Step 4. Make sure to include form media.

Make sure you include the media files for the form in your templates:

E.g. Add the following codes where form is the context object of your modelform that uses the uploader fields.

{{ form.media.css }}

{{ form.media.js }}

Step 5. Add the upload url to your project urls.

url(r'', include('upthor.urls')),

Step 6. Optional stuff

Temporary file cleanup

If you want to clean up temporary files automatically, you’ll need to install django-cron and add upthor.cron.CleanTemporaryFiles to your cron classes in settings.

Alternatively to clean up manually you can use the management command clean_temporary_files.

Custom upload widget template

You can override ThorSingleUploadWidget.render_template to return your own widget template instead of the hardcoded one defined in widgets.py. Although the structure (including most classes) has to remain the same, there are a few data attributes on .file-upload that you can use to customize behavior:

Data Attribute Name	Type	Description
upload-url	string	Required: URL to POST temporary files to, defaults to reverse of thor-file-upload.
max-size	number	Required: Maximum allowed file size in bytes, defaults to THOR_MAX_FILE_SIZE.
size-error	string	Required: Text to display if the file doesn’t meet the size requirements, defaults to "Uploaded file too large".
use-background	boolean	Whether or not to use background-image instead of img elements, defaults to false.

Backends

Currently it only supports local file backend, but we plan to add other backends when we reach a stable state.

Settings

The following settings are customizable using your django project settings file.

THOR_UPLOAD_TO

Path where the upload files will be stored. Defaults to “temp-files”.

THOR_EXPIRE_TIME

How long to keep temporary files in the database and on disk. Defaults to “60*60*24”, e.g. 24 hours.

THOR_LINKED_EXPIRE_TIME

How long to keep linked temporary files in the database and on disk. Defaults to “60*60*6”, e.g. 6 hours.

THOR_MAX_FILE_SIZE

The max file size of uploaded files. Defaults to “2*1024*1024”, e.g. 2 MB.

THOR_DISABLE_FQ_ENCRYPT

Disable the FQ Encryption, if this is False you need to install pycrypto since that is used for encryption. Defaults to “False”.

THOR_ENABLE_ADMIN

Should TemporaryFileWrapper model be shown in the admin interface. Defaults to “True”.