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)[source]#
将参数转换为 datetime。
此函数将标量、类数组、
Series或DataFrame/类似字典的对象转换为 pandas datetime 对象。- 参数:
- argint, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like
要转换为 datetime 的对象。如果提供的是
DataFrame，则该方法至少需要以下列："year"、"month"、"day"。 “year” 列必须以 4 位数字格式指定。- errors{‘raise’, ‘coerce’}, default ‘raise’
如果为
'raise'，则无效的解析将引发异常。如果为
'coerce'，则无效的解析将设置为NaT。
- dayfirstbool, default False
当 arg 是 str 或类列表时，指定日期解析顺序。如果为
True，则以日为先解析日期，例如"10/11/12"被解析为2012-11-10。警告
dayfirst=True不是严格的，但会优先以日为先解析。- yearfirstbool, default False
当 arg 是 str 或类列表时，指定日期解析顺序。
如果为
True，则以年为先解析日期，例如"10/11/12"被解析为2010-11-12。如果 dayfirst 和 yearfirst 都为
True，则 yearfirst 优先（与dateutil相同）。
警告
yearfirst=True不是严格的，但会优先以年为先解析。- utcbool, default False
控制与时区相关的解析、本地化和转换。
如果为
True，则该函数*始终*返回一个带时区的 UTC 本地化Timestamp、Series或DatetimeIndex。为此，时区无关的输入会被*本地化*为 UTC，而带时区的输入会被*转换为* UTC。如果为
False(默认值)，则输入不会被强制转换为 UTC。时区无关的输入将保持无关，而带时区的输入将保留其时间偏移。混合偏移量（通常是夏令时）存在限制，请参阅 示例 部分了解详细信息。
另请参阅：pandas 关于 时区转换和本地化 的一般文档。
- formatstr, default None
用于解析时间的 strftime 格式，例如
"%d/%m/%Y"。有关选项的更多信息，请参阅 strftime 文档，但请注意"%f"将解析到纳秒。“ISO8601”，用于解析任何 ISO8601 时间字符串（不一定是完全相同的格式）；
“mixed”，用于单独推断每个元素的格式。这有风险，您可能应该与 dayfirst 一起使用。
注意
如果传入
DataFrame，则 format 无效。- exactbool, default True
控制 format 的使用方式
如果为
True，则要求精确匹配 format。如果为
False，则允许 format 匹配目标字符串中的任意位置。
不能与
format='ISO8601'或format='mixed'一起使用。- unitstr, default ‘ns’
参数的单位（D,s,ms,us,ns）表示单位，这是一个整数或浮点数。这将基于 origin。例如，当
unit='ms'和origin='unix'时，它将计算自 unix 纪元开始以来的毫秒数。- originscalar, default ‘unix’
定义参考日期。数值将解析为自此参考日期以来的单位数（由 unit 定义）。
如果为
'unix'(或 POSIX) 时间； origin 设置为 1970-01-01。如果为
'julian'，unit 必须为'D'，origin 设置为儒略历的开始。儒略日0分配给公元前 4713 年 1 月 1 日中午开始的那一天。如果可转换为 Timestamp（Timestamp、dt.datetime、np.datetimt64 或日期字符串），则 origin 设置为 origin 标识的 Timestamp。
如果为浮点数或整数，origin 是相对于 1970-01-01 的差值（以
unit参数确定的单位表示）。
- cachebool, default True
如果为
True，则使用唯一的、已转换的日期缓存来应用 datetime 转换。当解析重复的日期字符串（尤其是包含时区偏移的字符串）时，可能会显着加快速度。仅当值至少为 50 个时才使用缓存。超出范围的值将导致缓存不可用，并可能减慢解析速度。
- 返回:
- datetime
如果解析成功。返回类型取决于输入（括号中的类型对应于在时区或超出范围的时间戳解析失败时进行的后备处理）
标量：
Timestamp（或datetime.datetime）类数组：
DatetimeIndex（或包含datetime.datetime的object类型的Series）Series：
datetime64类型的Series（或包含datetime.datetime的object类型的Series）DataFrame：
datetime64类型的Series（或包含datetime.datetime的object类型的Series）
- 引发:
- ParserError
从字符串解析日期时失败。
- ValueError
发生其他 datetime 转换错误时。例如，当
DataFrame中缺少“year”、“month”、“day”列之一时，或者当带时区的datetime.datetime出现在混合时间偏移的类数组中且utc=False时，或者当解析具有混合时区的 datetime 时（除非utc=True）。如果解析具有混合时区的 datetime，请指定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，否则将转换为具有object类型的Index，其中包含datetime.datetime。None/NaN/null 条目在这两种情况下都将转换为NaT。Series 将转换为具有
datetime64类型的Series（如果可能），否则将转换为具有object类型的Series，其中包含datetime.datetime。None/NaN/null 条目在这两种情况下都将转换为NaT。DataFrame/dict-like 将转换为
Series，数据类型为datetime64。对于每一行，通过组合各种 DataFrame 列来创建一个 datetime。列键可以是常用缩写（如 ['year', 'month', 'day', 'minute', 'second', 'ms', 'us', 'ns']）或它们的复数形式。
以下原因是导致返回
datetime.datetime对象（可能在Index或具有object类型的Series中），而不是 pandas 指定的类型（Timestamp、DatetimeIndex或datetime64类型的Series）当任何输入元素早于
Timestamp.min或晚于Timestamp.max时，请参阅 时间戳限制。当
utc=False（默认值）且输入是类数组或包含混合的 naive/aware datetime 或具有混合时间偏移的 aware 的Series时。请注意，这种情况相当常见，即时区具有夏令时策略。在这种情况下，您可能希望使用utc=True。
示例
处理各种输入格式
从
DataFrame的多个列组装 datetime。键可以是常用缩写（如 ['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[us]
使用 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 纪元 origin
>>> 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[s]', 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[us]', 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[us, UTC-05:00]', freq=None)
但是，具有*混合时间偏移*的带时区输入（例如来自具有夏令时的时区，如 Europe/Paris）**无法成功转换为**
DatetimeIndex。除非utc=True，否则解析具有混合时区的 datetime 将引发 ValueError。
>>> 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[us, UTC]', freq=None)
带时区的输入会被*转换为* UTC（输出表示完全相同的 datetime，但从 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[us, 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[us, UTC]', freq=None)