Часовые пояса

Обзор

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

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

Даже если ваш сайт доступен только в одном часовом поясе, всё равно рекомендуется хранить данные в UTC в вашей базе данных. Основная причина — летнее время (DST). Многие страны имеют систему DST, когда время переводится вперёд весной и назад осенью. Если вы работаете с местным временем, вам, вероятно, придётся столкнуться с ошибками дважды в год, когда происходят эти переходы. (Документация pytz более подробно описывает эти проблемы.) Это, вероятно, не важно для вашего блога, но это проблема, если вы пересчитываете плату для клиентов с ошибкой в один час дважды в год, каждый год. Решение этой проблемы — использование UTC в коде и использование местного времени только при взаимодействии с конечными пользователями.

Поддержка часовых поясов отключена по умолчанию. Чтобы её включить, задайте USE_TZ = True в файле настроек. Установка pytz настоятельно рекомендуется, но может быть необязательной в зависимости от вашего конкретного бэкенда базы данных, операционной системы и часового пояса. Если вы столкнётесь с ошибкой при запросе дат или времени, пожалуйста, попробуйте установить её перед сообщением об ошибке. Это так же просто, как:

$ pip install pytz

Если у вас возникли проблемы, начните с часто задаваемых вопросов по часовым поясам.

Концепции

Обычные и осознанные объекты datetime

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

Вы можете использовать is_aware() и is_naive() для определения того, осознанные или обычные объекты datetime.

При отключенной поддержке часовых поясов Django использует обычные объекты datetime в местном времени. Это просто и достаточно для многих случаев использования. В этом режиме для получения текущего времени вы бы написали:

import datetime

now = datetime.datetime.now()

При включённой поддержке часовых поясов (USE_TZ=True) Django использует осознанные объекты datetime с учётом часового пояса. Если ваш код создаёт объекты datetime, они также должны быть осознанными. В этом режиме пример выше становится:

from django.utils import timezone

now = timezone.now()

Интерпретация обычных объектов datetime

Когда USE_TZ True, Django всё ещё принимает обычные объекты datetime, чтобы сохранить обратную совместимость. Когда слой базы данных получает такой объект, он пытается сделать его осознанным, интерпретируя его в по умолчанию текущем часовом поясе и выводит предупреждение.

К сожалению, во время переходов на летнее время некоторые даты и время не существуют или являются неоднозначными. В таких ситуациях pytz выводит исключение. Другие реализации tzinfo, такие как местный часовой пояс, используемый в качестве резервного, когда pytz не установлен, могут выводить исключение или возвращать неточные результаты. Вот почему вы всегда должны создавать осознанные объекты datetime, когда включена поддержка часовых поясов.

На практике это редко проблема. Django предоставляет вам осознанные объекты datetime в моделях и формах, и чаще всего новые объекты datetime создаются из существующих с помощью арифметики timedelta. Единственный объект datetime, который часто создаётся в коде приложения, — это текущее время, и timezone.now() автоматически делает всё правильно.

По умолчанию текущий часовой пояс и текущий часовой пояс

По умолчанию текущий часовой пояс — это часовой пояс, определённый параметром TIME_ZONE.

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

Вы должны установить текущий часовой пояс на фактический часовой пояс конечного пользователя с помощью activate(). В противном случае используется часовой пояс по умолчанию.

Выбор текущего часового пояса

Текущий часовой пояс эквивалентен текущему локали для переводов. Однако нет эквивалента заголовка Accept-Language HTTP, который Django мог бы использовать для автоматического определения часового пояса пользователя. Вместо этого Django предоставляет функции выбора часового пояса. Используйте их, чтобы создать логику выбора часового пояса, которая имеет смысл для вас.

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

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

Добавьте следующий middleware в MIDDLEWARE:

import pytz

from django.utils import timezone
from django.utils.deprecation import MiddlewareMixin

