Python: полный мануал с примерами и справочником функций

Глава 15 · средний

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

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

Сначала решите, что обозначает значение

Дата сдачи отчёта, местное время открытия и момент получения сообщения — разные данные. date содержит календарную дату, time — время суток, datetime — их сочетание, а timedelta описывает длительность. Не добавляйте часовой пояс к дате рождения только потому, что библиотека умеет работать со временем. Для события, происходящего одновременно для всех участников, напротив, нужен момент с понятным часовым поясом, иначе одна строка может обозначать разные реальные события.

from datetime import date, timedelta
import calendar

start = date.fromisoformat("2024-02-28")
print((start + timedelta(days=1)).isoformat())
print("Дней в феврале:", calendar.monthrange(2024, 2)[1])
try:
    date.fromisoformat("2025-02-29")
except ValueError:
    print("Такой даты нет")

2024-02-29
Дней в феврале: 29
Такой даты нет

Календарную дату удобнее разбирать специальным методом, чем вручную делить строку и отдельно проверять длину каждого месяца. fromisoformat проверяет существование даты, однако ваша программа всё равно задаёт допустимый диапазон и смысл. Дата в будущем синтаксически верна, но может не подходить для отчёта о завершённом событии. В интерфейсе показывайте человеку понятную ошибку и сохранённое введённое значение; при обмене данными документируйте ожидаемый ISO-формат, не зависящий от локали компьютера.

Naive и aware: задан ли смысл часового пояса

Объект datetime без информации о смещении называют naive. Сам по себе он не означает ни UTC, ни время вашего города. Aware-объект содержит подходящий tzinfo и может обозначать определённый момент. Для текущего UTC используйте datetime.now(timezone.utc); не сохраняйте его в строку, предварительно отбрасывая пояс. В новом коде не требуется utcnow(), который возвращает naive-объект и оставляет читателю необходимость угадывать договорённость. Сравнение порядка между naive и aware вызывает ошибку.

replace(tzinfo=...) назначает или меняет метку пояса, не пересчитывая показания часов. astimezone(...) переводит уже известный момент и меняет местные показания. Это различие важнее названия метода. Если исходник содержит «09:00 по Москве», сначала нужен корректный московский пояс. Если он содержит «09:00 UTC», метка +03:00 без преобразования сдвинет смысл события на три часа. Не исправляйте неизвестные входные данные простым добавлением UTC: сначала определите их контракт.

Один момент может иметь разные местные показания

В следующем самостоятельном примере используется фиксированное смещение +03:00, которое подходит для московского времени в выбранную учебную дату 12 октября 2026 года. Оно не заменяет историю и будущие правила региона. Обе записи обозначают один момент и сравниваются как равные. Разность между событием и более поздним событием вычисляется после приведения к UTC: такой расчёт показывает прошедшее реальное время, не смешивая его с изменением местных часов.

from datetime import datetime, timedelta, timezone

utc = datetime.fromisoformat("2026-10-12T09:00:00+00:00")
fixed_moscow = timezone(timedelta(hours=3))
local = utc.astimezone(fixed_moscow)
later = datetime.fromisoformat("2026-10-12T13:30:00+03:00")
print(local.isoformat())
print("Один момент:", local == utc)
elapsed = later.astimezone(timezone.utc) - utc
print("Минут:", int(elapsed.total_seconds() / 60))

2026-10-12T12:00:00+03:00
Один момент: True
Минут: 90

Для региона используйте правила IANA

ZoneInfo("Europe/Moscow") представляет правила именованного региона, а не одно постоянное смещение. Модуль zoneinfo входит в стандартную библиотеку с Python 3.9, но сами данные IANA поступают из системы либо установленного пакета tzdata. В Windows подходящей системной базы может не быть, и тогда возникает ZoneInfoNotFoundError. Это проблема отсутствующих данных, а не неверного синтаксиса вашего расчёта. Версию базы важно учитывать для календаря и расписания, потому что правила определяются внешними решениями.

