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

Получение текущего класса хранилища

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

class DefaultStorage

DefaultStorage предоставляет леничный доступ к текущей системе хранилища по умолчанию, как определено в DEFAULT_FILE_STORAGE. DefaultStorage использует get_storage_class() внутри.

get_storage_class(import_path=None)

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

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

Класс 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 системного времени ctime, т.е. os.path.getctime(). На некоторых системах (например, Unix) это время последнего изменения метаданных, а на других (например, Windows) — время создания файла.

Класс 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)

Новое в Django 3.0.

Возвращает альтернативное имя файла, основанное на 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.