Сообщить об ошибке.

Методы объекта ditetime.datetime().

В этом разделе рассмотрены методы экземпляра класса datetime.datetime с примерами.

Содержание:


dt.date():

Метод dt.date() возвращает объект datetime.date() с тем же годом, месяцем и днем.

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.date()
# datetime.date(2020, 5, 6)

dt.time():

Метод dt.time() возвращает объект datetime.time() с тем же часом, минутой, секундой, микросекундой, при этом параметр tzinfo будет равен None. Смотрите также метод datetime.timetz().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.time()
# datetime.time(9, 47, 7, 560533)

dt.timetz():

Метод dt.timetz() возвращает объект datetime.time() с такими же атрибутами часа, минуты, секунды, микросекунды и tzinfo. Смотрите также метод datetime.time().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.timetz()
# datetime.time(9, 47, 7, 560533)

# если указать аргумент смещение `tz`
# то timetz() будет присутствовать в объекте 
>>> delta = datetime.timedelta(hours=3)
>>> tz = datetime.timezone(delta)
>>> dt = datetime.datetime.now(tz=tz)
# datetime.time(9, 56, 14, 920298, \
# tzinfo=datetime.timezone(datetime.timedelta(0, 10800)))

dt.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0):

Метод dt.replace() возвращает новый объект datetime.datetime() с теми же атрибутами, за исключением тех атрибутов, которым даны новые значения в зависимости от того, какие ключевые аргументы указаны.

Обратите внимание, что можно указать tzinfo=None для создания "наивного" объекта datetime.datetime() из "осведомленного" без преобразования данных даты и времени.

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt
# datetime.datetime(2020, 5, 6, 9, 56, 14, 920298)
>>> dt.replace(year=2022, month=6, hour=15)
# datetime.datetime(2022, 6, 6, 15, 56, 14, 920298)

dt.astimezone(tz=None):

Метод dt.astimezone() возвращает новый объект datetime.datetime() с новым атрибутом tzinfo, скорректировав данные даты и времени таким образом, чтобы результатом было то же время UTC, но по местному времени tz.

  • Если указан аргумент tz, то он должен быть экземпляром подкласса datetime.tzinfo(), а его методы tzinfo.utcoffset() и tzinfo.dst() не должны возвращать None. Если self - "наивно", то предполагается, что оно представляет время в часовом поясе системы.
  • Если вызывается без аргументов или с tz=None, то системный часовой пояс местного времени принимается за целевой часовой пояс. Атрибут .tzinfo преобразованного экземпляра datetime.datetime() будет установлен на экземпляр datetime.timezone() с именем зоны и смещением, полученными из ОС.

    >>> import datetime
    >>> dt = datetime.datetime.now()
    >>> dt
    # datetime.datetime(2020, 5, 6, 9, 56, 14, 920298)
    >>> dt.astimezone()
    # datetime.datetime(2020, 5, 6, 9, 56, 14, 920298, \
    # tzinfo=datetime.timezone(datetime.timedelta(0, 10800), 'MSK'))
    
  • Если self.tzinfo равно tz, а self.astimezone(tz) равно self: настройка даты или времени не выполняется. В противном случае результатом является местное время в часовом поясе tz, представляющее то же время в формате UTC, что и в self: после astz = dt.astimezone(tz), astz - astz.utcoffset() будет иметь те же данные о дате и времени, что и dt - dt.utcoffset().

  • Если вы просто хотите прикрепить объект часового пояса tz к datetime.datetime() без настройки даты и времени, используйте dt.replace(tzinfo=tz).

  • Если вы просто хотите удалить объект часового пояса из "осведомленного" datetime.datetime() без преобразования даты и времени, используйте dt.replace(tzinfo=None).

Обратите внимание, что метод tzinfo.fromutc() по умолчанию может быть переопределен в подклассе tzinfo, чтобы повлиять на результат, возвращаемый методом dt.astimezone(). действует так, что бы игнорировать ошибки datetime.astimezone():

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Конвертируйте self в UTC и прикрепите
    # новый объект часового пояса
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Конвертировать из UTC в местное время tz.
    return tz.fromutc(utc)

dt.utcoffset():

Если tzinfo=None, то метод dt.utcoffset() возвращает None, иначе возвращает self.tzinfo.utcoffset(self) или вызывает исключение, если последний не возвращает None или объект timedelta со значением менее одного дня.

>>> import datetime
>>> dt = datetime.datetime.now()
>>> print(dt.utcoffset())
# None
>>> new_dt = dt.astimezone()
>>> new_dt.utcoffset()
# datetime.timedelta(0, 10800)

dt.dst():

