Управление файлами

Использование файлов в моделях

При использовании FileField или ImageField Django предоставляет набор API для работы с этим файлом.

Рассмотрим следующую модель, в которой для хранения фотографии используется ImageField:

from django.db import models


class Car(models.Model):
    name = models.CharField(max_length=255)
    price = models.DecimalField(max_digits=5, decimal_places=2)
    photo = models.ImageField(upload_to="cars")
    specs = models.FileField(upload_to="specs")

У любого экземпляра Car будет атрибут photo, с помощью которого можно получить сведения о прикреплённой фотографии:

>>> car = Car.objects.get(name="57 Chevy")
>>> car.photo
<ImageFieldFile: cars/chevy.jpg>
>>> car.photo.name
'cars/chevy.jpg'
>>> car.photo.path
'/media/cars/chevy.jpg'
>>> car.photo.url
'https://media.example.com/cars/chevy.jpg'

Этот объект — car.photo в примере — является объектом File, а значит, имеет все описанные ниже методы и атрибуты.

Например, имя файла можно изменить, задав атрибуту name путь относительно расположения файлового хранилища (это MEDIA_ROOT, если вы используете FileSystemStorage по умолчанию):

>>> import os
>>> from django.conf import settings
>>> initial_path = car.photo.path
>>> car.photo.name = "cars/chevy_ii.jpg"
>>> new_path = os.path.join(settings.MEDIA_ROOT, car.photo.name)
>>> # Move the file on the filesystem
>>> os.rename(initial_path, new_path)
>>> car.save()
>>> car.photo.path
'/media/cars/chevy_ii.jpg'
>>> car.photo.path == new_path
True

Чтобы сохранить существующий файл с диска в FileField:

>>> from pathlib import Path
>>> from django.core.files import File
>>> path = Path("/some/external/specs.pdf")
>>> car = Car.objects.get(name="57 Chevy")
>>> with path.open(mode="rb") as f:
...     car.specs = File(f, name=path.name)
...     car.save()
...

>>> from PIL import Image
>>> car = Car.objects.get(name="57 Chevy")
>>> car.photo.width
191
>>> car.photo.height
287
>>> image = Image.open(car.photo)
# Raises ValueError: seek of closed file.
>>> car.photo.open()
<ImageFieldFile: cars/chevy.jpg>
>>> image = Image.open(car.photo)
>>> image
<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=191x287 at 0x7F99A94E9048>

Объект File

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

В большинстве случаев вы будете использовать объект File, предоставленный Django (то есть файл, прикреплённый к модели, как показано выше, или, возможно, загруженный файл).

Если вам нужно создать объект File самостоятельно, проще всего сделать это с помощью встроенного в Python объекта file:

>>> from django.core.files import File

# Create a Python file object using open()
>>> f = open("/path/to/hello.world", "w")
>>> myfile = File(f)

Теперь вы можете использовать любые документированные атрибуты и методы класса File.

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

>>> from django.core.files import File

# Create a Python file object using open() and the with statement
>>> with open("/path/to/hello.world", "w") as f:
...     myfile = File(f)
...     myfile.write("Hello World")
...
>>> myfile.closed
True
>>> f.closed
True

Закрывать файлы особенно важно при обращении к полям файлов в цикле по большому количеству объектов. Если после обращения к файлам не закрывать их вручную, может возникнуть риск исчерпания дескрипторов файлов. Это может привести к следующей ошибке:

OSError: [Errno 24] Too many open files

Хранение файлов

За кулисами Django делегирует файловой системе хранения принятие решений о том, как и где хранить файлы. Именно этот объект обрабатывает такие операции, как работа с файловыми системами, открытие и чтение файлов и т. д.

По умолчанию Django использует файловое хранилище 'django.core.files.storage.FileSystemStorage'. Если вы явно не укажете систему хранения в ключе default настройки STORAGES, будет использоваться именно она.

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

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

>>> path = default_storage.save("path/to/file", ContentFile(b"new content"))
>>> path
'path/to/file'

>>> default_storage.size(path)
11
>>> default_storage.open(path).read()
b'new content'

>>> default_storage.delete(path)
>>> default_storage.exists(path)
False

from django.core.files.storage import FileSystemStorage
from django.db import models

fs = FileSystemStorage(location="/media/photos")


class Car(models.Model):
    ...
    photo = models.ImageField(storage=fs)

from django.conf import settings
from django.db import models
from .storages import MyLocalStorage, MyRemoteStorage


def select_storage():
    return MyLocalStorage() if settings.DEBUG else MyRemoteStorage()


class MyModel(models.Model):
    my_file = models.FileField(storage=select_storage)

from django.core.files.storage import storages


def select_storage():
    return storages["mystorage"]


class MyModel(models.Model):
    upload = models.FileField(storage=select_storage)

from django.core.files.storage import storages
from django.utils.functional import LazyObject


class OtherStorage(LazyObject):
    def _setup(self):
        self._wrapped = storages["mystorage"]


my_storage = OtherStorage()


class MyModel(models.Model):
    upload = models.FileField(storage=my_storage)

@override_settings(
    STORAGES={
        "mystorage": {
            "BACKEND": "django.core.files.storage.InMemoryStorage",
        }
    }
)
def test_storage():
    model = MyModel()
    assert isinstance(model.upload.storage, InMemoryStorage)