API хранилища файлов

Получение класса хранилища по умолчанию

Django предоставляет удобные способы доступа к классу хранилища по умолчанию:

storages

Объект, подобный словарю, который позволяет получить экземпляр хранилища по его псевдониму, определённому в STORAGES.

У storages есть атрибут backends, значение которого по умолчанию равно исходному значению, указанному в STORAGES.

Кроме того, storages предоставляет метод create_storage(), который принимает словарь, используемый в STORAGES для бэкенда, и возвращает экземпляр хранилища на основе определения этого бэкенда. Это может быть полезно сторонним пакетам, которым требуется создавать экземпляры хранилищ в тестах:

>>> from django.core.files.storage import storages
>>> storages.backends
{'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
 'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
 'custom': {'BACKEND': 'package.storage.CustomStorage'}}
>>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})

class DefaultStorage [исходный код]

DefaultStorage обеспечивает отложенный доступ к системе хранения по умолчанию, заданной ключом default в STORAGES. Внутри DefaultStorage использует storages.

default_storage

default_storage — это экземпляр DefaultStorage.

Класс FileSystemStorage

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None, allow_overwrite=False) [исходный код]

Класс FileSystemStorage реализует базовое хранение файлов в локальной файловой системе. Он наследуется от Storage и предоставляет реализации всех его открытых методов.

Примечание

Метод FileSystemStorage.delete() не вызовет исключение, если указанный файл не существует.

location [исходный код]

Абсолютный путь к каталогу, в котором будут храниться файлы. По умолчанию используется значение параметра MEDIA_ROOT.

base_url [исходный код]

URL-адрес для доступа к файлам, хранящимся в этом расположении. По умолчанию используется значение параметра MEDIA_URL.

file_permissions_mode [исходный код]

Разрешения файловой системы, которые будут назначены файлу при сохранении. По умолчанию используется FILE_UPLOAD_PERMISSIONS.

directory_permissions_mode [исходный код]

Разрешения файловой системы, которые будут назначены каталогу при сохранении. По умолчанию используется FILE_UPLOAD_DIRECTORY_PERMISSIONS.

allow_overwrite

Флаг, управляющий возможностью сохранения нового файла поверх существующего. По умолчанию имеет значение False.

get_created_time(name) [исходный код]

Возвращает значение datetime, соответствующее ctime системы, то есть os.path.getctime(). В некоторых системах (например, Unix) это время последнего изменения метаданных, а в других (например, Windows) — время создания файла.

Класс InMemoryStorage

class InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None) [исходный код]

Класс InMemoryStorage реализует файловое хранилище в памяти. Оно не обеспечивает постоянного хранения, но может ускорить тесты, поскольку позволяет избежать обращения к диску.

location [исходный код]

Абсолютный путь к имени каталога, назначенному файлам. По умолчанию используется значение параметра MEDIA_ROOT.

base_url [исходный код]

URL-адрес для доступа к файлам, хранящимся в этом расположении. По умолчанию используется значение параметра MEDIA_URL.

file_permissions_mode [исходный код]

Разрешения файловой системы, назначаемые файлам; атрибут предусмотрен для совместимости с FileSystemStorage. По умолчанию используется FILE_UPLOAD_PERMISSIONS.

directory_permissions_mode [исходный код]

Разрешения файловой системы, назначаемые каталогам; атрибут предусмотрен для совместимости с FileSystemStorage. По умолчанию используется FILE_UPLOAD_DIRECTORY_PERMISSIONS.

Класс Storage

class Storage [исходный код]

Класс Storage предоставляет стандартизированный API для хранения файлов, а также набор поведений по умолчанию, которые все остальные системы хранения могут наследовать или переопределять при необходимости.

Примечание

Если методы возвращают наивные объекты datetime, будет использоваться текущее значение os.environ['TZ']; обратите внимание, что обычно оно задаётся параметром Django TIME_ZONE.

delete(name) [исходный код]

Удаляет файл, на который ссылается name. Если целевая система хранения не поддерживает удаление, вместо этого будет вызвано исключение NotImplementedError.

