pandas.to_datetime#

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

将参数转换为日期时间。

此函数将标量、类数组、Series 或 DataFrame/类字典转换为 pandas 日期时间对象。

参数:

argint, float, str, datetime, list, tuple, 1-d 数组, Series, DataFrame/类似字典

要转换为日期时间的对象。如果提供的是 DataFrame，该方法至少需要以下列："year"、"month"、"day"。”year” 列必须以 4 位数字格式指定。

错误{‘raise’, ‘coerce’}, 默认 ‘raise’

如果 'raise'，则无效的解析将引发异常。
如果 'coerce'，那么无效的解析将被设置为 NaT。

dayfirstbool, 默认为 False

如果 arg 是字符串或类似列表，指定一个日期解析顺序。如果 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。没有时区的输入将保持没有时区，而有时区的输入将保持其时间偏移。对于混合偏移（通常是夏令时）存在限制，详见 :ref:`示例部分。

另请参阅：关于时区转换和本地化的 pandas 一般文档。

格式str, 默认 None

用于解析时间的 strftime，例如 "%d/%m/%Y"。有关选择的更多信息，请参阅 strftime 文档，但请注意，"%f" 将解析到纳秒。您还可以传递：

“ISO8601”，用于解析任何 ISO8601 时间字符串（不一定完全相同的格式）；
“混合”，以单独推断每个元素的格式。这是有风险的，您可能应该与 dayfirst 一起使用。

备注

如果传递了一个 DataFrame ，那么 format 没有效果。

精确布尔值, 默认为 True

控制如何使用 format：

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

不能与 format='ISO8601' 或 format='mixed' 一起使用。

单元str, 默认 ‘ns’

参数的单位（D,s,ms,us,ns）表示单位，这是一个整数或浮点数。这将基于原点。例如，使用 unit='ms' 和 origin='unix'，这将计算到 Unix 纪元开始时的毫秒数。

origin标量，默认 ‘unix’

定义参考日期。数值将被解析为自此参考日期以来的单位数（由 unit 定义）。

如果 'unix' （或 POSIX）时间；原点设置为 1970-01-01。
如果 'julian'，单位必须是 'D'，并且原点设置为儒略历的开始。儒略日数 0 被分配给公元前 4713 年 1 月 1 日中午开始的那一天。
如果时间戳可转换（Timestamp, dt.datetime, np.datetimt64 或日期字符串），原点设置为通过原点标识的时间戳。
如果是一个浮点数或整数，origin 是相对于 1970-01-01 的差值（单位由 unit 参数决定）。

缓存布尔值, 默认为 True

如果 True，使用一个唯一的转换日期缓存来应用日期时间转换。在解析重复的日期字符串时，尤其是在带有时区偏移的字符串时，可能会产生显著的速度提升。当至少有50个值时，才会使用缓存。存在超出范围的值会使缓存不可用，并可能减慢解析速度。

返回:

datetime

如果解析成功。返回类型取决于输入（括号中的类型对应于时区解析失败或时间戳超出范围时的回退情况）：

标量: 时间戳 (或 datetime.datetime)
类数组：DatetimeIndex`（或包含 :class:`datetime.datetime 的 object 数据类型的 Series）
系列: Series 的 datetime64 数据类型 (或 Series 的 object 数据类型包含 datetime.datetime)
DataFrame: Series 的 datetime64 类型（或包含 datetime.datetime 的 object 类型的 Series）

引发:

ParserError: 当从字符串解析日期失败时。
ValueError: 当另一个日期时间转换错误发生时。例如，当 DataFrame 中缺少 ‘year’, ‘month’, ‘day’ 列之一，或者当在混合时间偏移的类数组中找到带时区的 datetime.datetime 并且 utc=False，或者在解析具有混合时区的日期时间时，除非 utc=True。如果解析具有混合时区的日期时间，请指定 utc=True。

参见

DataFrame.astype: 将参数转换为指定的数据类型。
to_timedelta: 将参数转换为 timedelta。
convert_dtypes: 转换数据类型。

备注

支持许多输入类型，并会产生不同的输出类型：

标量可以是 int、float、str、datetime 对象（来自标准库 datetime 模块或 numpy）。它们在可能的情况下被转换为 Timestamp，否则它们被转换为 datetime.datetime。None/NaN/null 标量被转换为 NaT。
类似数组 可以包含 int、float、str、datetime 对象。它们在可能的情况下会被转换为 DatetimeIndex，否则它们会被转换为 Index 并带有 object dtype，包含 datetime.datetime。None/NaN/null 条目在这两种情况下都会被转换为 NaT。
Series 在可能的情况下会被转换为带有 datetime64 dtype 的 Series，否则它们会被转换为带有 object dtype 的 Series，包含 datetime.datetime。None/NaN/null 条目在这两种情况下都会被转换为 NaT。
DataFrame/类似字典 被转换为带有 datetime64 数据类型的 Series。对于每一行，通过组装各种数据框列来创建一个日期时间。列键可以是常见的缩写（如 [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’, ‘ms’, ‘us’, ‘ns’]）或它们的复数形式。

以下原因是导致返回 datetime.datetime 对象（可能在一个 Index 或一个具有 object 数据类型的 Series 中）而不是适当的 pandas 指定类型（Timestamp、DatetimeIndex 或具有 datetime64 数据类型的 Series）的原因：

当任何输入元素在 Timestamp.min 之前或 Timestamp.max 之后时，请参见时间戳限制。
当 utc=False``（默认）并且输入是一个包含混合的朴素/感知日期时间或带有混合时间偏移的感知日期时间的数组或 :class:`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[s]

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

警告

对于浮点参数，可能会发生精度舍入。为防止意外行为，请使用固定宽度的精确类型。

使用非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("invalid for Ymd", 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[s]', 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[s, UTC-05:00]', freq=None)

然而，带有混合时间偏移的时区感知输入（例如来自有时区夏令时的时区，如欧洲/巴黎）**不能成功转换**为 DatetimeIndex。解析带有混合时区的日期时间将引发 ValueError，除非 utc=True:

>>> pd.to_datetime(
...     ["2020-10-25 02:00 +0200", "2020-10-25 04:00 +0100"]
... )  
ValueError: Mixed timezones detected. Pass utc=True in to_datetime
or tz='UTC' in DatetimeIndex to convert to a common timezone.

要创建一个包含混合偏移量和 object 数据类型的 Series ，请使用 Series.apply() 和 datetime.datetime.strptime() 。

>>> import datetime as dt
>>> ser = pd.Series(["2020-10-25 02:00 +0200", "2020-10-25 04:00 +0100"])
>>> ser.apply(lambda x: dt.datetime.strptime(x, "%Y-%m-%d %H:%M %z"))
0    2020-10-25 02:00:00+02:00
1    2020-10-25 04:00:00+01:00
dtype: object

时区感知和时区不可知输入的混合也会引发 ValueError，除非 utc=True：

>>> from datetime import datetime
>>> pd.to_datetime(
...     ["2020-01-01 01:00:00-01:00", datetime(2020, 1, 1, 3, 0)]
... )  
ValueError: Mixed timezones detected. Pass utc=True in to_datetime
or tz='UTC' in DatetimeIndex to convert to a common timezone.

设置 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[s, 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[s, 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[us, UTC]', freq=None)