Если tzinfo=None, то метод dt.dst() возвращает None, иначе возвращает self.tzinfo.dst(self) или вызывает исключение, если последний не возвращает None или объект timedelta со значением менее одного дня.

>>> import datetime
>>> dt = datetime.datetime.now()
>>> print(dt.dst())
# None
>>> new_dt = dt.astimezone()
>>> print(new_dt.dst())
# None

dt.tzname():

Если tzinfo=None, то метод dt.tzname() возвращает None, иначе возвращает self.tzinfo.tzname(self) или вызывает исключение, если последний не возвращает None или или строковый объект.

>>> import datetime
>>> dt = datetime.datetime.now()
>>> print(dt.tzname())
# None
>>> new_dt = dt.astimezone()
>>> new_dt.tzname()
# 'MSK'

dt.timetuple():

Метод dt.timetuple() возвращает кортеж структуры времени time.struct_time, например такой же как возвращает time.localtime().

Метод dt.timetuple() эквивалентен:

time.struct_time((dt.year, dt.month, dt.day,
                  dt.hour, dt.minute, dt.second,
                  dt.weekday(), yday, dst))

где yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 номер дня в текущем году, начиная с 1 для 1 января. Флаг tm_isdst кортежа структуры устанавливается в соответствии с методом dt.dst():

  • tm_isdst имеет значение -1, то dt.dst() возвращает None;
  • tm_isdst имеет значение 1, то dt.dst() возвращает ненулевое значение;
  • tm_isdst имеет значение 0.
>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.timetuple()
# time.struct_time(tm_year=2020, tm_mon=5, tm_mday=6, \
#                  tm_hour=9, tm_min=56, tm_sec=14, \
#                  tm_wday=2, tm_yday=127, tm_isdst=-1)
dt.timetuple().tm_isdst
# -1

dt.utctimetuple():

Если экземпляр dt - "наивен", то метод dt.utctimetuple() возвратит же самое, что и dt.timetuple(), за исключением того, что элемент структуры tm_isdst принудительно устанавливается в 0 независимо от того, что возвращает dt.dst(). DST никогда не действует в течение времени UTC.

Если dt - "осведомленный", то dt нормализуется к времени UTC, вычитая dt.utcoffset() и возвращается кортеж time.struct_time для нормализованного времени. Значение tm_isdst=0. Обратите внимание, что ошибка OverflowError может быть вызвана, если атрибут даты и времени dt.year равняется MINYEAR или MAXYEAR, а корректировки UTC превышают границу года.

Предупреждение. Поскольку "наивные" объекты datetime.datetime() обрабатываются многими методами как локальное время, то предпочтительно использовать "осведомленные" объекты datetime.datetime() для представления времени в UTC. В результате использование конструктора datetime.datetime.utcfromtimetuple() может привести к ошибочным результатам. Если у вас есть "наивный" объект datetime.datetime() представляющий UTC, то используйте dt.replace(tzinfo=timezone.utc), чтобы сообщить, в какой момент вы можете использовать dt.timetuple().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.timetuple()
# time.struct_time(tm_year=2020, tm_mon=5, tm_mday=6, \
#                  tm_hour=9, tm_min=56, tm_sec=14, \
#                  tm_wday=2, tm_yday=127, tm_isdst=0)
>>> dt.timetuple().tm_isdst
# 0

dt.toordinal():

Метод dt.toordinal() возвращает пролептический григорианский порядковый номер даты. Так же, как self.date().toordinal().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.toordinal()
# 737551

dt.timestamp():

Метод dt.timestamp() возвращает метку времени POSIX, соответствующую экземпляру datetime.datetime(). Возвращаемое значение - это число с плавающей точкой, аналогичное тому, которое возвращает time.time().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.timestamp()
1588748174.920298

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

Для "осведомленных" экземпляров datetime.datetime() возвращаемое значение вычисляется как:

