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

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

В большинстве случаев вы просто используете 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

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

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.