Объекты относительного и абсолютного времени¶

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

Вы можете использовать функции is_aware() и is_naive() для определения типа объекта.

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

import datetime

now = datetime.datetime.now()

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

from django.utils import timezone

now = timezone.now()

Интерпретация объектов относительного времени¶

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

Unfortunately, during DST transitions, some datetimes don’t exist or are ambiguous. In such situations, pytz raises an exception. That’s why you should always create aware datetime objects when time zone support is enabled.

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

Стандартный часовой пояс и текущий часовой пояс¶

Стандартный часовой пояс — это часовой пояс, определённый параметром конфигурации TIME_ZONE.

Текущая часовой пояс — часовой пояс для которого отображается страница сайта.

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

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

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

Most websites that care about time zones ask users in which time zone they live and store this information in the user’s profile. For anonymous users, they use the time zone of their primary audience or UTC. pytz provides helpers, like a list of time zones per country, that you can use to pre-select the most likely choices.

Ниже приведён пример сохранения текущего часового пояса в сессии. (Пример не использует обработку ошибок для простоты.)

Добавьте следующую строку в MIDDLEWARE_CLASSES:

import pytz

from django.utils import timezone

class TimezoneMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        tzname = request.session.get('django_timezone')
        if tzname:
            timezone.activate(pytz.timezone(tzname))
        else:
            timezone.deactivate()
        return self.get_response(request)

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

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{% endif %}>{{ tz }}</option>
        {% endfor %}
    </select>
    <input type="submit" value="Set">
</form>

Шаблонные теги¶

{% load tz %}

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

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

{% load tz %}

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

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

{% get_current_timezone as TIME_ZONE %}

Шаблонные фильтры¶

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

{% load tz %}

{{ value|localtime }}

{% load tz %}

{{ value|utc }}

{% load tz %}

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

База данных¶

Код¶

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

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

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

Finally, in order to help you locate code that needs upgrading, Django raises a warning when you attempt to save a naive datetime to the database:

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',
)

Фикстуры¶

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

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

Для значений относительного времени такого не происходит:

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

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

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

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

Настройка¶

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

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

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

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

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

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

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

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

   Finally, our calendar system contains interesting edge cases. For example, you can’t always subtract one year directly from a given date:

   >>> import datetime
   >>> def one_year_before(value):  # Wrong example.
   ...     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. Как работать с базами данных, которые хранят время без часового пояса?

   Укажите в опции TIME_ZONE настройки DATABASES правильный часовой пояс для базы данных.

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

Решение проблем¶

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

   Let’s reproduce this error by comparing a naive and an aware datetime:

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

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

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

   • относительное значение времени, созданное вашим кодом (иначе бы вы это не читали).

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

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

2. Я вижу множество RuntimeWarning: DateTimeField received a naive datetime (YYYY-MM-DD HH:MM:SS) при включенной поддержке часовых поясов – это плохо?

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

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

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

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

   None of this is true in a time zone aware environment:

   >>> 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 в date. Например, вы можете использовать шаблонный фильтр date для отображения только даты. Этот фильтр учтёт текущий часовой пояс при преобразовании значения даты/времени и обеспечит правильное отображение результата.

   If you really need to do the conversion yourself, you must ensure the datetime is converted to the appropriate time zone first. Usually, this will be the current timezone:

   >>> from django.utils import timezone
   >>> timezone.activate(pytz.timezone("Asia/Singapore"))
   # For this example, we 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. Я получил ошибку «Установлены ли pytz и поддержка часовых поясов в базе данных?» pytz установлен, я предполагаю, что проблема в базе данных?

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

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

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

   This is exactly what pytz is for.

   >>> 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>)
   

   Note that localize is a pytz extension to the tzinfo API. Also, you may want to catch pytz.InvalidTimeError. The documentation of pytz contains more examples. You should review it before attempting to manipulate aware datetimes.

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

   Хорошо, первым вопросом будет: вам действительно это надо?

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

   Более того, Python знает, как сравнивать значения абсолютного времени, принимая во внимание смещение UTC когда это требуется. Так гораздо проще (и значительно быстрее) создавать код для всех ваших моделей и представлений. Таким образом, в большинстве случаев времени в UTC, возвращённое функцией django.utils.timezone.now(), будет достаточно.

   For the sake of completeness, though, if you really want the local time in the current time zone, here’s how you can obtain it:

   >>> 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 установлена и параметр TIME_ZONE настроен на "Europe/Paris".

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

   pytz provides helpers, including a list of current time zones and a list of all available time zones – some of which are only of historical interest. zoneinfo also provides similar functionality via zoneinfo.available_timezones().