File wrappers

A view return DownloadResponse which itself carries a file wrapper. Here are file wrappers distributed by Django and django-downloadview.

Django’s builtins

Django itself provides some file wrappers [1] you can use within django-downloadview:

• django.core.files.File wraps a file that live on local filesystem, initialized with a path. django-downloadview uses this wrapper in PathDownloadView.

• django.db.models.fields.files.FieldFile wraps a file that is managed in a model. django-downloadview uses this wrapper in ObjectDownloadView.

• django.core.files.base.ContentFile wraps a bytes, string or unicode object. You may use it with VirtualDownloadView.

django-downloadview builtins

django-downloadview implements additional file wrappers:

• StorageFile wraps a file that is managed via a storage (but not necessarily via a model). StorageDownloadView uses this wrapper.

• HTTPFile wraps a file that lives at some (remote) location, initialized with an URL. HTTPDownloadView uses this wrapper.

• VirtualFile wraps a file that lives in memory, i.e. built as a string. This is a convenient wrapper to use in VirtualDownloadView subclasses.

Low-level IO utilities

django-downloadview provides two classes to implement file-like objects whose content is dynamically generated:

• TextIteratorIO for generated text;

• BytesIteratorIO for generated bytes.

These classes may be handy to serve dynamically generated files. See VirtualDownloadView for details.

Tip

Text or bytes? (formerly “unicode or str?”) As django-downloadview is meant to serve files, as opposed to read or parse files, what matters is file contents is preserved. django-downloadview tends to handle files in binary mode and as bytes.

API reference

StorageFile

class django_downloadview.files.StorageFile(storage, name, file=None)

Bases: File

A file in a Django storage.

This class looks like django.db.models.fields.files.FieldFile, but unrelated to model instance.

property file

Required by django.core.files.utils.FileProxy.

open(mode='rb')

Retrieves the specified file from storage and return open() result.

Proxy to self.storage.open(self.name, mode).

save(content)

Saves new content to the file.

Proxy to self.storage.save(self.name).

The content should be a proper File object, ready to be read from the beginning.

property path

Return a local filesystem path which is suitable for open().

Proxy to self.storage.path(self.name).

May raise NotImplementedError if storage doesn’t support file access with Python’s built-in open() function

delete()

Delete the specified file from the storage system.

Proxy to self.storage.delete(self.name).

exists()

Return True if file already exists in the storage system.

If False, then the name is available for a new file.

property size

Return the total size, in bytes, of the file.

Proxy to self.storage.size(self.name).

property url

Return an absolute URL where the file’s contents can be accessed.

Proxy to self.storage.url(self.name).

property accessed_time

Return the last accessed time (as datetime object) of the file.

Proxy to self.storage.accessed_time(self.name).

property created_time

Return the creation time (as datetime object) of the file.

Proxy to self.storage.created_time(self.name).

property modified_time

Return the last modification time (as datetime object) of the file.

Proxy to self.storage.modified_time(self.name).

HTTPFile

class django_downloadview.files.HTTPFile(request_factory=<function get>, url='', name='', **kwargs)

Bases: File

Wrapper for files that live on remote HTTP servers.

Acts as a proxy.

Uses https://pypi.python.org/pypi/requests.

Always sets “stream=True” in requests kwargs.

property request

property file

property size

Return the total size, in bytes, of the file.

Reads response’s “content-length” header.

property content_type

Return content type of the file (from original response).

VirtualFile

class django_downloadview.files.VirtualFile(file=None, name='', url='', size=None)

Bases: File

Wrapper for files that live in memory.

property size

BytesIteratorIO

class django_downloadview.io.BytesIteratorIO(iterator)

Bases: BytesIO

A dynamically generated BytesIO-like object.

Original code by Matt Joiner <anacrolix@gmail.com> from:

• http://stackoverflow.com/questions/12593576/

• https://gist.github.com/anacrolix/3788413

readable()

Returns True if the IO object can be read.

read(n=None)

Return content up to n length.

readline()

Next line from the file, as a bytes object.

Retain newline. A non-negative size argument limits the maximum number of bytes to return (an incomplete line may be returned then). Return an empty bytes object at EOF.

TextIteratorIO

class django_downloadview.io.TextIteratorIO(iterator)

Bases: TextIOBase

A dynamically generated TextIO-like object.

Original code by Matt Joiner <anacrolix@gmail.com> from:

• http://stackoverflow.com/questions/12593576/

• https://gist.github.com/anacrolix/3788413

readable()

Return whether object was opened for reading.

If False, read() will raise OSError.

read(n=None)

Return content up to n length.

readline()

Read until newline or EOF.

Returns an empty string if EOF is hit immediately.

Notes & references

[1]

https://docs.djangoproject.com/en/3.0/ref/files/file/