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)

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