pandas.to_datetime#

pandas.to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc=False, format=None, exact=, unit=None, infer_datetime_format=, origin='unix', cache=True)[источник]#

Преобразовать аргумент в datetime.

Эта функция преобразует скаляр, массивоподобный объект, Series или DataFrame/словареподобный объект в объект datetime pandas.

Параметры:
argint, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like

Объект для преобразования в datetime. Если DataFrame предоставлен, метод ожидает как минимум следующие столбцы: "year", "month", "day". Столбец "year" должен быть указан в 4-значном формате.

ошибки{‘ignore’, ‘raise’, ‘coerce’}, по умолчанию ‘raise’

  • Если 'raise', тогда некорректный разбор вызовет исключение.

  • Если 'coerce', тогда некорректный разбор будет установлен как NaT.

  • Если 'ignore', тогда некорректный разбор вернет входные данные.

dayfirstbool, по умолчанию False

Укажите порядок разбора даты, если arg является str или list-like. Если True, анализирует даты с днем первым, например "10/11/12" парсится как 2012-11-10.

Предупреждение

dayfirst=True не является строгим, но предпочтет парсинг с днем первым.

yearfirstbool, по умолчанию False

Укажите порядок разбора даты, если arg является строкой или похожим на список.

  • Если True разбирает даты с годом первым, например, "10/11/12" парсится как 2010-11-12.

  • Если оба dayfirst и yearfirst являются True, yearfirst предшествует (так же как dateutil).

Предупреждение

yearfirst=True не является строгим, но предпочтет разбор с годом первым.

utcbool, по умолчанию False

Управление парсингом, локализацией и преобразованием, связанными с часовыми поясами.

  • Если True, функция всегда возвращает локализованный в UTC с учетом часового пояса Timestamp, Series или DatetimeIndex. Для этого временные зоны без учета часового пояса локализованный как UTC, в то время как данные с учётом часового пояса преобразовано в UTC.

  • Если False (по умолчанию), входные данные не будут преобразованы в UTC. Входные данные без часового пояса останутся таковыми, а с часовым поясом сохранят свои смещения времени. Существуют ограничения для смешанных смещений (обычно, летнее время), см. Примеры раздел для подробностей.

Предупреждение

В будущей версии pandas разбор дат со смешанными часовыми поясами будет вызывать ошибку, если utc=True. Пожалуйста, укажите utc=True чтобы включить новое поведение и отключить это предупреждение. Чтобы создать Series со смещенными и object тип данных, пожалуйста, используйте apply и datetime.datetime.strptime.

См. также: общая документация pandas о преобразование часового пояса и локализация.

форматstr, по умолчанию None

Формат strftime для разбора времени, например. "%d/%m/%Y". См. документация strftime для получения дополнительной информации о вариантах, хотя обратите внимание, что "%f" будет парсить вплоть до наносекунд. Вы также можете передать:

  • “ISO8601”, для разбора любого ISO8601 строковое представление времени (не обязательно в точно таком же формате);

  • “mixed”, чтобы определить формат для каждого элемента отдельно. Это рискованно, и вам, вероятно, следует использовать это вместе с dayfirst.

Примечание

Если DataFrame передается, тогда формат не имеет эффекта.

точныйbool, по умолчанию True

Управление тем, как формат используется:

  • Если True, требуют точного формат совпадение.

  • Если False, разрешить формат для совпадения в любом месте целевой строки.

Нельзя использовать одновременно с format='ISO8601' или format='mixed'.

единицаstr, по умолчанию 'ns'

Единица измерения аргумента (D, s, ms, us, ns) обозначает единицу, которая является целым или вещественным числом. Это будет основано на точке отсчета. Например, с unit='ms' и origin='unix', это вычислило бы количество миллисекунд до начала эпохи Unix.

infer_datetime_formatbool, по умолчанию False

Если True и нет формат если задано, попытаться определить формат строк даты и времени на основе первого не-NaN элемента, и если его можно определить, переключиться на более быстрый метод их разбора. В некоторых случаях это может увеличить скорость разбора примерно в 5-10 раз.

Устарело с версии 2.0.0: Строгая версия этого аргумента теперь используется по умолчанию, передача его не имеет эффекта.

originскаляр, по умолчанию 'unix'

