Данные Юникода

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

Убедитесь, что ваша база данных настроена для хранения произвольных строковых данных. Обычно это означает использование кодировки 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 и т. д.), будут содержать значения Unicode, когда Django извлекает данные из базы данных. Это происходит всегда, даже если данные могли бы поместиться в строку байтов 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. Если ваша среда настроена неправильно, при сохранении файлов с именами файлов или содержимым, содержащим не-ASCII символы, возникнут исключения UnicodeEncodeError.

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

import sys

sys.getfilesystemencoding()

Это должно вывести «UTF-8».

Переменная среды LANG отвечает за установку ожидаемой кодировки на платформах Unix. Обратитесь к документации вашей операционной системы и веб-сервера для получения соответствующего синтаксиса и местоположения для установки этой переменной. См. Инструкции по использованию 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 не декодирует данные загружаемых файлов, так как эти данные обычно обрабатываются как наборы байтов, а не как строки. Любое автоматическое декодирование в этом случае изменит значение потока байтов.