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

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

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

storages¶

New in Django 4.2.

Экземпляры хранилища, как определено в STORAGES.

class DefaultStorage[исходный код]¶

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

default_storage¶

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

get_storage_class(import_path=None)[исходный код]¶

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

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

Не рекомендуется, начиная с версии 4.2: Функция get_storage_class() является устаревшей. Вместо нее используйте storages

Класс 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) - время создания файла.

Класс 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, если файл, на который ссылается данное имя, уже существует в системе хранения, или 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)[исходный код]¶

Путь к локальной файловой системе, где файл может быть открыт с помощью стандартной команды 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.