>>> import datetime
>>> dt = datetime.datetime.now()
(dt - datetime.datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

Примечание. Нет способа получить метку времени POSIX непосредственно из простого экземпляра datetime.datetime(), представляющего время UTC. Если ваше приложение использует это соглашение и системный часовой пояс не установлен на UTC, вы можете получитьвременную метку POSIX, указав tzinfo=timezone.utc:

>>> import datetime
>>> dt = datetime.datetime.now()
>>> timestamp = dt.replace(tzinfo=timezone.utc).timestamp()
# или путем вычисления метки времени напрямую:
>>> timestamp = (dt - datetime.datetime(1970, 1, 1)) / timedelta(seconds=1)

dt.weekday():

Метод dt.weekday() возвращает день недели в виде целого числа, где понедельник = 0, а воскресенье = 6. То же, что self.date().weekday().

Смотрите также метод dt.isoweekday().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.weekday()
2

dt.isoweekday():

Метод dt.isoweekday() возвращает день недели в виде целого числа, где понедельник = 1, а воскресенье = 6. То же, что self.date().isoweekday().

Смотрите также методы dt.weekday() и dt.isocalendar().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.isoweekday()
# 3

dt.isocalendar():

Метод dt.isocalendar() возвращает именованный кортеж с тремя компонентами: год year, неделя week и день недели weekday. Так же, как self.date().isocalendar().

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.isocalendar()
# datetime.IsoCalendarDate(year=2020, week=19, weekday=3)

Изменено в Python 3.9: результат изменился с простого кортежа на именованный кортеж.

dt.isoformat(sep='T', timespec='auto'):

Метод dt.isoformat() возвращает строку, представляющую дату и время в формате ISO 8601:

  • YYYY-MM-DDTHH:MM:SS.ffffff, если микросекунда не равна 0
  • YYYY-MM-DDTHH:MM:SS, если микросекунда равна 0

Если dt.utcoffset() не возвращает None, добавляется строка, дающая смещение UTC:

  • YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], если микросекунда не равна 0
  • YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], если микросекунда равна 0

Examples:

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.isoformat()
# '2020-05-06T09:56:14.920298'
>>> tz = datetime.timezone.utc
>>> dt_utc = datetime.datetime.now(tz=tz)
>>> dt_utc.isoformat()
# '2020-05-06T06:56:14.920298+00:00'
>>> dt_local = dt.astimezone()
>>> dt_local.isoformat()
'2020-05-06T09:56:14.920298+03:00'

Необязательный аргумент sep - по умолчанию 'T', представляет собой односимвольный разделитель, помещенный между датой и временем.

import datetime

class TZ(datetime.tzinfo):
    """Часовой пояс с произвольным постоянным смещением -06: 39."""
    def utcoffset(self, dt):
        return datetime.timedelta(hours=-6, minutes=-39)

>>> datetime.datetime(2022, 12, 25, tzinfo=TZ()).isoformat(' ')
# '2022-12-25 00:00:00-06:39'
>>> datetime.datetime(2022, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
# '2022-11-27T00:00:00.000100-06:39'

Необязательный аргумент timespec указывает количество дополнительных компонентов времени для включения, по умолчанию "auto".

Это может быть одно из следующих:

  • 'auto': то же, что и 'seconds', если dt.microseconds равна 0, в противном случае как 'milliseconds'.
  • 'hours': включает час в двузначном формате HH.
  • 'minutes': включает час и минуты в формате HH:MM.
  • 'seconds': включает час , минуты и секунды в формате HH:MM:SS.
  • 'milliseconds': включает полный вариант вывода, но усекает вторую дробную часть до миллисекунд - HH:MM:SS.sss.
  • 'microseconds': включает полный вариант вывода - HH:MM:SS.ffffff.

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

Будет вызвано исключение ValueError, если аргумент timespec будет недопустимым.

>>> import datetime
>>> datetime.datetime.now().isoformat(timespec='minutes')   
# '2022-12-25T00:00'
>>> dt = datetime.datetime(2023, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
# '2023-01-01T12:30:59.000000'

dt.__str__():

Для экземпляра dt справедливо утверждение: str(dt) эквивалентно вызову dt.isoformat(sep=' ').

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.__str__()
# '2021-05-06 09:56:14.920298'
>>> str(dt)
# '2021-05-06 09:56:14.920298'

dt.ctime():

Метод dt.ctime() возвращает строку, представляющую дату и время:

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.ctime()
# 'Wed May  6 09:56:14 2021'

>>> import time
>>> time.ctime(time.mktime(dt.timetuple()))
# 'Wed May  6 09:56:14 2021'

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

Вызов метода dt.ctime() эквивалентен:

>>> import datetime, time
>>> dt = datetime.datetime.now()
>>> time.ctime(time.mktime(dt.timetuple()))
'Wed May  6 09:56:14 2021'

dt.strftime(format):

Метод dt.strftime() возвращает строку, представляющую дату и время, управляемую явной строкой формата.

Полный список директив форматирования смотрите в разделе "Поведение методов strftime() и strptime() модуля datetime".

>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.strftime('%H:%M - %m.%d.%Y года')
# '09:56 - 05.06.2020 года'
>>> dt.strftime('%H часов %M минут %m.%d.%Y года')
# '09 часов 56 минут 05.06.2020 года'
>>> dt.strftime('%m/%d/%y')
# '05/06/20'
>>> dt.strftime('%Y-%m-%d')
# '2020-05-06'