Определите опорную дату. Числовые значения будут интерпретированы как количество единиц (определяется единица) с этой даты отсчета.

  • Если 'unix' (или POSIX) время; точка отсчета установлена на 1970-01-01.

  • Если 'julian', единица измерения должна быть 'D', и начало установлено на начало Юлианского календаря. Юлианский день 0 присваивается дню, начинающемуся в полдень 1 января 4713 года до н.э.

  • Если преобразуемо в Timestamp (Timestamp, dt.datetime, np.datetimt64 или строку даты), начало устанавливается в Timestamp, определенный origin.

  • Если число с плавающей точкой или целое, начало — это разница (в единицах, определенных unit аргумент) относительно 1970-01-01.

cachebool, по умолчанию True

Если True, используйте кэш уникальных, преобразованных дат для применения преобразования даты и времени. Может обеспечить значительное ускорение при разборе повторяющихся строк дат, особенно с часовыми поясами. Кэш используется только при наличии не менее 50 значений. Наличие значений вне диапазона сделает кэш непригодным и может замедлить разбор.

Возвращает:
datetime

Если парсинг прошел успешно. Тип возвращаемого значения зависит от входных данных (типы в скобках соответствуют резервному варианту в случае неудачного парсинга часового пояса или временной метки вне диапазона):

Вызывает:
ParserError

При неудачном разборе даты из строки.

ValueError

Когда происходит другая ошибка преобразования даты и времени. Например, когда один из столбцов 'год', 'месяц', 'день' отсутствует в DataFrame, или когда Timezone-aware datetime.datetime находится в массиво-подобном объекте смешанных временных смещений, и utc=False.

Смотрите также

DataFrame.astype

Преобразует аргумент в указанный тип данных.

to_timedelta

Преобразовать аргумент в timedelta.

convert_dtypes

Преобразовать dtypes.

Примечания

Поддерживаются многие типы входных данных, и они приводят к разным типам выходных данных:

  • скаляры может быть int, float, str, объект datetime (из стандартной библиотеки datetime модуль или numpy). Они преобразуются в Timestamp когда возможно, иначе они преобразуются в datetime.datetime. Скалярные значения None/NaN/null преобразуются в NaT.

  • array-like может содержать int, float, str, объекты datetime. Они преобразуются в DatetimeIndex если возможно, иначе они преобразуются в Index с object GH 8486 datetime.datetime. None/NaN/null записи преобразуются в NaT в обоих случаях.

  • Series преобразуются в Series с datetime64 dtype, когда это возможно, в противном случае они преобразуются в Series с object GH 8486 datetime.datetime. Записи None/NaN/null преобразуются в NaT в обоих случаях.

  • DataFrame/словареподобный преобразуются в Series с datetime64 тип данных. Для каждой строки создается дата и время путем сборки различных столбцов фрейма данных. Ключи столбцов могут быть общими сокращениями такими как ['год', 'месяц', 'день', 'минута', 'секунда', 'мс', 'мкс', 'нс']) или множественными формами тех же.

Следующие причины ответственны за datetime.datetime объекты, возвращаемые (возможно, внутри Index или Series с object dtype) вместо правильного типа, обозначенного в pandas (Timestamp, DatetimeIndex или Series с datetime64 dtype):

  • когда любой входной элемент находится до Timestamp.min или после Timestamp.max, см. ограничения временных меток.

  • когда utc=False (по умолчанию) и входные данные являются массивоподобными или Series содержащий смешанные наивные/осведомленные даты-время, или осведомленные со смешанными смещениями времени. Обратите внимание, что это происходит в (довольно частой) ситуации, когда часовой пояс имеет политику перехода на летнее время. В этом случае вы можете захотеть использовать utc=True.

Примеры

Обработка различных форматов входных данных

Сборка даты и времени из нескольких столбцов DataFrame. Ключи могут быть общими сокращениями, такими как ['year', 'month', 'day', 'minute', 'second', 'ms', 'us', 'ns']) или множественными формами тех же

>>> df = pd.DataFrame({'year': [2015, 2016],
...                    'month': [2, 3],
...                    'day': [4, 5]})
>>> pd.to_datetime(df)
0   2015-02-04
1   2016-03-05
dtype: datetime64[ns]

Используя время Unix epoch

