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']; обратите внимание, что это обычно устанавливается из TIME_ZONE Django.

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)

Локальный путь к файлу на файловой системе, где файл можно открыть с помощью стандартного open() Python. Для систем хранения, которые недоступны из локальной файловой системы, это вызовет 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.