File storage API

Getting the current storage class

Django provides two convenient ways to access the current storage class:

class DefaultStorage[source]

DefaultStorage provides lazy access to the current default storage system as defined by DEFAULT_FILE_STORAGE. DefaultStorage uses get_storage_class() internally.

get_storage_class(import_path=None)[source]

Returns a class or module which implements the storage API.

When called without the import_path parameter get_storage_class will return the current default storage system as defined by DEFAULT_FILE_STORAGE. If import_path is provided, get_storage_class will attempt to import the class or module from the given path and will return it if successful. An exception will be raised if the import is unsuccessful.

The FileSystemStorage Class

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)[source]

The FileSystemStorage class implements basic file storage on a local filesystem. It inherits from Storage and provides implementations for all the public methods thereof.

location

Absolute path to the directory that will hold the files. Defaults to the value of your MEDIA_ROOT setting.

base_url

URL that serves the files stored at this location. Defaults to the value of your MEDIA_URL setting.

file_permissions_mode

The file system permissions that the file will receive when it is saved. Defaults to FILE_UPLOAD_PERMISSIONS.

New in Django 1.7:

The file_permissions_mode attribute was added. Previously files always received FILE_UPLOAD_PERMISSIONS permissions.

directory_permissions_mode

The file system permissions that the directory will receive when it is saved. Defaults to FILE_UPLOAD_DIRECTORY_PERMISSIONS.

New in Django 1.7:

The directory_permissions_mode attribute was added. Previously directories always received FILE_UPLOAD_DIRECTORY_PERMISSIONS permissions.

Note

The FileSystemStorage.delete() method will not raise an exception if the given file name does not exist.

The Storage Class

class Storage[source]

The Storage class provides a standardized API for storing files, along with a set of default behaviors that all other storage systems can inherit or override as necessary.

Note

For methods returning naive datetime objects, the effective timezone used will be the current value of os.environ['TZ']; note that this is usually set from Django’s TIME_ZONE.

accessed_time(name)[source]

Returns a naive datetime object containing the last accessed time of the file. For storage systems that aren’t able to return the last accessed time this will raise NotImplementedError instead.

created_time(name)[source]

Returns a naive datetime object containing the creation time of the file. For storage systems that aren’t able to return the creation time this will raise NotImplementedError instead.

delete(name)[source]

Deletes the file referenced by name. If deletion is not supported on the target storage system this will raise NotImplementedError instead

exists(name)[source]

Returns True if a file referenced by the given name already exists in the storage system, or False if the name is available for a new file.

get_available_name(name, max_length=None)[source]

Returns a filename based on the name parameter that’s free and available for new content to be written to on the target storage system.

The length of the filename will not exceed max_length, if provided. If a free unique filename cannot be found, a SuspiciousFileOperation exception will be raised.

If a file with name already exists, an underscore plus a random 7 character alphanumeric string is appended to the filename before the extension.

Changed in Django 1.7:

Previously, an underscore followed by a number (e.g. "_1", "_2", etc.) was appended to the filename until an available name in the destination directory was found. A malicious user could exploit this deterministic algorithm to create a denial-of-service attack. This change was also made in Django 1.6.6, 1.5.9, and 1.4.14.

Changed in Django 1.8:

The max_length argument was added.

get_valid_name(name)[source]

Returns a filename based on the name parameter that’s suitable for use on the target storage system.

listdir(path)[source]

Lists the contents of the specified path, returning a 2-tuple of lists; the first item being directories, the second item being files. For storage systems that aren’t able to provide such a listing, this will raise a NotImplementedError instead.

modified_time(name)[source]

Returns a naive datetime object containing the last modified time. For storage systems that aren’t able to return the last modified time, this will raise NotImplementedError instead.

open(name, mode='rb')[source]

Opens the file given by name. Note that although the returned file is guaranteed to be a File object, it might actually be some subclass. In the case of remote file storage this means that reading/writing could be quite slow, so be warned.

path(name)[source]

The local filesystem path where the file can be opened using Python’s standard open(). For storage systems that aren’t accessible from the local filesystem, this will raise NotImplementedError instead.

save(name, content, max_length=None)[source]

Saves a new file using the storage system, preferably with the name specified. If there already exists a file with this name name, the storage system may modify the filename as necessary to get a unique name. The actual name of the stored file will be returned.

The max_length argument is passed along to get_available_name().

The content argument must be an instance of django.core.files.File or of a subclass of File.

Changed in Django 1.8:

The max_length argument was added.

size(name)[source]

Returns the total size, in bytes, of the file referenced by name. For storage systems that aren’t able to return the file size this will raise NotImplementedError instead.

url(name)[source]

Returns the URL where the contents of the file referenced by name can be accessed. For storage systems that don’t support access by URL this will raise NotImplementedError instead.