pandas.to_datetime

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

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

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

Параметры

arg:int, float, str, datetime, список, кортеж, одномерный массив, Series, DataFrame/список-словарь

Объект, который нужно преобразовать в дату и время. Если предоставлен 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 не строгий, но будет отдавать предпочтение разбору по дню. Если строка с датой, разделённой разделителями, не может быть обработана в соответствии с заданным dayfirst, например to_datetime(['31-12-2021']), то будет показано предупреждение.

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

Укажите порядок разбора даты, если arg — строка или список.

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

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

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

yearfirst=True не строгий, но будет отдавать предпочтение разбору по году.

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

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

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

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

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

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

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

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

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

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

• Если False, разрешается соответствие format в любой части целевой строки.

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

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

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

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

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

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

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

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

• Если преобразования в Timestamp, начало установлено на Timestamp, определенный по началу.

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

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

Изменено в версии 0.25.0: изменено значение по умолчанию с False на True.

Возвращает

дата и время

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

• скаляр: 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

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

convert_dtypes

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

Замечания

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

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

• подобные массиву могут содержать int, float, str, объекты 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, содержащий смешанные наивные/осознанные даты и время, или осознанные с разными временными смещениями. Обратите внимание, что это происходит в (довольно частом) случае, когда часовой пояс имеет политику летнего времени. В этом случае вы можете использовать utc=True.

Примеры

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

Сборка даты и времени из нескольких столбцов 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]

Передача infer_datetime_format=True часто может ускорить парсинг, если это не точно формат ISO8601, но в обычном формате.

>>> s = pd.Series(['3/11/2000', '3/12/2000', '3/13/2000'] * 1000)
>>> s.head()
0    3/11/2000
1    3/12/2000
2    3/13/2000
3    3/11/2000
4    3/12/2000
dtype: object

>>> %timeit pd.to_datetime(s, infer_datetime_format=True)  
100 loops, best of 3: 10.4 ms per loop

>>> %timeit pd.to_datetime(s, infer_datetime_format=False)  
1 loop, best of 3: 471 ms per loop

Использование времени эпохи 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)

Непреобразуемые даты/времена

Если дата не соответствует ограничениям по временным меткам, передача errors='ignore' вернёт исходный ввод вместо возбуждения исключения.

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

>>> pd.to_datetime('13000101', format='%Y%m%d', errors='ignore')
datetime.datetime(1300, 1, 1, 0, 0)
>>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
NaT

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

Поведение по умолчанию (utc=False) таково:

• Ввод без указания часового пояса преобразуется в DatetimeIndex без указания часового пояса:

>>> pd.to_datetime(['2018-10-26 12: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, pytz.FixedOffset(-300)]', freq=None)

• Однако, ввод с указанием часового пояса с переменным временным смещением (например, из часового пояса с летним временем, например, Europe/Paris) не преобразуется в DatetimeIndex. Вместо этого возвращается простой Index, содержащий объекты datetime.datetime:

>>> pd.to_datetime(['2020-10-25 02:00 +0200', '2020-10-25 04:00 +0100'])
Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00],
      dtype='object')

• Смесь ввода с указанием и без указания часового пояса преобразуется в DatetimeIndex с указанием часового пояса, если смещения временных поясов с указанием часового пояса являются постоянными:

>>> from datetime import datetime
>>> pd.to_datetime(["2020-01-01 01:00 -01:00", datetime(2020, 1, 1, 3, 0)])
DatetimeIndex(['2020-01-01 01:00:00-01:00', '2020-01-01 02:00:00-01:00'],
              dtype='datetime64[ns, pytz.FixedOffset(-60)]', freq=None)

Установка 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)

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

>>> from datetime import timezone, timedelta
>>> pd.to_datetime(['2018-10-26 12:00', '2018-10-26 12:00 -0530',
...                datetime(2020, 1, 1, 18),
...                datetime(2020, 1, 1, 18,
...                tzinfo=timezone(-timedelta(hours=1)))],
...                utc=True)
DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 17:30:00+00:00',
               '2020-01-01 18:00:00+00:00', '2020-01-01 19:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq=None)