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

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

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

storages

Новое в Django 4.2.

Экземпляры хранилищ, определенные в STORAGES.

class DefaultStorage

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

default_storage

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

get_storage_class(import_path=None)

Возвращает класс или модуль, реализующий API хранилища.

При вызове без параметра import_path get_storage_class вернет систему хранения по умолчанию, как определено ключом default в STORAGES. Если параметр import_path указан, get_storage_class попытается импортировать класс или модуль из указанного пути и вернет его, если это удастся. Если импорт не удастся, будет выброшено исключение.

Устарело начиная с версии 4.2: Функция get_storage_class() устарела. Используйте storages вместо неё.

Класс FileSystemStorage

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

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

location

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

base_url

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

file_permissions_mode

Права доступа к файлам в файловой системе после сохранения. По умолчанию FILE_UPLOAD_PERMISSIONS.

directory_permissions_mode

Права доступа к каталогам в файловой системе после сохранения. По умолчанию FILE_UPLOAD_DIRECTORY_PERMISSIONS.

Примечание

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

get_created_time(name)

Возвращает datetime времени последнего изменения метаданных, т.е. 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 если файл с указанным именем уже существует в системе хранения, или False если имя доступно для нового файла.

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.