.. _whatsnew_310:

What's new in 3.1.0 (Month XX, 2026)
------------------------------------

These are the changes in pandas 3.1.0. See :ref:`release` for a full changelog
including other versions of pandas.

{{ header }}

.. ---------------------------------------------------------------------------
.. _whatsnew_310.enhancements:

Enhancements
~~~~~~~~~~~~

.. _whatsnew_310.enhancements.enhancement1:

enhancement1
^^^^^^^^^^^^

.. _whatsnew_310.enhancements.enhancement2:

enhancement2
^^^^^^^^^^^^

.. _whatsnew_310.enhancements.other:

Other enhancements
^^^^^^^^^^^^^^^^^^
- :meth:`.DataFrameGroupBy.agg` now allows for the provided ``func`` to return a NumPy array (:issue:`63957`)
- Added :meth:`ExtensionArray.count` (:issue:`64450`)
- Display formatting for float sequences in DataFrame cells now respects the ``display.precision`` option (:issue:`60503`).
- Improved the string ``repr`` of :class:`pd.core.arrays.SparseArray` (:issue:`64547`)

.. ---------------------------------------------------------------------------
.. _whatsnew_310.notable_bug_fixes:

Notable bug fixes
~~~~~~~~~~~~~~~~~

These are bug fixes that might have notable behavior changes.

.. _whatsnew_310.notable_bug_fixes.notable_bug_fix1:

notable_bug_fix1
^^^^^^^^^^^^^^^^

.. _whatsnew_310.notable_bug_fixes.notable_bug_fix2:

notable_bug_fix2
^^^^^^^^^^^^^^^^

.. ---------------------------------------------------------------------------
.. _whatsnew_310.api_breaking:

Backwards incompatible API changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _whatsnew_310.api_breaking.deps:

Increased minimum versions for dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some minimum supported versions of dependencies were updated.
If installed, we now require:

+-----------------+-----------------+----------+---------+
| Package         | Minimum Version | Required | Changed |
+=================+=================+==========+=========+
|                 |                 |    X     |    X    |
+-----------------+-----------------+----------+---------+

For `optional libraries <https://pandas.pydata.org/docs/getting_started/install.html>`_ the general recommendation is to use the latest version.
The following table lists the lowest version per library that is currently being tested throughout the development of pandas.
Optional libraries below the lowest tested version may still work, but are not considered supported.

+-----------------+-----------------+---------+
| Package         | Minimum Version | Changed |
+=================+=================+=========+
|                 |                 |    X    |
+-----------------+-----------------+---------+

See :ref:`install.dependencies` and :ref:`install.optional_dependencies` for more.

.. _whatsnew_310.api_breaking.other:

Other API changes
^^^^^^^^^^^^^^^^^
- APIs that accept an ``engine="numba"`` parameter with ``engine_kwargs`` will no longer pass through a ``nopython`` argument to ``numba.jit``. This argument has had no effect since numba 0.59.0 (:issue:`64483`).
-

.. ---------------------------------------------------------------------------
.. _whatsnew_310.deprecations:

Deprecations
~~~~~~~~~~~~
- Deprecated :meth:`.DataFrameGroupBy.agg` and :meth:`.Resampler.agg` unpacking a scalar when the provided ``func`` returns a Series or array of length 1; in the future this will result in the Series or array being in the result. Users should unpack the scalar in ``func`` itself (:issue:`64014`)
- Deprecated arithmetic operations between pandas objects (:class:`DataFrame`, :class:`Series`, :class:`Index`, and pandas-implemented :class:`ExtensionArray` subclasses) and list-likes other than ``list``, ``np.ndarray``, :class:`ExtensionArray`, :class:`Index`, :class:`Series`, :class:`DataFrame`. For e.g. ``tuple`` or ``range``, explicitly cast these to a supported object instead. In a future version, these will be treated as scalar-like for pointwise operation (:issue:`62423`)
- Deprecated the ``.name`` property of offset objects (e.g., :class:`~pandas.tseries.offsets.Day`, :class:`~pandas.tseries.offsets.Hour`). Use ``.rule_code`` instead (:issue:`64207`)
-

.. ---------------------------------------------------------------------------
.. _whatsnew_310.performance:

Performance improvements
~~~~~~~~~~~~~~~~~~~~~~~~
- Performance improvement in :meth:`DataFrame.__getitem__` when selecting a
  single column by label on a :class:`DataFrame` with duplicate column names.
  (:issue:`64126`).
