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

Этот документ описывает 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 всякий раз, когда ему нужно представить файл. Этот объект — тонкий обертка над встроенным объектом файла Python встроенный объект файла с некоторыми специфичными для Django дополнениями.

В большинстве случаев вы просто будете использовать предоставленный 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.storage import default_storage
>>> from django.core.files.base import ContentFile

>>> 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.db import models
from django.core.files.storage import FileSystemStorage

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

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

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