API хранения файлов

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

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

storages

Объект, подобный словарю, позволяющий получить экземпляр хранилища, используя его псевдоним, определённый в STORAGES.

storages имеет атрибут backends, который по умолчанию принимает значение, заданное в STORAGES.

Кроме того, storages предоставляет метод create_storage(), принимающий словарь, используемый в STORAGES для бэкенда, и возвращает экземпляр хранилища на основе определения этого бэкенда. Это может быть полезно для сторонних пакетов, которым необходимо инициализировать хранилища в тестах:

>>> from django.core.files.storage import storages
>>> storages.backends
{'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
 'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
 'custom': {'BACKEND': 'package.storage.CustomStorage'}}
>>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})

class DefaultStorage [source]

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

default_storage

default_storage является экземпляром DefaultStorage.

Класс FileSystemStorage

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None, allow_overwrite=False) [source]

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

Примечание

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

location [source]

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

base_url [source]

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

file_permissions_mode [source]

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

directory_permissions_mode [source]

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

allow_overwrite

Новое в Django 5.1.

Флаг, определяющий возможность перезаписи существующего файла. По умолчанию значение False.

get_created_time(name) [source]

Возвращает datetime времени последнего изменения метаданных, т.е. os.path.getctime(). На некоторых системах (например, Unix) это время последнего изменения метаданных, а на других (например, Windows) — время создания файла.

Класс InMemoryStorage

class InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None) [source]

Класс InMemoryStorage реализует хранение файлов в памяти. Он не имеет персистентности, но может быть полезен для ускорения тестов, избегая доступа к диску.

location [source]

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

base_url [source]

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

file_permissions_mode [source]

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

directory_permissions_mode [source]

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

Класс Storage

class Storage [source]

Класс Storage предоставляет стандартизированный API для хранения файлов, вместе с набором стандартных поведений, которые все другие системы хранения могут унаследовать или переопределить по мере необходимости.

Примечание

Когда методы возвращают объекты datetime по умолчанию, используемое эффективное часовое поясное время будет текущим значением os.environ['TZ']; обратите внимание, что это обычно устанавливается из настроек Django TIME_ZONE.

delete(name) [source]

Удаляет файл, на который ссылается name. Если удаление не поддерживается целевой системой хранения, будет поднято исключение NotImplementedError.

exists(name) [source]

Возвращает True, если файл с заданным именем уже существует в системе хранения.

get_accessed_time(name) [source]

Возвращает datetime последнего времени доступа к файлу. Для систем хранения, неспособных вернуть время последнего доступа, будет поднято исключение NotImplementedError.

Если USE_TZ равно True, возвращает осознанное datetime, в противном случае возвращает неосознанное datetime в местном часовом поясе.

get_alternative_name(file_root, file_ext) [source]

Возвращает альтернативное имя файла на основе параметров file_root и file_ext, к имени файла перед расширением добавляется символ подчеркивания и случайная 7-символьная буквенно-цифровая строка.

get_available_name(name, max_length=None) [source]

Возвращает имя файла на основе параметра name, которое свободно и доступно для записи нового содержимого в целевой системе хранения.

Длина имени файла не будет превышать max_length, если оно предоставлено. Если уникальное свободное имя файла не может быть найдено, будет поднято исключение SuspiciousFileOperation.

Если файл с именем name уже существует, вызывается функция get_alternative_name() для получения альтернативного имени.

get_created_time(name) [source]

Возвращает datetime времени создания файла. Для систем хранения, неспособных вернуть время создания, будет поднято исключение NotImplementedError.

Если USE_TZ равно True, возвращает осознанное datetime, в противном случае возвращает неосознанное datetime в местном часовом поясе.

get_modified_time(name) [source]

Возвращает datetime последнего времени изменения файла. Для систем хранения, неспособных вернуть время последнего изменения, будет поднято исключение NotImplementedError.

Если USE_TZ равно True, возвращает осознанное datetime, в противном случае возвращает неосознанное datetime в местном часовом поясе.

get_valid_name(name) [source]

Возвращает имя файла на основе параметра name, подходящее для использования в целевой системе хранения.

generate_filename(filename) [source]

Проверяет filename, вызывая get_valid_name() и возвращает имя файла, которое будет передано методу save().

Аргумент filename может содержать путь, возвращаемый методом FileField.upload_to. В этом случае, путь не будет передан методу get_valid_name(), но будет добавлен в начало полученного имени.

По умолчанию используется операция os.path. Переопределите этот метод, если это не подходит для вашей системы хранения.

listdir(path) [source]

Перечисляет содержимое указанного пути, возвращая пару кортежей списков; первый элемент — это каталоги, второй — файлы. Для систем хранения, не способных предоставить такой список, вместо этого будет поднято исключение NotImplementedError.

open(name, mode='rb') [source]

Открывает файл, указанный через name. Обратите внимание, что хотя возвращаемый файл гарантированно является объектом File, он может фактически быть подклассом. В случае удаленного хранения файлов это означает, что чтение/запись может быть довольно медленным, поэтому будьте осторожны.

path(name) [source]

Локальный путь к файлу на файловой системе, где его можно открыть с помощью стандартных функций open() Python. Для систем хранения, недоступных из локальной файловой системы, будет поднято исключение NotImplementedError.

save(name, content, max_length=None) [source]

Сохраняет новый файл с использованием системы хранения, предпочтительно с указанным именем. Если файл с таким именем name уже существует, система хранения может изменить имя файла по мере необходимости, чтобы получить уникальное имя. Возвращается фактическое имя сохраненного файла.

Аргумент max_length передается в метод get_available_name().

Аргумент content должен быть экземпляром django.core.files.File или файлоподобным объектом, который можно обернуть в File.

size(name) [source]

Возвращает общий размер файла, указанного по ссылке name, в байтах. Для систем хранения, которые не могут вернуть размер файла, это вызовет NotImplementedError.

url(name) [source]

Возвращает URL, по которому можно получить доступ к содержимому файла, указанного по ссылке name. Для систем хранения, которые не поддерживают доступ по URL, это вызовет NotImplementedError.