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

将参数转换为日期时间。

此函数将标量 array-like、Series 或 DataFrame /dict-like 转换为 pandas 日期时间对象。

参数：

arg：int float, str, datetime, list, tuple, 一维数组, Series, DataFrame/dict-like

要转换为日期时间的对象。如果提供了DataFrame，则该方法至少需要以下列："year"、"month"、"day"。

errors：{‘ignore’, ‘raise’, ‘coerce’}，默认 ‘raise’

如果 'raise' ，则无效解析将引发异常。
如果 'coerce' ，则无效解析将设置为 NaT 。
如果 'ignore' ，则无效解析将返回输入。

dayfirst：布尔值，默认为 False

如果 arg 是 str 或 list-like，则指定日期解析顺序。如果 True ，首先解析日期，例如"10/11/12" 被解析为 2012-11-10 。

警告

dayfirst=True 并不严格，但更喜欢先解析 day。如果无法根据给定的 dayfirst 选项解析分隔日期字符串，例如to_datetime(['31-12-2021']) ，然后将显示警告。

yearfirst：布尔值，默认为 False

如果 arg 是 str 或 list-like，则指定日期解析顺序。

如果 True 以年份开头解析日期，例如"10/11/12" 被解析为 2010-11-12 。
如果 dayfirst 和 yearfirst 都是 True ，则在 yearfirst 之前(与 dateutil 相同)。

警告

yearfirst=True 并不严格，但更喜欢先解析年份。

utc：布尔值，默认无

控制timezone-related的解析、本地化和转换。

如果True，函数总是返回 timezone-aware UTC-localizedpandas.Timestamp,pandas.Series或者DatetimeIndex.为此，timezone-naive 输入是本地化作为 UTC，而 timezone-aware 输入是已转换到 UTC。
如果False(默认)，输入将不会被强制转换为 UTC。 Timezone-naive 输入将保持幼稚，而 timezone-aware 将保持其时间偏移。混合偏移(通常是夏令时)存在限制，有关详细信息，请参阅示例部分。

另请参阅：pandas 关于 timezone conversion and localization 的一般文档。

format：str，默认无

解析时间的 strftime，例如"%d/%m/%Y" 。请注意，"%f" 将一直解析到纳秒。有关选择的更多信息，请参阅strftime documentation。

exact：布尔值，默认为真

控制如何使用format：

如果 True ，需要精确的 format 匹配。
如果 False ，允许 format 匹配目标字符串中的任何位置。

unit：str，默认 ‘ns’

arg 的单位 (D,s,ms,us,ns) 表示单位，它是整数或浮点数。这将基于原点。例如，使用 unit='ms' 和 origin='unix'(默认值)，这将计算到 unix 纪元开始的毫秒数。

infer_datetime_format：布尔值，默认为 False

如果 True 并且没有给出 format，则尝试根据第一个非 NaN 元素推断日期时间字符串的格式，如果可以推断，则切换到更快的解析方法。在某些情况下，这可以将解析速度提高约 5-10 倍。

origin：标量，默认 ‘unix’

定义参考日期。自此参考日期以来，数值将被解析为单位数(由 unit 定义)。

如果'unix'(或POSIX)时间；原点设置为 1970-01-01。
如果 'julian' ，单位必须是 'D' ，并且原点设置为儒略历的开头。儒略日编号0 分配给从公元前 4713 年 1 月 1 日中午开始的那一天。
如果 Timestamp 可转换，则 origin 设置为由 origin 标识的 Timestamp。

cache：布尔值，默认为真

如果 True ，使用唯一的转换日期缓存来应用日期时间转换。解析重复的日期字符串时可能会产生显著的speed-up，尤其是具有时区偏移的字符串。仅当至少有 50 个值时才使用缓存。越界值的存在将导致缓存不可用并可能减慢解析速度。

datetime

如果解析成功。返回类型取决于输入(括号中的类型对应于在不成功的时区或超出范围的时间戳解析的情况下的回退)：