>>> pd.to_datetime(1490195805, unit='s')
Timestamp('2017-03-22 15:16:45')
>>> pd.to_datetime(1490195805433502912, unit='ns')
Timestamp('2017-03-22 15:16:45.433502912')

Предупреждение

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

Использование непоследовательного эпохального начала

>>> pd.to_datetime([1, 2, 3], unit='D',
...                origin=pd.Timestamp('1960-01-01'))
DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'],
              dtype='datetime64[ns]', freq=None)

Различия в поведении с strptime

"%f" будет парсить вплоть до наносекунд.

>>> pd.to_datetime('2018-10-26 12:00:00.0000000011',
...                format='%Y-%m-%d %H:%M:%S.%f')
Timestamp('2018-10-26 12:00:00.000000001')

Неконвертируемые даты/время

Передача errors='coerce' принудительно преобразует дату вне диапазона в NaT, в дополнение к принудительному преобразованию не-дат (или непарсируемых дат) в NaT.

>>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
NaT

Часовые пояса и временные смещения

Поведение по умолчанию (utc=False) выглядит следующим образом:

  • Входные данные без временной зоны преобразуются в данные без временной зоны DatetimeIndex:

>>> pd.to_datetime(['2018-10-26 12:00:00', '2018-10-26 13:00:15'])
DatetimeIndex(['2018-10-26 12:00:00', '2018-10-26 13:00:15'],
              dtype='datetime64[ns]', freq=None)

  • Входные данные с учётом часового пояса с постоянным временным смещением преобразуются в учитывающие часовой пояс DatetimeIndex:

>>> pd.to_datetime(['2018-10-26 12:00 -0500', '2018-10-26 13:00 -0500'])
DatetimeIndex(['2018-10-26 12:00:00-05:00', '2018-10-26 13:00:00-05:00'],
              dtype='datetime64[ns, UTC-05:00]', freq=None)

  • Однако входные данные с учетом часового пояса со смешанными временными смещениями (например, выданные из часового пояса с переходом на летнее время, такого как Европа/Париж) не успешно преобразовано в DatetimeIndex. Разбор дат и времени со смешанными часовыми поясами будет показывать предупреждение, если только utc=TrueАлексей Гёри utc=False будет показано предупреждение ниже и простая Index содержащий datetime.datetime объекты будут возвращены:

>>> pd.to_datetime(['2020-10-25 02:00 +0200',
...                 '2020-10-25 04:00 +0100'])  
FutureWarning: In a future version of pandas, parsing datetimes with mixed
time zones will raise an error unless `utc=True`. Please specify `utc=True`
to opt in to the new behaviour and silence this warning. To create a `Series`
with mixed offsets and `object` dtype, please use `apply` and
`datetime.datetime.strptime`.
Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00],
      dtype='object')

  • Смесь данных с часовыми поясами и без них также преобразуется в простой Index содержащий datetime.datetime объектах:

>>> from datetime import datetime
>>> pd.to_datetime(["2020-01-01 01:00:00-01:00",
...                 datetime(2020, 1, 1, 3, 0)])  
FutureWarning: In a future version of pandas, parsing datetimes with mixed
time zones will raise an error unless `utc=True`. Please specify `utc=True`
to opt in to the new behaviour and silence this warning. To create a `Series`
with mixed offsets and `object` dtype, please use `apply` and
`datetime.datetime.strptime`.
Index([2020-01-01 01:00:00-01:00, 2020-01-01 03:00:00], dtype='object')

Установка utc=True решает большинство вышеуказанных проблем:

  • Входные данные без временной зоны являются локализованный как UTC

>>> pd.to_datetime(['2018-10-26 12:00', '2018-10-26 13:00'], utc=True)
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 13:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)

  • Входные данные с учётом часового пояса являются преобразовано в UTC (вывод представляет тот же самый момент времени, но рассматриваемый с временным смещением UTC +00:00).

>>> pd.to_datetime(['2018-10-26 12:00 -0530', '2018-10-26 12:00 -0500'],
...                utc=True)
DatetimeIndex(['2018-10-26 17:30:00+00:00', '2018-10-26 17:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)

  • Входные данные могут содержать как строки, так и дату-время, указанные выше правила всё ещё применяются

>>> pd.to_datetime(['2018-10-26 12:00', datetime(2020, 1, 1, 18)], utc=True)
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2020-01-01 18:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)