exists(name) [исходный код]

Возвращает True, если файл с указанным именем уже существует в системе хранения.

get_accessed_time(name) [исходный код]

Возвращает значение datetime, соответствующее времени последнего доступа к файлу. Для систем хранения, которые не могут вернуть время последнего доступа, будет вызвано исключение NotImplementedError.

Если USE_TZ имеет значение True, возвращается объект datetime с часовым поясом; в противном случае возвращается наивный datetime в местном часовом поясе.

get_alternative_name(file_root, file_ext) [исходный код]

Возвращает альтернативное имя файла на основе параметров file_root и file_ext: перед расширением к имени файла добавляется символ подчёркивания и случайная буквенно-цифровая строка из 7 символов.

get_available_name(name, max_length=None) [исходный код]

Возвращает имя файла на основе параметра name, которое свободно и доступно для записи нового содержимого в целевой системе хранения.

Длина имени файла не превысит max_length, если этот параметр указан. Если не удастся найти свободное уникальное имя файла, будет вызвано исключение SuspiciousFileOperation.

Если файл с именем name уже существует, для получения альтернативного имени вызывается get_alternative_name().

get_created_time(name) [исходный код]

Возвращает значение datetime, соответствующее времени создания файла. Для систем хранения, которые не могут вернуть время создания, будет вызвано исключение NotImplementedError.

Если USE_TZ имеет значение True, возвращается объект datetime с часовым поясом; в противном случае возвращается наивный datetime в местном часовом поясе.

get_modified_time(name) [исходный код]

Возвращает значение datetime, соответствующее времени последнего изменения файла. Для систем хранения, которые не могут вернуть время последнего изменения, будет вызвано исключение NotImplementedError.

Если USE_TZ имеет значение True, возвращается объект datetime с часовым поясом; в противном случае возвращается наивный datetime в местном часовом поясе.

get_valid_name(name) [исходный код]

Возвращает имя файла на основе параметра name, пригодное для использования в целевой системе хранения.

generate_filename(filename) [исходный код]

Проверяет filename, вызывая get_valid_name, и возвращает имя файла, которое будет передано методу save().

Аргумент filename может содержать путь, возвращаемый FileField.upload_to. В этом случае путь не будет передан в get_valid_name, но будет добавлен в начало полученного имени.

Реализация по умолчанию использует операции os.path. Переопределите этот метод, если он не подходит для вашего хранилища.

listdir(path) [исходный код]

Выводит список содержимого указанного пути и возвращает кортеж из двух списков: первый содержит каталоги, второй — файлы. Для систем хранения, которые не могут предоставить такой список, будет вызвано исключение NotImplementedError.

open(name, mode='rb') [исходный код]

Открывает файл, указанный в name. Обратите внимание: хотя возвращаемый файл гарантированно является объектом File, фактически он может быть экземпляром подкласса. При удалённом хранении файлов это означает, что чтение и запись могут выполняться довольно медленно.

path(name) [исходный код]

Путь в локальной файловой системе, по которому файл можно открыть с помощью стандартного средства Python open(). Для систем хранения, недоступных из локальной файловой системы, вместо этого будет вызвано исключение NotImplementedError.

save(name, content, max_length=None) [исходный код]

Сохраняет новый файл с помощью системы хранения, по возможности используя указанное имя. Если файл с таким именем уже существует name, система хранения может изменить имя файла, чтобы обеспечить его уникальность. Возвращается фактическое имя сохранённого файла.

Аргумент max_length передаётся в get_available_name().

Аргумент content должен быть экземпляром django.core.files.File или файловым объектом, который можно обернуть в File.

size(name) [исходный код]

Возвращает общий размер в байтах файла, на который ссылается name. Для систем хранения, которые не могут вернуть размер файла, вместо этого будет вызвано исключение NotImplementedError.

url(name) [исходный код]

Возвращает URL-адрес, по которому можно получить доступ к содержимому файла, на который ссылается name. Для систем хранения, не поддерживающих доступ по URL, вместо этого будет вызвано исключение NotImplementedError.