django-simple-file-handler 0.1.6

A Django app for storing and processing documents and images

The django-simple-file-handler package is an app for uploading and managing documents and images. With optional packages installed, it can process images and generate PDFs from HTML files. It only has been tested with Django 1.11 and Python 3.6.

If python-magic is installed, django-simple-file-handler will use it to check uploaded file MIME types. Otherwise, it will use Python’s built-in library. This package only has been tested with python-magic 0.4.

Please note that “private” files and PDFs would be more accurately described as “hidden.” The app generates a proxy URL that will load the file for a logged-in user and stores the file with a name consisting of many random characters. Still, it is possible to load these files without logging in if the file name is known.

Processed image generation requires that Pillow be installed. This package only has been tested with Pillow 5.0.

PDF generation requires that either WeasyPrint or xhtml2pdf be installed. This package only has been tested with WeasyPrint 0.28 and xhtml2pdf 0.2.1. Please refer to those projects’ documentation for HTML template-formatting specifics.

Quick start

1. Run pip install django-simple-file-handler.

2. Add django-simple-file-handler to your installed apps:

   INSTALLED_APPS = (
       ...
       'django_simple_file_handler',
   )

3. Run python manage.py migrate.

4. Include the django-simple-file-handler URLconf in your project urls.py like this (this step is only required if you wish to use private files or PDFs):

   urlpatterns = [
       ...
       url(
           r'^private-file-pseudo-directory-path/',
           include('django_simple_file_handler.urls')
       ),
   ]

Basics

Public and private document objects, as well as unprocessed image objects, can be created and managed via the admin site. Other types are read-only in the admin site.

All types can be created and accessed by subclassing or creating a foreign key in your own apps.

Temporary documents and temporary PDFs are intended to be used when two or more objects might need to have the same title. These add a string of random characters to the ends of file names to prevent overwriting files.

Classes

• PublicDocument — Includes uploaded document file

• PrivateDocument — Includes uploaded document file with a proxy URL requiring login

• TemporaryDocument — Includes uploaded document file with a modified file name allowing title duplication

• UnprocessedImage — Includes uploaded image file

• ProcessedImage — Includes uploaded image file and processed image file

• PublicPDF — Includes generated PDF file

• PrivatePDF — Includes generated PDF file with a proxy URL requiring login

• TemporaryPDF — Includes generated PDF file with a modified file name allowing title duplication

Attributes

• created — DateTimeField with automatically generated value

• updated — DateTimeField with automatically generated value

• title — CharField with max_length of 245 characters (not available for ProcessedImage)

• extra_text — TextField (optional)

• saved_file — FileField for the uploaded file

• processed_file — FileField for processed image (ProcessedImage only)

• output_width — PositiveIntegerField (ProcessedImage only)

• output_height — PositiveIntegerField (ProcessedImage only)

• subdirectory_path — String containing the path used by saved_file

• image_path — String containing the path used by processed_file (ProcessedImage only)

• output_mode — String used by Pillow (ProcessedImage only)

• content_type — String used by Pillow (ProcessedImage only)

• file_format — String used by Pillow (ProcessedImage only)

• file_extension — String used by Pillow (ProcessedImage only)

Methods

• file_url — Returns URL of the uploaded file as a string

• file_link — Returns an HTML link to the URL of the uploaded file as a string

• proxy_url — Returns proxy URL for the uploaded file as a string (PrivateDocument and PrivatePDF only)

• proxy_link — Returns an HTML link to the proxy URL for the uploaded file as a string (PrivateDocument and PrivatePDF only)

• image_url — Returns URL of the processed image file as a string (ProcessedImage only)

• image_link — Returns an HTML link to the URL of the processed image file as a string (ProcessedImage only)

Generating PDFs

The example code below uses PublicPDF, but PrivatePDF and TemporaryPDF work the same way.

generated_pdf = PublicPDF(
    title = 'title of the generated PDF document',
    extra_text = 'any additional text needed with the object',
    template_location = 'path/to/your/html/template.html',
    template_data = {
        'value_one': value_to_be_inserted_in_template,
        'value_two': value_to_be_inserted_in_template,
        'value_three': value_to_be_inserted_in_template,
    },
)
generated_pdf.save()

Database object attributes can then be changed without rewriting the PDF file. The file is only written when the template_data dictionary is given and the object resaved.

File types

Supported document formats include PDF, ZIP, Word, Excel and PowerPoint. Supported image formats include PNG, JPEG, GIF and TIFF (processed images only).

To support different file types, subclass the relevant model and initialize your model with your own dictionary of allowed attributes.

from django_simple_file_handler.models import PublicDocument

...
class MyPublicDocument(PublicDocument):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._meta.get_field('saved_file').validators = [
            CheckExtMIME(allowed_attributes=MY_DICTIONARY),
        ]

Note that this validator will not appear in database migrations, which is intentional.

The dictionary’s format can optionally include arguments for file extensions, MIME types and verbose names for file formats (these will appear in error messages if given). Here is an example:

MY_DICTIONARY = {
    'allowed_extensions' : [
        'abc',
        'def',
        'ghi',
    ],
    'allowed_mimetypes' : [
        'application/example1',
        'application/example2',
        'image/example3',
    ],
    'allowed_verbose' : [
        'Format1',
        'Format2',
        'Format3',
    ],
}

File locations

If you wish to change the locations where files are stored, subclass the relevant model and change the relevant attributes as in this example:

from django_simple_file_handler import ProcessedImage

...
class MyProcessedImage(ProcessedImage):
    subdirectory_path = 'path/to/save/location/'
    image_path = 'path/to/save/location/'

Note that the image_path attribute only applies to ProcessedImage.

Image attributes

By default, images are processed into PNG format with RGB data. To use something else, subclass the ProcessedImage model and change the attributes as in this example:

from django_simple_file_handler.models import ProcessedImage

...
class MyProcessedImage(ProcessedImage):
    output_mode = 'P'
    content_type = 'image/gif'
    file_format = 'GIF'
    file_extension = 'gif'

Advanced use

The django-simple-file-handler models make use of modular, reusable mixins and functions that can, of course, be imported for use with your own code.