A Django app for storing and processing documents and images
Project description
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.
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
Run pip install django-simple-file-handler.
Add django-simple-file-handler to your installed apps:
INSTALLED_APPS = ( ... 'django_simple_file_handler', )
Run python manage.py migrate.
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_simple_file_handler-0.1.8.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8ce505751e205d829f4ea89ba49426baf29521e9806f54fdaac2ff50d2437aff |
|
MD5 | 52a320bc78c7305002968ac53b518429 |
|
BLAKE2b-256 | ddea4c1f51f098300a494dec2f4b0e9ba3f91550bd15939ce97c0e5fa74c434a |
Hashes for django_simple_file_handler-0.1.8-py37-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e14279541f7e65a38f77812528d8d64cde987b0ccf2da78a876c9c952ef59072 |
|
MD5 | 85232ff822e52199f4cda805de6564b5 |
|
BLAKE2b-256 | de3c1fd2292f5afc87da78355930b3d6c6b317d3abe9f0d562af3f57737b67f4 |