File storage API¶
Getting the default storage class¶
Django provides convenient ways to access the default storage class:
-
class
DefaultStorage
[source]¶ DefaultStorage
provides lazy access to the default storage system as defined bydefault
key inSTORAGES
.DefaultStorage
usesstorages
internally.
-
default_storage
¶ default_storage
is an instance of theDefaultStorage
.
The FileSystemStorage
class¶
-
class
FileSystemStorage
(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None, allow_overwrite=False)[source]¶ 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 an exception if the given file name does not exist.-
location
[source]¶ Absolute path to the directory that will hold the files. Defaults to the value of your
MEDIA_ROOT
setting.
-
base_url
[source]¶ URL that serves the files stored at this location. Defaults to the value of your
MEDIA_URL
setting.
-
file_permissions_mode
[source]¶ The file system permissions that the file will receive when it is saved. Defaults to
FILE_UPLOAD_PERMISSIONS
.
-
directory_permissions_mode
[source]¶ The file system permissions that the directory will receive when it is saved. Defaults to
FILE_UPLOAD_DIRECTORY_PERMISSIONS
.
-
allow_overwrite
¶ - New in Django 5.1.
Flag to control allowing saving a new file over an existing one. Defaults to
False
.
-
get_created_time
(name)[source]¶ Returns a
datetime
of the system’s ctime, i.e.os.path.getctime()
. On some systems (like Unix), this is the time of the last metadata change, and on others (like Windows), it’s the creation time of the file.
-
The InMemoryStorage
class¶
-
class
InMemoryStorage
(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)[source]¶ The
InMemoryStorage
class implements a memory-based file storage. It has no persistence, but can be useful for speeding up tests by avoiding disk access.-
location
[source]¶ Absolute path to the directory name assigned to files. Defaults to the value of your
MEDIA_ROOT
setting.
-
base_url
[source]¶ URL that serves the files stored at this location. Defaults to the value of your
MEDIA_URL
setting.
-
file_permissions_mode
[source]¶ The file system permissions assigned to files, provided for compatibility with
FileSystemStorage
. Defaults toFILE_UPLOAD_PERMISSIONS
.
-
directory_permissions_mode
[source]¶ The file system permissions assigned to directories, provided for compatibility with
FileSystemStorage
. Defaults toFILE_UPLOAD_DIRECTORY_PERMISSIONS
.
-
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
When methods return naive
datetime
objects, the effective timezone used will be the current value ofos.environ['TZ']
; note that this is usually set from Django’sTIME_ZONE
.-
delete
(name)[source]¶ Deletes the file referenced by
name
. If deletion is not supported on the target storage system this will raiseNotImplementedError
instead.
-
exists
(name)[source]¶ Returns
True
if a file referenced by the given name already exists in the storage system.
-
get_accessed_time
(name)[source]¶ Returns a
datetime
of the last accessed time of the file. For storage systems unable to return the last accessed time this will raiseNotImplementedError
.If
USE_TZ
isTrue
, returns an awaredatetime
, otherwise returns a naivedatetime
in the local timezone.
-
get_alternative_name
(file_root, file_ext)[source]¶ Returns an alternative filename based on the
file_root
andfile_ext
parameters, an underscore plus a random 7 character alphanumeric string is appended to the filename before the extension.
-
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, aSuspiciousFileOperation
exception will be raised.If a file with
name
already exists,get_alternative_name()
is called to obtain an alternative name.
-
get_created_time
(name)[source]¶ Returns a
datetime
of the creation time of the file. For storage systems unable to return the creation time this will raiseNotImplementedError
.If
USE_TZ
isTrue
, returns an awaredatetime
, otherwise returns a naivedatetime
in the local timezone.
-
get_modified_time
(name)[source]¶ Returns a
datetime
of the last modified time of the file. For storage systems unable to return the last modified time this will raiseNotImplementedError
.If
USE_TZ
isTrue
, returns an awaredatetime
, otherwise returns a naivedatetime
in the local timezone.
-
get_valid_name
(name)[source]¶ Returns a filename based on the
name
parameter that’s suitable for use on the target storage system.
-
generate_filename
(filename)[source]¶ Validates the
filename
by callingget_valid_name()
and returns a filename to be passed to thesave()
method.The
filename
argument may include a path as returned byFileField.upload_to
. In that case, the path won’t be passed toget_valid_name()
but will be prepended back to the resulting name.The default implementation uses
os.path
operations. Override this method if that’s not appropriate for your storage.
-
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.
-
open
(name, mode='rb')[source]¶ 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)[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 raiseNotImplementedError
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 toget_available_name()
.The
content
argument must be an instance ofdjango.core.files.File
or a file-like object that can be wrapped inFile
.
-