标量：Timestamp(或 datetime.datetime)
array-like：DatetimeIndex(或 Series 与 object dtype 包含 datetime.datetime )
系列：datetime64 dtype 的Series(或包含datetime.datetime 的object dtype 的Series)
数据帧：datetime64 dtype 的 Series(或包含 datetime.datetime 的 object dtype 的 Series)

抛出：

ParserError: 从字符串解析日期失败时。
ValueError: 当另一个日期时间转换错误发生时。例如，当 ‘year’, ‘month’、day' 列之一在 DataFrame 中丢失时，或者当 Timezone-aware datetime.datetime 在混合时间偏移的 array-like 和 utc=False 中找到时。

注意：

支持许多输入类型，并导致不同的输出类型：

标量可以是int float、str、datetime 对象(来自 stdlibdatetime模块或numpy)。它们被转换为pandas.Timestamp如果可能，否则它们将转换为datetime.datetime. None/NaN/null 标量转换为NaT.
array-like可以包含int float、str、datetime 对象。它们被转换为DatetimeIndex如果可能，否则它们将转换为pandas.Index和objectdtype，包含datetime.datetime. None/NaN/null 条目被转换为NaT在这两种情况下。
Series被转换为pandas.Series和datetime64dtype 尽可能，否则它们将转换为pandas.Series和objectdtype，包含datetime.datetime. None/NaN/null 条目被转换为NaT在这两种情况下。
数据帧/dict-like被转换为pandas.Series和datetime64类型。对于每一行，通过组合各种 DataFrame 列创建一个日期时间。列键可以是常见的缩写，如 [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’, ‘ms’, ‘us’, ‘ns’]) 或相同的复数。

以下原因导致返回 datetime.datetime 对象(可能在 Index 或带有 object dtype 的 Series 内)而不是正确的 pandas 指定类型( Timestamp 、 DatetimeIndex 或 Series datetime64 数据类型)：

当任何输入元素在 Timestamp.min 之前或 Timestamp.max 之后，请参见 timestamp limitations 。
当utc=False(默认)并且输入是一个array-like 或Series 包含混合的naive/aware datetime，或有混合的时间偏移量。请注意，当时区有夏令时政策时，这种情况会发生(非常频繁)。在这种情况下，您可能希望使用 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]

传递 infer_datetime_format=True 可以 often-times 加速解析，如果它不是 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 arg，可能会发生精确舍入。为防止出现意外行为，请使用 fixed-width 精确类型。

使用非 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)

不可转换的日期/时间

如果日期不符合 timestamp limitations ，则传递 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)如下：

Timezone-naive 输入转换为 timezone-naive 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)

Timezone-aware 输入具有恒定的时间偏移被转换为timezone-awareDatetimeIndex：

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

但是，timezone-aware 输入具有混合时间偏移(例如从具有夏令时的时区发出，例如欧洲/巴黎)是未成功转换到一个DatetimeIndex.取而代之的是一个简单的pandas.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')

如果 timezone-aware 的偏移量恒定，则 timezone-aware 和 timezone-naive 输入的混合将转换为 timezone-aware 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)

最后，混合timezone-aware 字符串和datetime.datetime 总是会引发错误，即使元素都具有相同的时间偏移。

>>> from datetime import datetime, timezone, timedelta
>>> d = datetime(2020, 1, 1, 18, tzinfo=timezone(-timedelta(hours=1)))
>>> pd.to_datetime(["2020-01-01 17:00 -0100", d])
Traceback (most recent call last):
    ...
ValueError: Tz-aware datetime.datetime cannot be converted to datetime64
            unless utc=True

设置utc=True 可以解决上述大部分问题：

Timezone-naive 输入本地化为 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)

Timezone-aware 输入是已转换到 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)

输入可以包含naive和aware，字符串或日期时间，上述规则仍然适用

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

相关用法

注：本文由纯净天空筛选整理自pandas.pydata.org大神的英文原创作品 pandas.to_datetime。非经特殊声明，原始代码版权归原作者所有，本译文未经允许或授权，请勿转载或复制。

用法:

参数：

返回：

抛出：

注意：

例子：