3.0.0 中的新功能（2024年XX月）#

这是 pandas 3.0.0 中的更改。有关包括其他版本在内的完整更新日志，请参见 发行说明。

增强功能#

enhancement1#

enhancement2#

其他增强功能#

值得注意的错误修复#

这些是可能会有显著行为变化的错误修复。

在 observed=False 的情况下改进了 groupby 的行为#

由于改进了对未观察组的处理，修复了许多错误（GH 55738）。本节中的所有评论同样影响 SeriesGroupBy。

在 pandas 的早期版本中，使用 DataFrameGroupBy.apply() 或 DataFrameGroupBy.agg() 进行单一分组时，会将未观察到的组传递给提供的函数，导致下面出现 0。

In [1]: df = pd.DataFrame(
   ...:     {
   ...:         "key1": pd.Categorical(list("aabb"), categories=list("abc")),
   ...:         "key2": [1, 1, 1, 2],
   ...:         "values": [1, 2, 3, 4],
   ...:     }
   ...: )
   ...: 

In [2]: df
Out[2]: 
  key1  key2  values
0    a     1       1
1    a     1       2
2    b     1       3
3    b     2       4

In [3]: gb = df.groupby("key1", observed=False)

In [4]: gb[["values"]].apply(lambda x: x.sum())
Out[4]: 
      values
key1        
a          3
b          7
c          0

然而，在使用多个分组时，情况并非如此，导致下面出现 NaN。

In [1]: gb = df.groupby(["key1", "key2"], observed=False)
In [2]: gb[["values"]].apply(lambda x: x.sum())
Out[2]:
           values
key1 key2
a    1        3.0
     2        NaN
b    1        3.0
     2        4.0
c    1        NaN
     2        NaN

现在使用多个分组也会将未观察到的分组传递给提供的函数。

In [5]: gb = df.groupby(["key1", "key2"], observed=False)

In [6]: gb[["values"]].apply(lambda x: x.sum())
Out[6]: 
           values
key1 key2        
a    1          3
     2          0
b    1          3
     2          4
c    1          0
     2          0

同样地：

这些改进也修复了 groupby 中的某些错误：

notable_bug_fix2#

向后不兼容的 API 变化#

日期时间解析推理#

将一系列字符串、datetime 对象或 np.datetime64 对象转换为 datetime64 dtype 现在会推断输出 dtype 的适当分辨率（也称为单位）。这会影响 Series、DataFrame、Index、DatetimeIndex 和 to_datetime()。

之前，这些总是提供纳秒分辨率：

In [1]: dt = pd.Timestamp("2024-03-22 11:36").to_pydatetime()
In [2]: pd.to_datetime([dt]).dtype
Out[2]: dtype('<M8[ns]')
In [3]: pd.Index([dt]).dtype
Out[3]: dtype('<M8[ns]')
In [4]: pd.DatetimeIndex([dt]).dtype
Out[4]: dtype('<M8[ns]')
In [5]: pd.Series([dt]).dtype
Out[5]: dtype('<M8[ns]')

现在从 pydatetime 对象推断出微秒单位“us”，与标量 Timestamp 行为匹配。

In [7]: In [1]: dt = pd.Timestamp("2024-03-22 11:36").to_pydatetime()

In [8]: In [2]: pd.to_datetime([dt]).dtype
Out[8]: dtype('<M8[us]')

In [9]: In [3]: pd.Index([dt]).dtype
Out[9]: dtype('<M8[us]')

In [10]: In [4]: pd.DatetimeIndex([dt]).dtype
Out[10]: dtype('<M8[us]')

In [11]: In [5]: pd.Series([dt]).dtype
Out[11]: dtype('<M8[us]')

类似地，当传递一个 np.datetime64 对象序列时，传递对象的分辨率将被保留（或者对于低于秒的分辨率，将使用秒分辨率）。

当传递字符串时，解析将取决于字符串的精度，再次匹配 Timestamp 行为。之前：

