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

В этом документе описаны API Django для доступа к файлам, например, загруженным пользователем. Низкоуровневые API достаточно универсальны, чтобы вы могли использовать их и для других целей. Если вы хотите обрабатывать «статические файлы» (JS, CSS и т. д.), см. Управление статическими файлами (например, изображениями, JavaScript, CSS).

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

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

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

При использовании 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')

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

>>> car = Car.objects.get(name="57 Chevy")
>>> car.photo
<ImageFieldFile: chevy.jpg>
>>> car.photo.name
'cars/chevy.jpg'
>>> car.photo.path
'/media/cars/chevy.jpg'
>>> car.photo.url
'http://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 = 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

Объект File

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

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

Если вам нужно создать объект 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

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

IOError: [Errno 24] Too many open files

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

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

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

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

Объекты хранения

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

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

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

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

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

См. API хранения файлов для получения информации об API хранения файлов.

Встроенный класс хранения файловой системы

Django поставляется с классом django.core.files.storage.FileSystemStorage, который реализует базовое локальное хранение файлов файловой системы.

Например, следующий код сохранит загруженные файлы в /media/photos независимо от значения настройки MEDIA_ROOT:

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)

Настраиваемые системы хранения работают аналогичным образом: вы можете передать их в качестве аргумента storage в FileField.