Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions doc/source/user_guide/migration-3-strings.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,14 @@ enable it with:

This allows you to test your code before the final 3.0 release.

.. note::

This migration guide focuses on the changes and migration steps needed when
you are currently using ``object`` dtype for string data, which is used by
default in pandas < 3.0. If you are already using one of the opt-in string
dtypes, you can continue to do so without change.
See :ref:`string_migration_guide-for_existing_users` for more details.

Background
----------

Expand Down Expand Up @@ -457,7 +465,23 @@ raise an error regardless of the number of strings:
...
TypeError: Cannot perform reduction 'prod' with string dtype

.. For existing users of the nullable ``StringDtype``
.. --------------------------------------------------

.. TODO
.. _string_migration_guide-for_existing_users:

For existing users of the nullable ``StringDtype``
--------------------------------------------------

While pandas 3.0 introduces a new _default_ string data type, pandas had an
opt-in nullable string data type since pandas 1.0, which can be specified using
``dtype="string"``. This nullable string dtype uses ``pd.NA`` as the missing
value indicator. In addition, also through :class:`ArrowDtype` (by using
``dtypes_backend="pyarrow"``) since pandas 1.5, one could already make use of
a dedicated string dtype.

If you are already using one of the nullable string dtypes, for example by
specifying ``dtype="string"``, by using :meth:`~DataFrame.convert_dtypes`, or
by specifying the ``dtype_backend`` argument in IO functions, you can continue
to do so without change.

The migration guide above applies to code that is currently (< 3.0) using object
dtype for string data.
Loading