In [2]: pd.to_datetime(["2024-03-22 11:43:01"]).dtype
Out[2]: dtype('<M8[ns]')
In [3]: pd.to_datetime(["2024-03-22 11:43:01.002"]).dtype
Out[3]: dtype('<M8[ns]')
In [4]: pd.to_datetime(["2024-03-22 11:43:01.002003"]).dtype
Out[4]: dtype('<M8[ns]')
In [5]: pd.to_datetime(["2024-03-22 11:43:01.002003004"]).dtype
Out[5]: dtype('<M8[ns]')

推断的分辨率现在与输入字符串的分辨率匹配：

In [12]: In [2]: pd.to_datetime(["2024-03-22 11:43:01"]).dtype
Out[12]: dtype('<M8[s]')

In [13]: In [3]: pd.to_datetime(["2024-03-22 11:43:01.002"]).dtype
Out[13]: dtype('<M8[ms]')

In [14]: In [4]: pd.to_datetime(["2024-03-22 11:43:01.002003"]).dtype
Out[14]: dtype('<M8[us]')

In [15]: In [5]: pd.to_datetime(["2024-03-22 11:43:01.002003004"]).dtype
Out[15]: dtype('<M8[ns]')

在混合分辨率输入的情况下，使用最高分辨率：

In [2]: pd.to_datetime([pd.Timestamp("2024-03-22 11:43:01"), "2024-03-22 11:43:01.002"]).dtype
Out[2]: dtype('<M8[ns]')

增加 Python 的最小版本#

pandas 3.0.0 支持 Python 3.10 及以上版本。

增加了依赖项的最小版本#

一些依赖项的最低支持版本已更新。如果已安装，我们现在要求：

包

最低版本

必需的

Changed

numpy

1.23.5

X

X

对于 可选库 ，一般的建议是使用最新版本。下表列出了每个库在 pandas 开发过程中当前测试的最低版本。低于最低测试版本的可选库可能仍然有效，但不被视为支持。

包

新最低版本

pytz

2023.4

fastparquet

2023.10.0

adbc-driver-postgresql

0.10.0

mypy (dev)

1.9.0

更多信息请参见 依赖项 和 可选依赖项。

pytz 现在是一个可选依赖项#

pandas 现在在将时区字符串传递给各种方法时，默认使用标准库中的 zoneinfo 作为时区实现。(GH 34916)

旧行为:

In [1]: ts = pd.Timestamp(2024, 1, 1).tz_localize("US/Pacific")
In [2]: ts.tz
<DstTzInfo 'US/Pacific' LMT-1 day, 16:07:00 STD>

新行为：

In [16]: ts = pd.Timestamp(2024, 1, 1).tz_localize("US/Pacific")

In [17]: ts.tz
Out[17]: zoneinfo.ZoneInfo(key='US/Pacific')

pytz 时区对象在直接传递时仍然受支持，但它们将不再默认从字符串输入中返回。此外，pytz 不再是 pandas 的必需依赖项，但可以通过 pip extra pip install pandas[timezone] 安装。

此外，pandas 不再对导致模糊或不存在时间的时区操作抛出 pytz 异常。这些情况现在将引发 ValueError。

其他 API 更改#

弃用#

Copy 关键字#

以下方法中的 copy 关键字参数已弃用，并将在未来版本中移除：

写时复制利用了一种延迟复制机制，直到必要时才复制数据。使用 .copy 来触发即时复制。从 3.0 版本开始，copy 关键字没有效果，因此可以安全地从代码中删除。

其他弃用#

移除先前版本的弃用/更改#

强制弃用别名 M, Q, Y 等，改为使用 ME, QE, YE 等作为偏移量#

重命名了以下偏移别名 (GH 57986):

偏移

移除别名

新别名

MonthEnd

M

ME

BusinessMonthEnd

BM

BME

SemiMonthEnd

SM

SME

CustomBusinessMonthEnd

CBM

CBME

QuarterEnd

Q

QE

BQuarterEnd

BQ

BQE

YearEnd