Следующий фрагмент зависит от наличия базы IANA, поэтому это инструкция для настроенного окружения, а не один из самодостаточных проверяемых скриптов главы. Установка tzdata выполняется отдельно в нужном окружении; библиотека не скачивает её сама. Если программа обязана работать без внешних данных, используйте документированное фиксированное смещение только для тех задач, где его ограничения действительно подходят. Не подменяйте отсутствующий региональный пояс молча произвольным смещением.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

moment = datetime(2026, 10, 12, 9, tzinfo=timezone.utc)
print(moment.astimezone(ZoneInfo("Europe/Moscow")).isoformat())

python -m pip install tzdata

Повторяющиеся часы, fold и пропущенное время

При переходе с летнего времени местные часы могут пройти один час дважды; при обратном переходе часть местных показаний вообще не существует. Атрибут fold различает два повторившихся времени: обычно 0 для первого и 1 для второго. Одного значения «02:30» недостаточно. Если вы принимаете местное расписание от человека, задайте правило выбора или попросите уточнить смещение. Простое конструирование datetime с ZoneInfo не является универсальной проверкой существования местного времени при переходе.

Для реальной длительности переводите границы в UTC перед вычитанием. При одинаковом объекте tzinfo арифметика datetime использует локальные показания и может не учитывать смену смещения так, как ожидается от секундомера. Для требования «каждый день в 09:00 по местному времени» нужен календарный расчёт с правилами пояса, а не прибавление 86400 секунд к прежнему UTC-моменту. Храните выбранный регион вместе с расписанием; для уже произошедшего события удобно хранить UTC и исходный контекст отображения.

Строка, timestamp и представление для человека

isoformat и fromisoformat полезны для машинного обмена. strftime и strptime работают с заданным шаблоном; названия месяцев могут зависеть от локали. Для timestamp важно знать единицу: секунды и миллисекунды различаются в тысячу раз. Чтение через datetime.fromtimestamp(value, timezone.utc) явно задаёт UTC; без аргумента пояса результат зависит от местной конфигурации. Для точного финансового или научного времени отдельно учитывают требования к точности и определение шкалы времени.

from datetime import datetime, timezone

moment = datetime.fromtimestamp(0, timezone.utc)
print(moment.isoformat())
label = datetime.strptime("12.10.2026", "%d.%m.%Y").date()
print(label.isoformat())

1970-01-01T00:00:00+00:00
2026-10-12

Измеряйте длительность монотонными часами

Календарные часы нужны для отметки события, но могут корректироваться системой. Для таймаута используйте time.monotonic, а для измерения выполнения — perf_counter или его вариант в наносекундах. Сравнивайте два показания одних и тех же часов; их абсолютное значение не предназначено для записи даты. В проверяемом примере выводится условие о неотрицательной длительности, а не нестабильное число секунд. Одно измерение не доказывает преимущество алгоритма: повторите опыт на осмысленных входных данных и учтите накладные расходы.

from time import perf_counter, monotonic

started = perf_counter()
result = sum(range(1000))
elapsed = perf_counter() - started
deadline = monotonic() + 5
print("Сумма:", result)
print("Длительность неотрицательна:", elapsed >= 0)
print("Дедлайн ещё впереди:", deadline > monotonic())

Сумма: 499500
Длительность неотрицательна: True
Дедлайн ещё впереди: True

Практика: не принимайте время без пояса

Напишите функцию, которая принимает ISO-время, требует явное смещение и возвращает запись UTC. Проверьте корректную строку +03:00, naive-строку и ошибочный текст. Ошибки должны объяснять смысл отказа; для примера их ловят и печатают. Такая граница особенно полезна при импорте событий: неизвестное местное время не попадёт в базу под видом точно известного момента.

from datetime import datetime, timezone

def normalize(text):
    try:
        value = datetime.fromisoformat(text)
    except ValueError as error:
        raise ValueError("Неверная ISO-строка") from error
    if value.utcoffset() is None:
        raise ValueError("Укажите часовой пояс")
    return value.astimezone(timezone.utc).isoformat()

for text in ["2026-10-12T12:00:00+03:00", "2026-10-12T12:00:00", "ошибка"]:
    try:
        print(normalize(text))
    except ValueError as error:
        print(error)

2026-10-12T09:00:00+00:00
Укажите часовой пояс
Неверная ISO-строка