class TimezoneMiddleware(MiddlewareMixin):
    def process_request(self, request):
        tzname = request.session.get('django_timezone')
        if tzname:
            timezone.activate(pytz.timezone(tzname))
        else:
            timezone.deactivate()

Создайте представление, которое может установить текущий часовой пояс:

from django.shortcuts import redirect, render

def set_timezone(request):
    if request.method == 'POST':
        request.session['django_timezone'] = request.POST['timezone']
        return redirect('/')
    else:
        return render(request, 'template.html', {'timezones': pytz.common_timezones})

Включите форму в template.html, которая будет POST в это представление:

{% load tz %}
{% get_current_timezone as TIME_ZONE %}
<form action="{% url 'set_timezone' %}" method="POST">
    {% csrf_token %}
    <label for="timezone">Time zone:</label>
    <select name="timezone">
        {% for tz in timezones %}
        <option value="{{ tz }}"{% if tz == TIME_ZONE %} selected="selected"{% endif %}>{{ tz }}</option>
        {% endfor %}
    </select>
    <input type="submit" value="Set" />
</form>

Формы с учётом часового пояса

При включённой поддержке часовых поясов Django интерпретирует даты и время, введённые в формах, в текущем часовом поясе и возвращает осознанные объекты datetime в cleaned_data.

Если текущий часовой пояс выводит исключение для дат и времени, которые не существуют или являются неоднозначными из-за переходов на летнее время (часовые пояса, предоставляемые pytz, делают это), такие даты и время будут отображаться как недопустимые значения.

Вывод времени с учётом часового пояса в шаблонах

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

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

Теги шаблонов

localtime

Включает или отключает преобразование объектов datetime с учетом часового пояса в текущий часовой пояс в содержащемся блоке.

Этот тег имеет точно такие же эффекты, как настройка USE_TZ с точки зрения движка шаблонов. Это позволяет более точно контролировать преобразования.

Чтобы активировать или деактивировать преобразование для блока шаблона, используйте:

{% load tz %}

{% localtime on %}
    {{ value }}
{% endlocaltime %}

{% localtime off %}
    {{ value }}
{% endlocaltime %}

timezone

Устанавливает или сбрасывает текущий часовой пояс в содержащемся блоке. Когда текущий часовой пояс сброшен, применяется по умолчанию.

{% load tz %}

{% timezone "Europe/Paris" %}
    Paris time: {{ value }}
{% endtimezone %}

{% timezone None %}
    Server time: {{ value }}
{% endtimezone %}

get_current_timezone

Вы можете получить имя текущего часового пояса, используя тег get_current_timezone:

{% get_current_timezone as TIME_ZONE %}

В качестве альтернативы вы можете активировать процессор контекста tz() и использовать переменную контекста TIME_ZONE.

Фильтры шаблонов

Эти фильтры принимают как объекты datetime с учетом часового пояса, так и без него. Для целей преобразования они предполагают, что объекты datetime без учета часового пояса находятся в часовом поясе по умолчанию. Они всегда возвращают объекты datetime с учетом часового пояса.

localtime

Принудительно преобразует отдельное значение в текущий часовой пояс.

Например:

{% load tz %}

{{ value|localtime }}

utc

Принудительно преобразует отдельное значение в UTC.

Например:

{% load tz %}

{{ value|utc }}

timezone

Принудительно преобразует отдельное значение в произвольный часовой пояс.

Аргумент должен быть подклассом tzinfo или именем часового пояса. Если это имя часового пояса, требуется pytz.

Например:

{% load tz %}

{{ value|timezone:"Europe/Paris" }}

Руководство по миграции часовых поясов

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

База данных

PostgreSQL

Бэкенд PostgreSQL хранит datetime в формате timestamp with time zone. На практике это означает, что он преобразует datetime из часового пояса подключения в UTC при сохранении и из UTC в часовой пояс подключения при извлечении.