Y

YE

BYearEnd

BY

BYE

其他移除#

性能提升#

错误修复#

Categorical#

Datetimelike#

Timedelta#

时区#

Numeric#

  • 在 DataFrame.quantile() 中的一个错误，当 numeric_only=True 且 q 是类列表时，列类型未被保留，导致产生空结果 (GH 59035)

  • np.matmul 中使用 Index 输入引发 TypeError 的错误 (GH 57079)

转换#

字符串#

Interval#

索引#

  • 在 Python 3.12 中，当使用 slice 调用时，DataFrame.__getitem__() 返回修改后的列的错误 (GH 57500)

  • DataFrame.from_records() 在 index 中传递空列表时抛出 ValueError 的错误 (GH 58594)

缺失#

MultiIndex#

I/O#

周期#

绘图#

分组/重采样/滚动#

  • DataFrameGroupBy.__len__() 和 SeriesGroupBy.__len__() 中的错误会在分组包含NA值且 dropna=False 时引发 (GH 58644)

  • 在 DataFrameGroupBy.groups() 和 SeriesGroupby.groups() 中的错误，不会尊重 groupby 参数 dropna (GH 55919)

  • 在 DataFrameGroupBy.median() 中的错误，其中 nat 值给出了不正确的结果。(GH 57926)

  • Bug in DataFrameGroupBy.quantile() when interpolation="nearest" is inconsistent with DataFrame.quantile() (GH 47942)

  • 在具有非均匀采样和/或索引与结果重采样索引不一致的 DataFrame 上使用 Resampler.interpolate() 会导致错误的插值 (GH 21351)

  • 当传递 times 和非均值的聚合函数时，DataFrame.ewm() 和 Series.ewm() 中的错误 (GH 51695)

  • 在 DataFrameGroupBy.agg() 中存在一个错误，当输入是字典且存在重复列时，会引发 AttributeError ，而不是返回包含所有重复列聚合的 DataFrame。 (GH 55041)

  • DataFrameGroupBy.apply() 中的一个错误，当 func 的所有返回值都是 None 时，返回一个完全空的 DataFrame，而不是返回一个具有原始列和数据类型的空 DataFrame。(GH 57775)

  • 在 as_index=False 的情况下，DataFrameGroupBy.apply() 中的一个错误，返回的是 MultiIndex 而不是 Index。 (GH 58291)

  • 在 DataFrameGroupBy.cumsum() 和 DataFrameGroupBy.cumprod() 中的错误，其中 numeric_only 参数通过 kwargs 间接传递，而不是直接传递。(GH 58811)

  • DataFrameGroupBy.cumsum() 中的一个错误，当标签包含 None 时，它没有返回正确的 dtype。(GH 58811)

  • 在 DataFrameGroupby.transform() 和 SeriesGroupby.transform() 中存在一个错误，当使用归约器和 observed=False 时，如果有未观察到的类别，会将数据类型强制转换为浮点型。(GH 55326)

  • Bug in Rolling.apply() 中，如果 method="table"，应用的函数可能在少于 min_period 个周期内被调用。(GH 58868)

  • Series.resample() 中的错误在日期范围在非常接近一个不存在的时间结束时可能会引发。(GH 58380)

重塑#

Sparse#

ExtensionArray#

  • 在 arrays.ArrowExtensionArray.__setitem__() 中的错误，当使用带有重复值的整数数组作为键时会导致错误行为 (GH 58530)

  • 在 api.types.is_datetime64_any_dtype() 中的一个错误，其中自定义的 ExtensionDtype 会对类数组返回 False (GH 57055)

  • 在比较带有 ArrowDtype 的对象和类型不兼容的对象（例如字符串与布尔值）时，错误地引发异常，而不是返回全``False``（对于``==``）或全``True``（对于``!=``）(GH 59505)

  • 在各种 DataFrame 缩减中，当结果为空时，pyarrow 时间型数据类型返回不正确的数据类型 (GH 59234)

Styler#

其他#

贡献者#