pandas.to_datetime

pandas.to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc=False, format=None, exact=<no_default>, unit=None, infer_datetime_format=<no_default>, origin='unix', cache=True)[source]

Преобразует аргумент в дату и время.

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

Параметры:

arg:int, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like

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

errors:{‘ignore’, ‘raise’, ‘coerce’}, default ‘raise’

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

• Если 'coerce', результатом ошибочного разбора будет NaT.

• Если 'ignore', при ошибке разбора будет возвращён входной объект.

dayfirst:bool, default False

Задаёт порядок разбора даты, если arg является строкой или массивоподобным объектом. Если True, даты разбираются, начиная с дня; например, "10/11/12" разбирается как 2012-11-10.

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

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

yearfirst:bool, default False

Задаёт порядок разбора даты, если arg является строкой или массивоподобным объектом.

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

• Если и dayfirst, и yearfirst имеют значение True, приоритет отдаётся yearfirst (как и в случае с dateutil).

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

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

utc:bool, default False

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

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

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

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

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

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

format:str, default None

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

• «ISO8601» для разбора любой строки времени в формате ISO8601 (не обязательно точно в одном и том же формате);

• «mixed» для определения формата каждого элемента отдельно. Это рискованный вариант; вероятно, его следует использовать вместе с dayfirst.

Примечание

Если передан объект DataFrame, параметр format не влияет на результат.

exact:bool, default True

Управляет использованием параметра format:

• Если True, формат должен точно совпадать с format.

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

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

unit:str, default ‘ns’

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

infer_datetime_format:bool, default False

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

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

origin:scalar, default ‘unix’

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

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

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

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

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

cache:bool, default True

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

Возвращает:

datetime

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

• скаляр: Timestamp (или datetime.datetime)

• массивоподобный объект: DatetimeIndex (или Series с типом данных object, содержащий datetime.datetime)

• Series: Series с типом данных datetime64 (или Series с типом данных object, содержащий datetime.datetime)

• DataFrame: Series с типом данных datetime64 (или Series с типом данных object, содержащий datetime.datetime)

Вызывает исключения:

ParserError

Если не удалось разобрать дату из строки.

ValueError

Если произошла другая ошибка преобразования даты и времени. Например, если в DataFrame отсутствует один из столбцов «year», «month» или «day», либо если в массивоподобном объекте с разными смещениями времени обнаружен объект datetime.datetime с часовым поясом и utc=False.

См. также

DataFrame.astype

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

to_timedelta

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

convert_dtypes

Преобразует типы данных.

Примечания

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

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

• массивоподобные объекты могут содержать целые числа, числа с плавающей точкой, строки и объекты datetime. По возможности они преобразуются в DatetimeIndex, в противном случае — в Index с типом данных object, содержащий объекты datetime.datetime. В обоих случаях элементы None/NaN/null преобразуются в NaT.

• Series по возможности преобразуются в Series с типом данных datetime64, в противном случае — в Series с типом данных object, содержащий объекты datetime.datetime. В обоих случаях элементы None/NaN/null преобразуются в NaT.

• DataFrame/объекты типа словаря преобразуются в Series с типом данных datetime64. Для каждой строки дата и время формируются из соответствующих столбцов фрейма данных. В качестве ключей столбцов можно использовать распространённые сокращения, например [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’, ‘ms’, ‘us’, ‘ns’], или соответствующие им формы множественного числа.

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

• если какой-либо входной элемент предшествует 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

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

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

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

• Однако входные данные с часовым поясом и разными смещениями времени (например, относящиеся к часовому поясу с переходом на летнее время, такому как Europe/Paris) не удаётся преобразовать в 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)

• Входные данные могут содержать строки или объекты datetime; приведённые выше правила остаются в силе

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