File storage API¶
Getting the current storage class¶
Django provides two convenient ways to access the current storage class:
-
class
DefaultStorage
¶ DefaultStorage
provides lazy access to the current default storage system as defined byDEFAULT_FILE_STORAGE
.DefaultStorage
usesget_storage_class()
internally.
-
get_storage_class
([import_path=None])¶ Returns a class or module which implements the storage API.
When called without the
import_path
parameterget_storage_class
will return the current default storage system as defined byDEFAULT_FILE_STORAGE
. Ifimport_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
¶ The
FileSystemStorage
class implements basic file storage on a local filesystem. It inherits fromStorage
and provides implementations for all the public methods thereof.Note
The
FileSystemStorage.delete()
method will not raise raise an exception if the given file name does not exist.
The Storage Class¶
-
class
Storage
¶ 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.-
accessed_time
(name)¶ Returns a
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 raiseNotImplementedError
instead.
-
created_time
(name)¶ Returns a
datetime
object containing the creation time of the file. For storage systems that aren’t able to return the creation time this will raiseNotImplementedError
instead.
-
delete
(name)¶ Deletes the file referenced by
name
. If deletion is not supported on the target storage system this will raiseNotImplementedError
instead
-
exists
(name)¶ Returns
True
if a file referenced by the given name already exists in the storage system, orFalse
if the name is available for a new file.
-
get_available_name
(name)¶ 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.
-
get_valid_name
(name)¶ Returns a filename based on the
name
parameter that’s suitable for use on the target storage system.
-
listdir
(path)¶ 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)¶ Returns a
datetime
object containing the last modified time. For storage systems that aren’t able to return the last modified time, this will raiseNotImplementedError
instead.
-
open
(name, mode='rb')¶ Opens the file given by
name
. Note that although the returned file is guaranteed to be aFile
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)¶ 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 raiseNotImplementedError
instead.
-
save
(name, content)¶ 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
content
argument must be an instance ofdjango.core.files.File
or of a subclass ofFile
.
-
size
(name)¶ 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 raiseNotImplementedError
instead.
-
url
(name)¶ 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 raiseNotImplementedError
instead.
-