Данные Unicode

Создание базы данных

Убедитесь, что база данных настроена для хранения произвольных строковых данных. Обычно для этого нужно использовать кодировку UTF-8 или UTF-16. Если вы используете более ограниченную кодировку — например, latin1 (iso8859-1), — вы не сможете хранить в базе данных некоторые символы, и информация будет потеряна.

• Пользователям MySQL следует обратиться к руководству MySQL, чтобы узнать, как задать или изменить кодировку набора символов базы данных.
• Пользователям PostgreSQL следует обратиться к руководству PostgreSQL, чтобы узнать, как создавать базы данных с правильной кодировкой.
• Пользователям Oracle следует обратиться к руководству Oracle, чтобы узнать, как задать (раздел 2) или изменить (раздел 11) кодировку набора символов базы данных.
• Пользователям SQLite ничего делать не нужно. SQLite всегда использует UTF-8 для внутренней кодировки.

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

Подробнее см. в разделе «API базы данных» ниже.

Общая обработка строк

При использовании строк в Django — например, в запросах к базе данных, при рендеринге шаблонов или где-либо ещё — у вас есть два варианта кодировки этих строк. Вы можете использовать обычные строки или байтовые строки (начинающиеся с «b»).

Если ваш код использует только данные ASCII, можно безопасно использовать обычные строки и передавать их как угодно, поскольку ASCII является подмножеством UTF-8.

Не думайте, что если для параметра DEFAULT_CHARSET задано значение, отличное от 'utf-8', то в байтовых строках можно использовать эту другую кодировку! DEFAULT_CHARSET применяется только к строкам, созданным в результате рендеринга шаблонов (и электронной почты). Для внутренних байтовых строк Django всегда предполагает кодировку UTF-8. Причина в том, что параметр DEFAULT_CHARSET фактически не находится под вашим контролем (если вы разработчик приложения). Им управляет человек, устанавливающий и использующий ваше приложение. Если этот человек выберет другое значение, ваш код всё равно должен продолжать работать. Следовательно, код не может полагаться на этот параметр.

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

>>> from urllib.parse import quote
>>> from django.utils.encoding import iri_to_uri
>>> quote("Paris & Orléans")
'Paris%20%26%20Orl%C3%A9ans'
>>> iri_to_uri("/favorites/François/%s" % quote("Paris & Orléans"))
'/favorites/Fran%C3%A7ois/Paris%20%26%20Orl%C3%A9ans'

>>> from django.utils.encoding import uri_to_iri
>>> uri_to_iri("/%E2%99%A5%E2%99%A5/?utf8=%E2%9C%93")
'/♥♥/?utf8=✓'
>>> uri_to_iri("%A9hello%3Fworld")
'%A9hello%3Fworld'

iri_to_uri(iri_to_uri(some_string)) == iri_to_uri(some_string)
uri_to_iri(uri_to_iri(some_string)) == uri_to_iri(some_string)

Модели

Поскольку все строки возвращаются из базы данных как объекты str, поля моделей, основанные на строках (CharField, TextField, URLField и т. д.), при получении данных из базы данных Django содержат значения Unicode. Это всегда так, даже если данные могли бы поместиться в байтовую строку ASCII.

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

from urllib.parse import quote
from django.utils.encoding import iri_to_uri


def get_absolute_url(self):
    url = "/person/%s/?x=0&y=0" % quote(self.location)
    return iri_to_uri(url)

Шаблоны

При создании шаблонов вручную используйте строки:

from django.template import Template

t2 = Template("This is a string template.")

Однако чаще всего шаблоны читаются из файловой системы. Если файлы шаблонов сохранены не в кодировке UTF-8, измените параметр TEMPLATES. Встроенная серверная часть django предоставляет параметр 'file_charset' для изменения кодировки, используемой при чтении файлов с диска.

Параметр DEFAULT_CHARSET задаёт кодировку отрендеренных шаблонов. По умолчанию используется UTF-8.

Файлы

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

Поддержка имён файлов в UTF-8 в файловых системах различается и может зависеть от среды. Проверьте текущую конфигурацию в интерактивной оболочке Python, выполнив:

import sys

sys.getfilesystemencoding()

В результате должно появиться «UTF-8».

За установку ожидаемой кодировки в Unix отвечает переменная окружения LANG. Чтобы узнать подходящий синтаксис и место для задания этой переменной, обратитесь к документации своей операционной системы и сервера приложений. Примеры см. в документе Как использовать Django с Apache и mod_wsgi.

В среде разработки может потребоваться добавить настройку в файл ~.bashrc, например:

export LANG="en_US.UTF-8"

Отправка форм

Отправка HTML-форм — непростой вопрос. Нет гарантии, что при отправке будут переданы сведения о кодировке, а значит, фреймворку может потребоваться угадать кодировку отправленных данных.

Django использует «ленивый» подход к декодированию данных формы. Данные объекта HttpRequest декодируются только при обращении к ним. Более того, большая часть данных вообще не декодируется. Декодирование применяется только к структурам данных HttpRequest.GET и HttpRequest.POST. Эти два поля возвращают свои элементы как данные Unicode. Все остальные атрибуты и методы HttpRequest возвращают данные в точности в том виде, в каком они были отправлены клиентом.

По умолчанию параметр DEFAULT_CHARSET используется в качестве предполагаемой кодировки данных формы. Чтобы изменить её для конкретной формы, можно задать атрибут encoding экземпляра HttpRequest. Например:

def some_view(request):
    # We know that the data must be encoded as KOI8-R (for some reason).
    request.encoding = "koi8-r"
    ...

Вы можете изменить кодировку даже после обращения к request.GET или request.POST; при всех последующих обращениях будет использоваться новая кодировка.

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

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