Загрузка файлов из форм в Django

После нескольких восторгов по поводу Django настало время написать и о кривостях. Одна из них -- то, как обрабатываются файлы, закачиваемые из браузера через <input type="file">. Вопросы, с ними связанные, с завидным постоянством появляются в джанговской рассылке.

Автоматизированная обработка форм

Автоматизация обработки форм -- одна из самых сильных сторон Django. Она делается с помощью так называемых "манипуляторов", которые делают две вещи:

• конвертируют данные из внутренних типов модели БД в пригодный для HTML-формочек вид
• валидируют принятые через POST данные и конвертируют их обратно во внутренние типы

Самое приятное во всей идее манипуляторов, что Django делает их для моделей автоматически. То есть если в модели заказа описана ссылка на клиента:

class Order(meta.Model):
  client = meta.ForeignKey(Client)

... для поля client будет автоматически построен <select> с именами клиентов, а при возврате данных из формы манипулятор проверит, что поле, во-первых, заполнено, а во-вторых, заполнено существующим id клиента. Если валидация прошла успешно, то манипулятор сможет сохранить данные в базу, а если были ошибки, то покажет ту же самую форму, но уже с заполненными текущими данными, а также с ошибками для каждого отдельного поля.

В коде все выглядит довольно понятно.

Вывод формы

# создается автоматический манипулятор для объекта
manipulator = orders.ChangeManipulator(id)

# данные объекта переводятся в "формочный" вид
data = manipulator.flatten_data()

# FormWrapper умеет рисовать элементы форм с данными
form=FormWrapper(manipulator,data,{})

return render_to_response('order_template',{'form':form})

Прием POST-данных

manipulator=orders.ChangeManipulator(id)

# данные копируются из POST для дальнейших издевательств
data=request.POST.copy()

# валидация данных
errors=manipulator.get_validation_errors(data)

if errors:

  # При ошибках форма и ошибки выводятся обратно
  form=FormWrapper(manipulator,data,errors)
  return render_to_response('order_template',{'form':form})

else:

  # Если ошибок нет, данные конвертируются и сохраняются
  manipulator.do_html2python(data)
  manipulator.save(data)

  return HttpResponseRedirect('./')

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

Но это работает не всегда.

Файловые поля

В Django есть два типа полей -- FileField и ImageField -- которые представляются в виде файлового контрола в формах. И они отличаются от других полей тем, что для них нужно производить неочевидные (и не описанные в документации) вещи. И при выводе в форму, и при обработке.

Связаны отличия с тем, что сами файлы не хранятся в БД, а складываются в файловой системе. В самой БД хранятся только названия файлов.

Дальше я все буду рассматривать на примере модели музыкального альбома, у которого есть текстовое название и картинка обложки:

class Album(meta.Model):
  title = meta.CharField(maxlength=50)
  cover = meta.ImageField()

Вывод

Здесь есть двое часто наступаемых грабель.

Первые простые. Не все помнят, что для того, чтобы браузер вообще передавал файлы на сервер, надо фоме прописать enctype="multipart/form-data". Тут Django ни при чем, просто это часто забывается.

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

{{ form.title }}

... и оно превратится в

<input type="text" id="id_title" class="vTextField required" name="title" size="30" value="..." maxlength="50" />

Для файлов же надо указывать два поля:

{{ form.cover }} {{ form.cover_file }}

Первое -- это скрытое поле, в котором лежит текущее название файла, а второе -- непосредственно файловый контрол с кнопкой "Browse...".

Причем, как видно, сама картинка не выводится. Чтобы ее вывести, надо написать:

{% if form.data.cover %}<img src="{{ album.get_cover_url }}">{% endif %}

При этом, очевидно, файл картинки должен лежать в месте, видном с веба. Иначе никакого URL к нему Django построить не сможет.

На самом деле, в том, что файловые поля выводятся сложнее, чем обычные поля, Django не "виновато". Как раз наоборот -- хорошо, что фреймворк не пытается форматировать эти вещи автоматически, а дает свободу в том, как это будет расположено в форме, и надо ли включать саму картинку. Но это не повод все это не документировать! :-)

Прием

При приеме файловых полей автоматические манипуляторы не сохраняют переданный файл. То есть по manipulator.save(data) сохранится только имя файла в поле "cover". А дальше надо работать вручную:

album=manipulator.save(data)
album.save_cover_file(
  request.FILES['cover_file']['filename'],
  request.FILES['cover_file']['content'])

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

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

Опуская подробности моей вчерашней отладки, когда я с каждым шагом узнавал, что "ах, и это тоже ручками...", все выливается примерно в такой алгоритм:

• посмотреть в исходный объект, есть ли у него уже сохраненный файл (поле "cover" не пустое), и получить имя файла
• сохранить новые данные манипулятором
• если по данным формы видно, что файл удаляется или там есть новый файл, удалить старый файл вручную
• если в данных формы есть новый файл, сохранить его на диск

В коде это выглядит так (можно свободно пользоваться):

old_filename=manipulator.original_object.cover and manipulator.original_object.get_cover_filename()
album=manipulator.save(data)
if (not data['cover'] or request.FILES.get('cover_file','')) and old_filename:
  os.remove(old_filename)
if request.FILES.get('cover_file',''):
  album.save_cover_file(
    request.FILES['cover_file']['filename'],
    request.FILES['cover_file']['content'])

На стороне браузера тоже потребуется одно дополнение. В том варианте, который я предлагал раньше, нет никаких средств, чтобы удалить картинку. Для этого я повесил кнопку, по которой javascript'ом очищается значение у скрытого <input name="cover">, а также удаляется сама картинка. Именно по пустому "cover" на сервере определяется факт удаления.

Итог

Я всеми руками за то, чтобы интерфейсная часть в HTML делалась вручную, это как раз то, что нужно контролировать. Но вот перезаписывание и удаление файлов вполне может и должно делаться в манипуляторах автоматически. Кто первый сделает патч? :-)