Следовательно, если вы используете PostgreSQL, вы можете свободно переключаться между USE_TZ = False и USE_TZ = True. Часовой пояс подключения к базе данных будет установлен на TIME_ZONE или UTC соответственно, чтобы Django получал правильные datetime во всех случаях. Вам не нужно выполнять какие-либо преобразования данных.

Другие базы данных

Другие бэкэнды хранят datetime без информации о часовом поясе. Если вы переключаетесь с USE_TZ = False на USE_TZ = True, вы должны преобразовать свои данные из местного времени в UTC — что не является детерминированным, если у вас в местном времени есть летнее время.

Код

Первый шаг — добавить USE_TZ = True в файл настроек и установить pytz (если это возможно). На этом этапе все должно работать в основном. Если вы создаете объекты datetime без учета часового пояса в своём коде, Django делает их явными при необходимости.

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

Поэтому второй шаг — переработать свой код, где вы создаете объекты datetime, чтобы они учитывали часовой пояс. Это можно сделать поэтапно. django.utils.timezone определяет некоторые полезные вспомогательные функции для совместимости кода: now(), is_aware(), is_naive(), make_aware() и make_naive().

Наконец, чтобы помочь вам найти код, который требует обновления, Django выводит предупреждение, когда вы пытаетесь сохранить datetime без учета часового пояса в базе данных:

RuntimeWarning: DateTimeField ModelName.field_name received a naive
datetime (2012-01-01 00:00:00) while time zone support is active.

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

import warnings
warnings.filterwarnings(
    'error', r"DateTimeField .* received a naive datetime",
    RuntimeWarning, r'django\.db\.models\.fields',
)

Файлы fixture

При сериализации datetime с учетом часового пояса смещение UTC включается, как это:

"2011-09-01T13:20:30+03:00"

Для datetime без учета часового пояса, очевидно, этого нет:

"2011-09-01T13:20:30"

Для моделей с DateTimeField это различие делает невозможным создание файла fixture, который работает как с поддержкой часовых поясов, так и без неё.

Файлы fixture, сгенерированные с помощью USE_TZ = False, или до Django 1.4, используют формат «без учета часового пояса». Если ваш проект содержит такие файлы, после включения поддержки часовых поясов вы увидите RuntimeWarning при их загрузке. Чтобы избавиться от предупреждений, вы должны преобразовать свои файлы fixture в формат «с учетом часового пояса».

Вы можете перегенерировать файлы fixture с помощью loaddata и затем dumpdata. Или, если они достаточно малы, вы можете просто отредактировать их, чтобы добавить смещение UTC, которое соответствует вашей TIME_ZONE к каждой сериализованной datetime.

Вопросы и ответы по часовым поясам

Настройка

1. Мне не нужны несколько часовых поясов. Нужно ли мне включить поддержку часовых поясов?

   Да. Когда включена поддержка часовых поясов, Django использует более точную модель местного времени. Это защищает вас от тонких и невоспроизводимых ошибок в переходах на летнее время (DST).

   В этом отношении часовые пояса сравнимы с unicode в Python. Сначала это сложно. У вас возникают ошибки кодирования и декодирования. Затем вы узнаете правила. И некоторые проблемы исчезают — вы больше никогда не получите испорченный вывод, когда ваше приложение получает ввод, не являющийся ASCII.

   Когда вы включаете поддержку часовых поясов, у вас могут возникнуть некоторые ошибки, потому что вы используете неявные значения datetime, а Django ожидает явные значения datetime. Такие ошибки проявляются при запуске тестов, и их легко исправить. Вы быстро научитесь избегать недопустимых операций.

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

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

