Класс timedelta() модуля datetime

Интервал времени timedelta, поддерживаемые операции.

Синтаксис:

import datetime

delta = datetime.timedelta(days=0, 
                           seconds=0, 
                           microseconds=0, 
                           milliseconds=0, 
                           minutes=0, 
                           hours=0, 
                           weeks=0)

Параметры:

Все аргументы являются необязательными и по умолчанию равны 0. Аргументы могут быть целыми числами или числами с плавающей запятой и могут быть положительными или отрицательными.

• days=0 - день,

• seconds=0 - секунды,

• microseconds=0 - микросекунды,

• milliseconds=0 - миллисекунды,

• minutes=0 - минуты,

• hours=0 - часы,

• weeks=0 - недели.

Возвращаемое значение:

• продолжительность datetime.timedelta.

Описание:

Класс timedelta() модуля datetime представляет собой продолжительность, разницу между двумя датами или временем.

Экземпляр datetime.timedelta продолжительность хранит как сочетание days, seconds и microseconds, а остальные переданные в конструктор аргументы конвертируются в эти единицы:

• millisecond преобразуется в 1000 microseconds.

• minute преобразуется в 60 seconds.

• hour преобразуется в 3600 seconds.

• week преобразуется в 7 days.

days, seconds и microseconds затем нормализуются так, чтобы представление было уникальным:

• 0 <= microseconds < 1000000

• 0 <= seconds < 3600*24 (количество секунд в одном дне)

• -999999999 <= days <= 999999999

В следующем примере показано, как любые аргументы, кроме days, seconds и microseconds объединяются и нормализуются в эти три результирующих атрибута:

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )

# Остались только дни, секунды и микросекунды
>>> delta
# datetime.timedelta(days=64, seconds=29156, microseconds=10)
>>> delta.days
# 64
>>> delta.seconds
# 29156
>>> delta.microseconds
# 10
>>> delta.total_seconds()
# 5558756.00001

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

Если нормализованное значение дней находится за пределами диапазона -999999999 <= days <= 999999999, то появляется исключение OverflowError.

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

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
# (-1, 86399, 999999)

Продолжительность timedelta имеет 1 метод:

delta.total_seconds():

Метод timedelta.total_seconds() возвращает общее количество секунд, содержащихся в продолжительности timedelta. Эквивалент td/timedelta(seconds=1).

Для интервальных единиц, отличных от секунд, используйте форму деления напрямую, например td/timedelta(microseconds=1).

Обратите внимание, что для очень больших временных интервалов более 270 лет на большинстве платформ этот метод теряет микросекундную точность.

Поддерживаемые операции timedelta:

Операция	Результат	Замечания
t1 = t2 + t3	Сумма t2 и t3. Впоследствии t1-t2 == t3 и t1-t3 == t2 верны.	(1)
t1 = t2 - t3	Разница t2 и t3. Впоследствии t1 == t2 - t3 и t2 == t1 + t3 верны.	(1)(6)
t1 = t2 * i t1 = i * t2	Дельта умножается на целое число 'int'. Впоследствии t1 // i == t2 верно, если i! = 0.
	В общем случае t1 * i == t1 * (i-1) + t1 верно.	(1)
t1 = t2 * f t1 = f * t2	Дельта умножается на 'float'. Результат округляется до ближайшего кратного 'timedelta.resolution' с использованием округления от половины до четности.
f = t2 / t3	Деление общей длительности 't2' на интервал 't3'. Возвращает объект 'float'.	(3)
t1 = t2 / f t1 = t2 / i	Дельта делится на 'float' или 'Int'. Результат округляется до ближайшего кратного 'timedelta.resolution' с использованием округления от половины до четности.
t1 = t2 // i t1 = t2 // t3	Вычисляется, остаток (если есть) выбрасывается. Во втором случае возвращается целое число.	(3)
t1 = t2 % t3	Остаток вычисляется как объект 'timedelta'.	(3)
q, r = divmod(t1, t2)	Вычисляет частное и остаток: q = t1 // t2 и r = t1% t2. 'q' представляет собой целое число, а 'r' представляет собой объект 'datetime.timedelta'.	(3)
+t1	Возвращает объект 'datetime.timedelta' с тем же значением.	(2)
-t1	Эквивалентно datetime.timedelta(-t1.days, -t1.seconds, -t1.microseconds) и так же t1 * -1.	(1) (4)
abs(t)	Эквивалентно '+t', когда t.days >= 0, и '-t', когда t.days < 0.	(2)
str(t)	Возвращает строку в форме [D day [s],] [H] H: MM: SS [.UUUUUU], где D отрицательно для отрицательного 't'.	(5)
repr(t)	Возвращает строковое представление объекта 'datetime.timedelta' в виде вызова конструктора со значениями канонического атрибута.

Замечания:

1. Это точно, но может быть переполнение.

2. Это точно и не может быть переполнения.

3. Деление на 0 поднимает исключение ZeroDivisionError.
4. -timedelta.max не может быть представлен как объект datetime.timedelta.

5. Строковые представления объектов datetime.timedelta нормализуются аналогично их внутреннему представлению. Это приводит к несколько необычным результатам для отрицательных timedeltas.Например:

   >>> datetime.timedelta(days=-1, seconds=68400)
   >>> print(_)
   # -1 day, 19:00:00

6. Выражение t2 - t3 всегда будет равно выражению t2 + (-t3), кроме случаев, когда t3 равно timedelta.max. В этом случае первое даст результат, а второе вызовет переполнение.

В дополнение к операциям, перечисленным выше, объекты datetime.timedelta поддерживают определенные дополнения и вычитания с объектами date и datetime. Смотрите "Частые приемы работы c datetime.timedelta".

Поддерживаются сравнения объектов datetime.timedelta с некоторыми оговорками.

Сравнения == или != всегда возвращают bool, независимо от типа сравниваемого объекта:

>>> from datetime import timedelta
>>> delta1 = timedelta(seconds=57)
>>> delta2 = timedelta(hours=25, seconds=2)
>>> delta2 != delta1
# True
>>> delta2 == 5
# False

Для всех других сравнений, таких < как > и когда объект timedelta сравнивается с объектом другого типа, вызывается исключение TypeError:

>>> delta2 > delta1
# True
>>> delta2 > 5
# Traceback (most recent call last):
#   File "<stdin>", line 1, in <module>
# TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'

В булевых контекстах объект timedelta считается истинным тогда и только тогда, когда он не равен datetime.timedelta(0).

Дополнительный пример нормализации:

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)

# Компоненты 'another_year' составляют ровно 365 дней
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
# True
>>> year.total_seconds()
# 31536000.0