dask_expr._collection.to_datetime
dask_expr._collection.to_datetime¶
- dask_expr._collection.to_datetime(arg: DatetimeScalar, errors: DateTimeErrorChoices = 'raise', dayfirst: bool = False, yearfirst: bool = False, utc: bool = False, format: str | None = None, exact: bool = _NoDefault.no_default, unit: str | None = None, infer_datetime_format: bool = _NoDefault.no_default, origin='unix', cache: bool = True) Timestamp [源代码]¶
- dask_expr._collection.to_datetime(arg: Series | DictConvertible, errors: DateTimeErrorChoices = 'raise', dayfirst: bool = False, yearfirst: bool = False, utc: bool = False, format: str | None = None, exact: bool = _NoDefault.no_default, unit: str | None = None, infer_datetime_format: bool = _NoDefault.no_default, origin='unix', cache: bool = True) dask_expr._collection.Series
- dask_expr._collection.to_datetime(arg: list | tuple | Index | ArrayLike, errors: DateTimeErrorChoices = 'raise', dayfirst: bool = False, yearfirst: bool = False, utc: bool = False, format: str | None = None, exact: bool = _NoDefault.no_default, unit: str | None = None, infer_datetime_format: bool = _NoDefault.no_default, origin='unix', cache: bool = True) DatetimeIndex
将参数转换为日期时间。
此函数将标量、类数组、
Series
或DataFrame
/类字典转换为 pandas 的 datetime 对象。- 参数
- 参数int, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like
要转换为日期时间的对象。如果提供的是
DataFrame
,该方法至少需要以下列:“年”
,“月”
,“日”
。“年”列必须以四位数格式指定。- 错误{‘忽略’, ‘引发’, ‘强制’}, 默认 ‘引发’
如果
'raise'
,那么无效的解析将引发异常。如果
'coerce'
,那么无效的解析将被设置为NaT
。如果
'ignore'
,那么无效的解析将返回输入。
- 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 版本中,除非 utc=True,否则解析包含混合时区的日期时间将引发错误。请指定 utc=True 以选择新的行为并消除此警告。要创建包含混合偏移量和 object 数据类型的 Series,请使用 apply 和 datetime.datetime.strptime。
另请参阅:关于 时区转换和本地化 的 pandas 一般文档。
- 格式str, 默认 None
用于解析时间的 strftime 格式,例如
"%d/%m/%Y"
。有关选择的更多信息,请参阅 strftime 文档,但请注意"%f"
将解析到纳秒级。您还可以传递:“ISO8601”,用于解析任何 ISO8601 时间字符串(不一定是完全相同的格式);
“mixed”,用于单独推断每个元素的格式。这是有风险的,您可能应该与 dayfirst 一起使用。
备注
如果传递了一个
DataFrame
,那么 format 将无效。- 精确bool, 默认 True
控制 format 的使用方式:
如果
True
,则要求完全匹配 format。如果
False
,允许 format 匹配目标字符串中的任何位置。
不能与
format='ISO8601'
或format='mixed'
一起使用。- 单元str, 默认值为 ‘ns’
参数的单位(D,s,ms,us,ns)表示单位,这是一个整数或浮点数。这将基于原点。例如,使用
unit='ms'
和origin='unix'
,这将计算到unix纪元开始的时间的毫秒数。- infer_datetime_formatbool, 默认 False
如果
True
且未给出 format,则尝试根据第一个非 NaN 元素推断日期时间字符串的格式,如果可以推断,则切换到更快的解析方法。在某些情况下,这可以将解析速度提高 ~5-10 倍。2.0.0 版后已移除: 此参数的严格版本现在是默认值,传递它没有效果。
- 起源标量,默认值为 ‘unix’
定义参考日期。数值将被解析为自此参考日期以来的单位数(由 unit 定义)。
如果
'unix'
(或 POSIX)时间;原点设置为 1970-01-01。如果
'julian'
,单位必须是'D'
,并且原点设置为儒略历的开始。儒略日数0
被分配给公元前 4713 年 1 月 1 日中午开始的那一天。如果时间戳可转换(Timestamp、dt.datetime、np.datetimt64 或日期字符串),则将原点设置为由原点标识的时间戳。
如果是一个浮点数或整数,origin 是相对于 1970-01-01 的差值(单位由
unit
参数决定)。
- 缓存bool, 默认 True
如果
True
,使用一个唯一的、转换后的日期缓存来应用日期时间转换。在解析重复的日期字符串时,尤其是在包含时区偏移的情况下,可能会显著提高速度。只有当至少有50个值时,才会使用缓存。存在超出范围的值将使缓存不可用,并可能减慢解析速度。
- 返回
- datetime
如果解析成功。返回类型取决于输入(括号中的类型对应于时区解析失败或时间戳超出范围时的回退):
标量:
时间戳
(或datetime.datetime
)类似数组:
DatetimeIndex`(或包含 :class:`datetime.datetime
的Series
与object
数据类型)系列:
Series
的datetime64
数据类型 (或Series
的object
数据类型包含datetime.datetime
)DataFrame:
Series
的datetime64
类型 (或Series
的object
类型包含datetime.datetime
)
- Raises
- 解析器错误
当从字符串解析日期失败时。
- ValueError
当发生另一个日期时间转换错误时。例如,当
DataFrame
中缺少 ‘year’, ‘month’, ‘day’ 列之一,或者当在混合时间偏移的类数组对象中发现带有时区的datetime.datetime
,并且utc=False
时。
参见
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
,其 dtype 为object
,包含datetime.datetime
。None/NaN/null 条目在这两种情况下都会被转换为NaT
。系列 在可能的情况下会被转换为
Series
并带有datetime64
数据类型,否则它们会被转换为带有object
数据类型的Series
,其中包含datetime.datetime
。None/NaN/null 条目在这两种情况下都会被转换为NaT
。DataFrame/dict-like 被转换为
Series
,其数据类型为datetime64
。对于每一行,通过组合不同的数据框列来创建一个日期时间。列键可以是常见的缩写(如 [‘year’, ‘month’, ‘day’, ‘minute’, ‘second’, ‘ms’, ‘us’, ‘ns’])或其复数形式。
以下原因是导致返回
datetime.datetime
对象(可能位于Index
或Series
中,且具有object
数据类型)而不是适当的 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[ns]
使用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('13000101', 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[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, UTC-05:00]', freq=None)
然而,带有混合时间偏移的时区感知输入(例如来自具有夏令时的时区,如欧洲/巴黎)**无法成功转换**为
DatetimeIndex
。解析具有混合时区的日期时间将显示警告,除非 utc=True。如果你指定 utc=False,将显示以下警告,并返回一个包含datetime.datetime
对象的简单Index
:
>>> pd.to_datetime(['2020-10-25 02:00 +0200', ... '2020-10-25 04:00 +0100']) FutureWarning: In a future version of pandas, parsing datetimes with mixed time zones will raise an error unless `utc=True`. Please specify `utc=True` to opt in to the new behaviour and silence this warning. To create a `Series` with mixed offsets and `object` dtype, please use `apply` and `datetime.datetime.strptime`. Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00], dtype='object')
时区感知和时区不感知输入的混合也会被转换为一个简单的
索引
,其中包含datetime.datetime
对象:
>>> from datetime import datetime >>> pd.to_datetime(["2020-01-01 01:00:00-01:00", ... datetime(2020, 1, 1, 3, 0)]) FutureWarning: In a future version of pandas, parsing datetimes with mixed time zones will raise an error unless `utc=True`. Please specify `utc=True` to opt in to the new behaviour and silence this warning. To create a `Series` with mixed offsets and `object` dtype, please use `apply` and `datetime.datetime.strptime`. Index([2020-01-01 01:00:00-01:00, 2020-01-01 03:00:00], dtype='object')
设置
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)
输入可以包含字符串或日期时间,上述规则仍然适用
>>> 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[ns, UTC]', freq=None)