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

В данном документе описываются 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 (т.е. файл, прикреплённый к модели, как указано выше, или, возможно, загруженный файл).

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