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

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

Новое в 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.