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)[源代码]#
将参数转换为日期时间。
此函数用于将标量、类似数组的
Series或DataFrame/dict类似于PandasDateTime对象。- 参数
- arg整型、浮点型、字符串、日期时间、列表、元组、一维数组、系列、数据帧/类字典
要转换为DateTime的对象。如果一个
DataFrame，则该方法至少需要以下列："year"，"month"，"day"。- errors{‘忽略’，‘提升’，‘强制’}，默认‘提升’
如果
'raise'，则无效的解析将引发异常。如果
'coerce'，则无效解析将设置为NaT。如果
'ignore'，则无效的解析将返回输入。
- dayfirst布尔值，默认为False
如果满足以下条件，请指定日期解析顺序 arg 是字符串或类似于列表。如果
True，以日期开头的日期进行解析，例如"10/11/12"被解析为2012-11-10。警告
dayfirst=True不是很严格，但会更喜欢跟天先解析。如果分隔的日期字符串无法根据给定的 dayfirst 选项，例如to_datetime(['31-12-2021'])，则会显示警告。- yearfirst布尔值，默认为False
如果满足以下条件，请指定日期解析顺序 arg 是字符串或类似于列表。
如果
True先分析年份，例如"10/11/12"被解析为2010-11-12。如果两者都有 dayfirst 和 yearfirst 是
True， yearfirst 位于前面(与dateutil)。
警告
yearfirst=True不是严格的，但会更喜欢用年优先解析。- utc布尔默认为无
控制与时区相关的解析、本地化和转换。
如果
True，该函数 始终 返回支持时区的UTC本地化Timestamp，Series或DatetimeIndex。要做到这一点，时区原始输入是 本地化 作为UTC，而时区感知输入是 已转换 到协调世界时。如果
False(默认)，输入不会被强制为UTC。时区朴素的输入将保持朴素，而时区感知的输入将保持其时间偏移量。混合偏移(通常为夏令时)存在限制，请参见 Examples 部分了解详细信息。
另请参阅：关于Pandas的一般文档 timezone conversion and localization 。
- format字符串，默认为无
解析时间的strftime，例如
"%d/%m/%Y"。请注意，"%f"将一直解析到纳秒。看见 strftime documentation 有关选择的详细信息，请参阅。- exact布尔值，默认为True
控制方式 format 使用的是：
如果
True，需要一个完全相同的 format 火柴。如果
False，允许 format 以匹配目标字符串中的任何位置。
- unit字符串，默认为“ns”
Arg的单位(D，s，ms，us，ns)表示单位，它是一个整数或浮点数。这将基于原点。例如，使用
unit='ms'和origin='unix'，这将计算距Unix纪元开始的毫秒数。- infer_datetime_format布尔值，默认为False
如果
True而且没有 format ，则尝试根据第一个非NaN元素推断DateTime字符串的格式，如果可以推断，则切换到更快的解析方法。在某些情况下，这可以将解析速度提高约5-10倍。- origin标量，默认‘unix’
定义参考日期。数值将被解析为单位数(由 unit )从这个参考日期开始。
如果
'unix'(或POSIX)时间；原点设置为1970-01-01。如果
'julian'，单位必须为'D'，原点设置为儒略历的开始。儒略日编号0分配到公元前4713年1月1日中午开始的那一天。如果时间戳可转换，则将来源设置为由来源标识的时间戳。
- cache布尔值，默认为True
如果
True中，使用唯一的转换日期缓存来应用日期时间转换。在分析重复的日期字符串时，尤其是具有时区偏移量的字符串时，可能会显著提高速度。仅当至少有50个值时才使用缓存。越界值的存在将导致缓存不可用，并可能减慢解析速度。在 0.25.0 版更改: 将缺省值从
False至True。
- 退货
- 日期时间
如果解析成功。返回类型取决于输入(括号中的类型对应于时区或时间戳解析不成功时的回退)：
标量：
Timestamp(或datetime.datetime)类似于阵列的：
DatetimeIndex(或Series使用object数据类型包含datetime.datetime)系列：
Series的datetime64数据类型(或Series的object数据类型包含datetime.datetime)DataFrame：
Series的datetime64数据类型(或Series的object数据类型包含datetime.datetime)
- 加薪
- ParserError
在从字符串分析日期时失败。
- ValueError
当发生另一个日期时间转换错误时。例如，当“年”、“月”、“日”列中的一个列在
DataFrame，或者当时区感知时datetime.datetime在混合时间偏移量的数组中找到，并且utc=False。
参见
DataFrame.astype将参数强制转换为指定的数据类型。
to_timedelta将参数转换为时间增量。
convert_dtypes转换数据类型。
注意事项
支持多种输入类型，并导致不同的输出类型：
标量 可以是int、Float、str、DateTime对象(来自stdlib
datetime模块或numpy)。它们被转换为Timestamp如果可能，则将它们转换为datetime.datetime。无/NaN/空标量转换为NaT。array-like 可以包含int、Float、str、DateTime对象。它们被转换为
DatetimeIndex如果可能，则将它们转换为Index使用object数据类型，包含datetime.datetime。None/NaN/NULL条目转换为NaT在这两种情况下。系列 被转换为
Series使用datetime64如果可能，则将它们转换为Series使用object数据类型，包含datetime.datetime。None/NaN/NULL条目转换为NaT在这两种情况下。DataFrame/dict-like 被转换为
Series使用datetime64数据类型。对于每一行，通过组合各种数据框列来创建DateTime。列键可以是常见的缩写，如 [“年”、“月”、“日”、“分钟”、“秒”、“ms”、“us”、“ns”] )或相同的复数。
以下原因是导致
datetime.datetime返回的对象(可能在Index或者是Series使用objectDtype)，而不是正确的Pandas指定类型 (Timestamp，DatetimeIndex或Series使用datetime64Dtype)：当任何输入元素出现在
Timestamp.min或之后Timestamp.max，请参见 timestamp limitations 。什么时候
utc=False(默认)，并且输入是类似数组的或Series包含混合的朴素/Aware日期时间，或包含混合时间偏移量的Aware。请注意，在时区有夏令时政策的情况下(相当频繁)会发生这种情况。在这种情况下，您可能希望使用utc=True。
示例
处理各种输入格式
属性的多列组合日期时间。
DataFrame。这些键可以是常见的缩写，如 [“年”、“月”、“日”、“分钟”、“秒”、“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如果解析不完全是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')
警告
对于浮动参数，可能会发生精确舍入。若要防止意外行为，请使用固定宽度的精确类型。
使用非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)
Non-convertible date/times
如果日期不符合 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)，详情如下：时区-朴素输入转换为时区-朴素
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)
但是，支持时区的输入 具有混合时间偏移 (例如，来自夏令时的时区，如欧洲/巴黎)是 未成功转换 发送到
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)
最后，将支持时区的字符串和
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解决了上述大部分问题：时区-简单的输入是 本地化 作为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)
输入可以同时包含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)