- Performance improvement in :func:`infer_freq` (:issue:`64463`)
- Performance improvement in :func:`merge` with ``how="cross"`` (:issue:`38082`)
- Performance improvement in :func:`merge` with ``how="left"`` (:issue:`64370`)
- Performance improvement in :meth:`GroupBy.quantile` (:issue:`64330`)
- Performance improvement in datetime/timedelta unit conversion (e.g. ``datetime64[s]`` to ``datetime64[ns]``) (:issue:`35025`)

.. ---------------------------------------------------------------------------
.. _whatsnew_310.bug_fixes:

Bug fixes
~~~~~~~~~
- Fix bug in :func:`to_datetime` that could give an unnecessary ``RuntimeWarning`` when converting DataFrame containing missing values (:issue:`64141`)

Categorical
^^^^^^^^^^^
-
-

Datetimelike
^^^^^^^^^^^^
- Bug in :class:`Timestamp` constructor, :class:`Timedelta` constructor, :func:`to_datetime`, and :func:`to_timedelta` with non-round ``float`` input and ``unit`` failing to raise when the value is just outside the representable bounds (:issue:`57366`)
- Bug in :meth:`DatetimeArray.isin` and :meth:`TimedeltaArray.isin` where mismatched resolutions could silently truncate finer-resolution values, leading to false matches (:issue:`64545`)

Timedelta
^^^^^^^^^
-
-

Timezones
^^^^^^^^^
-
-

Numeric
^^^^^^^
- Fixed bug in :func:`read_excel` where having a column with mixture of numeric and boolean values will typecast the values based on the first appearance data type since 1==True and 0==False (:issue:`60088`)
- Fixed bug in :meth:`Series.clip` where passing a scalar numpy array (e.g. ``np.array(0)``) would raise a ``TypeError`` (:issue:`59053`)

Conversion
^^^^^^^^^^
- Fixed :func:`pandas.array` to preserve mask information when converting NumPy masked arrays, converting masked values to missing values (:issue:`63879`).
- Fixed bug in :meth:`DataFrame.from_records` where ``exclude`` was ignored when ``data`` was an iterator and ``nrows=0`` (:issue:`63774`)
-

Strings
^^^^^^^
-
-

Interval
^^^^^^^^
-
-

Indexing
^^^^^^^^
- Bugs in setitem-with-expansion when adding new rows failing to keep the original dtype in some cases (:issue:`32346`, :issue:`15231`, :issue:`47503`, :issue:`6485`, :issue:`25383`, :issue:`52235`, :issue:`17026`, :issue:`56010`)
-

Missing
^^^^^^^
-
-

MultiIndex
^^^^^^^^^^
-
-

I/O
^^^
- Fixed bug in :func:`read_excel` where usage of ``skiprows`` could lead to an infinite loop (:issue:`64027`)
- Fixed :func:`read_json` with ``lines=True`` and ``chunksize`` to respect ``nrows``
  when the requested row count is not a multiple of the chunk size (:issue:`64025`)
- Fixed :func:`read_json` with ``lines=True`` and ``nrows=0`` to return an empty DataFrame (:issue:`64025`)

Period
^^^^^^
-
-

Plotting
^^^^^^^^
-
-

Groupby/resample/rolling
^^^^^^^^^^^^^^^^^^^^^^^^
- Bug in :meth:`.DataFrameGroupBy.agg` when there are no groups, multiple keys, and ``group_keys=False`` (:issue:`51445`)
- Bug in :meth:`.DataFrameGroupBy.agg` would operate on the group as a whole when ``args`` or ``kwargs`` are supplied for the provided ``func``; now this method only operates on each Series of the group (:issue:`39169`)

Reshaping
^^^^^^^^^
- In :func:`pivot_table`, when ``values`` is empty, the aggregation will be computed on a Series of all NA values (:issue:`46475`)
-

Sparse
^^^^^^
- Bug in indexing a :class:`SparseArray` with an out-of-bounds integer with the value of the length of the array returning the fill value instead of raising an ``IndexError`` (:issue:`64183`).
-

ExtensionArray
^^^^^^^^^^^^^^
- Fixed bug in :meth:`Series.apply` and :meth:`Series.map` where nullable integer dtypes were converted to float, causing precision loss for large integers; now the nullable dtype will be preserved (:issue:`63903`).
-
-

Styler
^^^^^^
-
-

Other
^^^^^

.. ***DO NOT USE THIS SECTION***

-
-

.. ---------------------------------------------------------------------------
.. _whatsnew_310.contributors:

Contributors
~~~~~~~~~~~~
