From 2aeaf271132b5394a5e3f7eb2296f73659a30dd0 Mon Sep 17 00:00:00 2001 From: Richard Shadrach Date: Sun, 24 Aug 2025 09:24:53 -0400 Subject: [PATCH 1/2] DOC: Add change in .values to the string migration guide --- doc/source/user_guide/migration-3-strings.rst | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/source/user_guide/migration-3-strings.rst b/doc/source/user_guide/migration-3-strings.rst index be8e9c65e9747..2025cffeb956e 100644 --- a/doc/source/user_guide/migration-3-strings.rst +++ b/doc/source/user_guide/migration-3-strings.rst @@ -315,6 +315,37 @@ the :meth:`~pandas.Series.str.decode` method now has a ``dtype`` parameter to be able to specify object dtype instead of the default of string dtype for this use case. +Result of :meth:`~pandas.Series.values` is now an :class:`~pandas.ExtensionArray` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With object dtype, using ``.values`` on a Series will return the underlying NumPyArray. + +.. code-block:: python + + >>> ser = pd.Series(["a", "b", "c"], dtype="object") + >>> type(ser.values) + + +However with the new string dtype, the underlying ExtensionArray is returned instead. + +.. code-block:: python + + >>> ser = pd.Series(["a", "b", "c"], dtype="str") + >>> ser.values + + ['a', 'b', 'c'] + Length: 3, dtype: str + +If your code requires a NumPy array, you should use :meth:`Series.to_numpy`. + +.. code-block:: python + + >>> ser = pd.Series(["a", "b", pd.NA], dtype="str") + >>> ser.to_numpy() + ['a' 'b' nan] + +In general, you should always prefer :meth:`Series.to_numpy` to get a NumPy array or :meth:`Series.array` to get an ExtensionArray over using :meth:`Series.values`. + Notable bug fixes ~~~~~~~~~~~~~~~~~ From f12eda22e82ff42eaf143537a77b942be7528932 Mon Sep 17 00:00:00 2001 From: Richard Shadrach Date: Sun, 24 Aug 2025 12:02:37 -0400 Subject: [PATCH 2/2] Refinements --- doc/source/user_guide/migration-3-strings.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/user_guide/migration-3-strings.rst b/doc/source/user_guide/migration-3-strings.rst index 2025cffeb956e..b64fbf2a1ca46 100644 --- a/doc/source/user_guide/migration-3-strings.rst +++ b/doc/source/user_guide/migration-3-strings.rst @@ -315,14 +315,14 @@ the :meth:`~pandas.Series.str.decode` method now has a ``dtype`` parameter to be able to specify object dtype instead of the default of string dtype for this use case. -Result of :meth:`~pandas.Series.values` is now an :class:`~pandas.ExtensionArray` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:meth:`Series.values` now returns an :class:`~pandas.api.extensions.ExtensionArray` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -With object dtype, using ``.values`` on a Series will return the underlying NumPyArray. +With object dtype, using ``.values`` on a Series will return the underlying NumPy array. .. code-block:: python - >>> ser = pd.Series(["a", "b", "c"], dtype="object") + >>> ser = pd.Series(["a", "b", np.nan], dtype="object") >>> type(ser.values) @@ -330,10 +330,10 @@ However with the new string dtype, the underlying ExtensionArray is returned ins .. code-block:: python - >>> ser = pd.Series(["a", "b", "c"], dtype="str") + >>> ser = pd.Series(["a", "b", pd.NA], dtype="str") >>> ser.values - ['a', 'b', 'c'] + ['a', 'b', nan] Length: 3, dtype: str If your code requires a NumPy array, you should use :meth:`Series.to_numpy`.