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¶

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)¶

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

Примечание

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

location¶

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

base_url¶

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

file_permissions_mode¶

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

directory_permissions_mode¶

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

allow_overwrite¶

New in Django 5.1.

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

get_created_time(name)¶

Возвращает datetime системное время ctime, т.е. 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, если файл, на который ссылается данное имя, уже существует в системе хранения.

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)¶

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