Метод save

Метод save класса Storage предназначен для сохранения файла в хранилище. Он принимает имя файла и содержимое для записи, а также опциональные параметры, позволяющие управлять процессом сохранения. Метод возвращает строку с именем сохраненного файла, которое может отличаться от переданного в аргументах (например, если в хранилище уже существует файл с таким именем и включена автоматическая генерация уникального имени).

Синтаксис

storage.save(name, content, max_length=None)

Параметры метода:

name - строка с именем файла, под которым он будет сохранен в хранилище. Может содержать путь к подпапкам (например, 'images/photo.jpg').
content - содержимое файла. Должен быть объектом, поддерживающим интерфейс файла, например экземпляр File или ContentFile.
max_length - максимальная длина имени файла. Если имя файла превышает указанное значение, оно будет обрезано или заменено на уникальное.

Базовое сохранение файла

Рассмотрим сохранение текстового файла в хранилище с использованием метода save:

from django.core.files.storage import default_storage
from django.core.files.base import ContentFile

# Создаем содержимое файла
content = ContentFile(b"Hello, World!")

# Сохраняем файл
saved_name = default_storage.save("hello.txt", content)

print(saved_name)

Результат выполнения кода:

"hello.txt"

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

Сохранение с изменением имени файла

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

from django.core.files.storage import FileSystemStorage
from django.core.files.base import ContentFile

# Создаем хранилище с автоматическим изменением имени
storage = FileSystemStorage()

# Сохраняем первый файл
content1 = ContentFile(b"First content")
storage.save("test.txt", content1)

# Сохраняем второй файл с тем же именем
content2 = ContentFile(b"Second content")
saved_name = storage.save("test.txt", content2)

print(saved_name)

Результат выполнения кода:

"test_1.txt"

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

Сохранение файла в подпапку

Метод save позволяет указывать относительный путь к файлу внутри хранилища. Это полезно для организации файловой структуры:

from django.core.files.storage import default_storage
from django.core.files.base import ContentFile

# Создаем содержимое
content = ContentFile(b"Image data")

# Сохраняем файл в подпапку
saved_name = default_storage.save("images/photo.jpg", content)

print(saved_name)

Результат выполнения кода:

"images/photo.jpg"

Если указанные подпапки не существуют, они будут созданы автоматически (для некоторых хранилищ это поведение может отличаться).

Использование с моделью

Чаще всего метод save используется внутри модели при сохранении файлового поля. Рассмотрим пример с моделью Document:

from django.db import models
from django.core.files.storage import default_storage
from django.core.files.base import ContentFile

class Document(models.Model):
	title = models.CharField(max_length=100)
	file = models.FileField(upload_to="documents/")

	def save(self, *args, **kwargs):
		# Обработка перед сохранением
		super().save(*args, **kwargs)

Для сохранения файла в экземпляр модели можно использовать метод save поля:

from myapp.models import Document
from django.core.files.base import ContentFile

# Создаем экземпляр модели
doc = Document(title="My Document")

# Сохраняем файл
content = ContentFile(b"Document content")
doc.file.save("report.txt", content)

# Сохраняем модель
doc.save()

print(doc.file.name)

Результат выполнения кода:

"documents/report.txt"

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

Смотрите также

метод open,
который открывает файл для чтения или записи
метод delete,
который удаляет файл из хранилища
метод exists,
который проверяет существование файла
метод get_available_name,
который возвращает доступное имя для сохранения