pandas.to_datetime

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

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

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

Параметры:

arg:int, float, str, datetime, list, tuple, 1-d массив, Series, DataFrame/dict-подобный объект

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

errors:{‘ignore’, ‘raise’, ‘coerce’}, по умолчанию ‘raise’

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

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

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

dayfirst:bool, по умолчанию False

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

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

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

yearfirst:bool, по умолчанию False

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

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

• Если оба dayfirst и yearfirst True, yearfirst имеет приоритет (то же, что и dateutil).

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

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

utc:bool, по умолчанию False

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

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

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

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

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

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

format:str, по умолчанию None

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

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

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

Примечание

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

exact:bool, по умолчанию True

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

• Если True, требуется точное совпадение с format.

• Если False, format может совпадать где угодно в целевой строке.

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

unit:str, по умолчанию ‘ns’

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

infer_datetime_format:bool, по умолчанию False

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

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

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

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

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

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

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

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

cache:bool, по умолчанию True

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

Возвращает:

дата и время

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

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

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

• Series: Series типа datetime64 (или Series типа object содержащего datetime.datetime)

• DataFrame: Series типа datetime64 (или Series типа object содержащего datetime.datetime)

Возбуждает:

ParserError

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

ValueError

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

См. также

DataFrame.astype

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

to_timedelta

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

convert_dtypes

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

Примечания

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

• Скаляры могут быть целыми числами, числами с плавающей запятой, строками, объектами datetime (из модуля stdlib 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. Для каждой строки создаётся объект datetime, собранный из различных столбцов DataFrame. Ключи столбцов могут быть общими аббревиатурами, такими как [‘год’, ‘месяц’, ‘день’, ‘минута’, ‘секунда’, ‘мс’, ‘мкс’, ‘нкс’]) или множественным числом от того же слова.

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

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

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

Примеры

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

Сборка datetime из нескольких столбцов DataFrame. Ключи могут быть общими аббревиатурами, такими как [‘год’, ‘месяц’, ‘день’, ‘минута’, ‘секунда’, ‘мс’, ‘мкс’, ‘нкс’]) или множественным числом от того же слова

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