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

将参数转换为日期时间。

此函数将标量、类数组、SeriesDataFrame/类字典转换为 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

  • 如果 dayfirstyearfirst 都是 Trueyearfirst 优先(与 dateutil 相同)。

警告

yearfirst=True 不是严格的,但会更倾向于先解析年份。

utcbool, 默认 False

控制与时区相关的解析、本地化和转换。

  • 如果 True,该函数 总是 返回一个时区感知的 UTC 本地化的 TimestampSeriesDatetimeIndex。为此,时区无感的输入会被 本地化 为 UTC,而时区感知的输入会被 转换 为 UTC。

  • 如果 False`(默认),输入将不会被强制转换为 UTC。没有时区信息的输入将保持原样,而有时区信息的输入将保留其时间偏移。对于混合偏移(通常是夏令时)存在限制,详情请参见 :ref:`示例 部分。

警告

在未来的 pandas 版本中,除非 utc=True,否则解析包含混合时区的日期时间将引发错误。请指定 utc=True 以选择新的行为并消除此警告。要创建包含混合偏移量和 object 数据类型的 Series,请使用 applydatetime.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

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

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 对象(可能位于 IndexSeries 中,且具有 object 数据类型)而不是适当的 pandas 指定类型(TimestampDatetimeIndex 或具有 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)