2. Я включил поддержку часовых поясов. Я в безопасности?

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

   Если ваше приложение подключается к другим системам (например, если оно обращается к веб-сервису), убедитесь, что значения datetime указаны должным образом. Чтобы безопасно передавать значения datetime, их представление должно включать смещение UTC или их значения должны быть в UTC (или и то, и другое!).

   Наконец, наша система календаря содержит интересные ловушки для компьютеров:

   >>> import datetime
   >>> def one_year_before(value):       # DON'T DO THAT!
   ...     return value.replace(year=value.year - 1)
   >>> one_year_before(datetime.datetime(2012, 3, 1, 10, 0))
   datetime.datetime(2011, 3, 1, 10, 0)
   >>> one_year_before(datetime.datetime(2012, 2, 29, 10, 0))
   Traceback (most recent call last):
   ...
   ValueError: day is out of range for month
   

   (Чтобы реализовать эту функцию, вы должны решить, является ли 2012-02-29 минус один год 2011-02-28 или 2011-03-01, что зависит от ваших бизнес-требований.)

3. Нужно ли мне установить pytz?

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

   Как только вы активируете поддержку часовых поясов, Django нуждается в определении часового пояса по умолчанию. Если pytz доступен, Django загружает это определение из базы данных часовых поясов. Это наиболее точное решение. В противном случае он полагается на разницу между местным временем и UTC, как сообщает операционная система, для вычисления преобразований. Это менее надёжно, особенно в моменты перехода на летнее время.

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

4. Как взаимодействовать с базой данных, которая хранит значения datetime в местном времени?

   Установите параметр TIME_ZONE в соответствующий часовой пояс для этой базы данных в настройке DATABASES.

   Это полезно для подключения к базе данных, которая не поддерживает часовые пояса и которой не управляет Django, когда USE_TZ установлено True.

Устранение неполадок

1. Моё приложение завершается сбоем с TypeError: can't compare offset-naive and offset-aware datetimes — в чём проблема?

   Давайте воспроизведём эту ошибку, сравнив неявное и явное значение datetime:

   >>> import datetime
   >>> from django.utils import timezone
   >>> naive = datetime.datetime.utcnow()
   >>> aware = timezone.now()
   >>> naive == aware
   Traceback (most recent call last):
   ...
   TypeError: can't compare offset-naive and offset-aware datetimes
   

   Если вы столкнулись с этой ошибкой, скорее всего, ваш код сравнивает эти два значения:

   • значение datetime, предоставленное Django (например, значение, полученное из формы или поля модели). Поскольку вы включили поддержку часовых поясов, оно явное.
   • значение datetime, сгенерированное вашим кодом, которое неявное (иначе вы бы этого не читали).

   В общем случае правильное решение — изменить ваш код, чтобы использовать явное значение datetime вместо неявного.

   Если вы пишете подключаемое приложение, которое должно работать независимо от значения USE_TZ, для вас может быть полезен django.utils.timezone.now(). Эта функция возвращает текущую дату и время в виде неявного значения datetime, когда USE_TZ = False и как явное значение datetime, когда USE_TZ = True. Вы можете добавлять или вычитать datetime.timedelta по мере необходимости.

2. Я вижу много RuntimeWarning: DateTimeField received a naive datetime (YYYY-MM-DD HH:MM:SS) while time zone support is active — это плохо?

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

   Тем временем, для обратной совместимости значение datetime рассматривается как значение в часовом поясе по умолчанию, что, как правило, ожидается.

