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

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

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

• Пользователи MySQL, обратитесь к разделу MySQL manual для получения подробной информации о том, как установить или изменить кодировку набора символов базы данных.
• PostgreSQL users, refer to the PostgreSQL manual for details on creating databases with the correct encoding.
• Пользователи Oracle, обратитесь к разделу Oracle manual для получения подробной информации о том, как установить (section 2) или изменить (section 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.

Файлы¶

If you intend to allow users to upload files, you must ensure that the environment used to run Django is configured to work with non-ASCII file names. If your environment isn’t configured correctly, you’ll encounter UnicodeEncodeError exceptions when saving files with file names or content that contains non-ASCII characters.

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

import sys
sys.getfilesystemencoding()

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

The LANG environment variable is responsible for setting the expected encoding on Unix platforms. Consult the documentation for your operating system and application server for the appropriate syntax and location to set this variable. See the Как использовать Django с Apache и mod_wsgi for examples.

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

export LANG="en_US.UTF-8"

Представление формы¶

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

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

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