3. now.date() — это вчера! (или завтра)

   Если вы всегда использовали неявные значения datetime, вы, вероятно, считаете, что можете преобразовать значение datetime в дату, вызвав его метод date(). Вы также считаете, что date очень похожа на datetime, за исключением того, что она менее точна.

   Ничего из этого неверно в среде с поддержкой часовых поясов:

   >>> import datetime
   >>> import pytz
   >>> paris_tz = pytz.timezone("Europe/Paris")
   >>> new_york_tz = pytz.timezone("America/New_York")
   >>> paris = paris_tz.localize(datetime.datetime(2012, 3, 3, 1, 30))
   # This is the correct way to convert between time zones with pytz.
   >>> new_york = new_york_tz.normalize(paris.astimezone(new_york_tz))
   >>> paris == new_york, paris.date() == new_york.date()
   (True, False)
   >>> paris - new_york, paris.date() - new_york.date()
   (datetime.timedelta(0), datetime.timedelta(1))
   >>> paris
   datetime.datetime(2012, 3, 3, 1, 30, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)
   >>> new_york
   datetime.datetime(2012, 3, 2, 19, 30, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)
   

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

   Значение datetime представляет собой точку во времени. Оно абсолютное: не зависит ни от чего. Напротив, дата — это понятие календаря. Это период времени, границы которого зависят от часового пояса, в котором рассматривается дата. Как вы можете видеть, эти два понятия фундаментально различаются, и преобразование значения datetime в дату — не детерминированная операция.

   Что это означает на практике?

   В целом следует избегать преобразования datetime в date. Например, вы можете использовать фильтр шаблонов date, чтобы отобразить только часть даты значения datetime. Этот фильтр преобразует значение datetime в текущий часовой пояс перед форматированием, гарантируя, что результаты отображаются корректно.

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

   >>> from django.utils import timezone
   >>> timezone.activate(pytz.timezone("Asia/Singapore"))
   # For this example, we just set the time zone to Singapore, but here's how
   # you would obtain the current time zone in the general case.
   >>> current_tz = timezone.get_current_timezone()
   # Again, this is the correct way to convert between time zones with pytz.
   >>> local = current_tz.normalize(paris.astimezone(current_tz))
   >>> local
   datetime.datetime(2012, 3, 3, 8, 30, tzinfo=<DstTzInfo 'Asia/Singapore' SGT+8:00:00 STD>)
   >>> local.date()
   datetime.date(2012, 3, 3)
   

4. У меня возникает ошибка “Are time zone definitions for your database and pytz installed?” pytz установлен, так что, наверное, проблема в моей базе данных?

   Если вы используете MySQL, см. раздел Определения часовых поясов в примечаниях к MySQL, чтобы узнать, как загрузить определения часовых поясов.

Использование

1. У меня есть строка "2012-02-21 10:28:45" и я знаю, что она в часовом поясе "Europe/Helsinki" . Как преобразовать её в явное значение datetime?

   Для этого и предназначен pytz.

   >>> from django.utils.dateparse import parse_datetime
   >>> naive = parse_datetime("2012-02-21 10:28:45")
   >>> import pytz
   >>> pytz.timezone("Europe/Helsinki").localize(naive, is_dst=None)
   datetime.datetime(2012, 2, 21, 10, 28, 45, tzinfo=<DstTzInfo 'Europe/Helsinki' EET+2:00:00 STD>)
   

   Обратите внимание, что localize — это расширение pytz для API tzinfo. Кроме того, вы можете захотеть поймать pytz.InvalidTimeError. В документации pytz содержатся дополнительные примеры. Вы должны изучить их, прежде чем пытаться манипулировать явными значениями datetime.

2. Как получить местное время в текущем часовом поясе?

   Ну, первый вопрос — вам это действительно нужно?

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

   Кроме того, Python знает, как сравнивать явные значения datetime, учитывая смещения UTC при необходимости. Значительно проще (и, возможно, быстрее) писать весь ваш код модели и представления в UTC. Таким образом, в большинстве случаев значения datetime в UTC, возвращаемые django.utils.timezone.now(), будут достаточными.

   Однако, для полноты картины, если вам действительно нужно местное время в текущем часовом поясе, вот как его получить:

   >>> from django.utils import timezone
   >>> timezone.localtime(timezone.now())
   datetime.datetime(2012, 3, 3, 20, 10, 53, 873365, tzinfo=<DstTzInfo 'Europe/Paris' CET+1:00:00 STD>)
   

   В этом примере pytz установлен, и текущий часовой пояс — "Europe/Paris".

3. Как увидеть все доступные часовые пояса?

   pytz предоставляет помощники, включая список текущих часовых поясов и список всех доступных часовых поясов — некоторые из которых представляют только исторический интерес.