REF: Rename mode.nullable_backend to mode.dtype_backend (#50291)

Author: mroeschke

doc/source/whatsnew/v2.0.0.rst

@@ -28,10 +28,10 @@ The available extras, found in the :ref:`installation guide<install.dependencies
 ``[all, performance, computation, timezone, fss, aws, gcp, excel, parquet, feather, hdf5, spss, postgresql, mysql,
 sql-other, html, xml, plot, output_formatting, clipboard, compression, test]`` (:issue:`39164`).
 
-.. _whatsnew_200.enhancements.io_use_nullable_dtypes_and_nullable_backend:
+.. _whatsnew_200.enhancements.io_use_nullable_dtypes_and_dtype_backend:
 
-Configuration option, ``mode.nullable_backend``, to return pyarrow-backed dtypes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration option, ``mode.dtype_backend``, to return pyarrow-backed dtypes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``use_nullable_dtypes`` keyword argument has been expanded to the following functions to enable automatic conversion to nullable dtypes (:issue:`36712`)
 
@@ -41,7 +41,7 @@ The ``use_nullable_dtypes`` keyword argument has been expanded to the following
 * :func:`read_sql_query`
 * :func:`read_sql_table`
 
-Additionally a new global configuration, ``mode.nullable_backend`` can now be used in conjunction with the parameter ``use_nullable_dtypes=True`` in the following functions
+Additionally a new global configuration, ``mode.dtype_backend`` can now be used in conjunction with the parameter ``use_nullable_dtypes=True`` in the following functions
 to select the nullable dtypes implementation.
 
 * :func:`read_csv` (with ``engine="pyarrow"`` or ``engine="python"``)
@@ -50,12 +50,12 @@ to select the nullable dtypes implementation.
 * :func:`read_orc`
 
 
-And the following methods will also utilize the ``mode.nullable_backend`` option.
+And the following methods will also utilize the ``mode.dtype_backend`` option.
 
 * :meth:`DataFrame.convert_dtypes`
 * :meth:`Series.convert_dtypes`
 
-By default, ``mode.nullable_backend`` is set to ``"pandas"`` to return existing, numpy-backed nullable dtypes, but it can also
+By default, ``mode.dtype_backend`` is set to ``"pandas"`` to return existing, numpy-backed nullable dtypes, but it can also
 be set to ``"pyarrow"`` to return pyarrow-backed, nullable :class:`ArrowDtype` (:issue:`48957`, :issue:`49997`).
 
 .. ipython:: python
@@ -65,12 +65,12 @@ be set to ``"pyarrow"`` to return pyarrow-backed, nullable :class:`ArrowDtype` (
         1,2.5,True,a,,,,,
         3,4.5,False,b,6,7.5,True,a,
     """)
-    with pd.option_context("mode.nullable_backend", "pandas"):
+    with pd.option_context("mode.dtype_backend", "pandas"):
         df = pd.read_csv(data, use_nullable_dtypes=True)
     df.dtypes
 
     data.seek(0)
-    with pd.option_context("mode.nullable_backend", "pyarrow"):
+    with pd.option_context("mode.dtype_backend", "pyarrow"):
         df_pyarrow = pd.read_csv(data, use_nullable_dtypes=True, engine="pyarrow")
     df_pyarrow.dtypes
 

pandas/core/config_init.py

@@ -539,10 +539,11 @@ def use_inf_as_na_cb(key) -> None:
     The default storage for StringDtype.
 """
 
-nullable_backend_doc = """
+dtype_backend_doc = """
 : string
-    The nullable dtype implementation to return.
-    Available options: 'pandas', 'pyarrow', the default is 'pandas'.
+    The nullable dtype implementation to return. Only applicable to certain
+    operations where documented. Available options: 'pandas', 'pyarrow',
+    the default is 'pandas'.
 """
 
 with cf.config_prefix("mode"):
@@ -553,9 +554,9 @@ def use_inf_as_na_cb(key) -> None:
         validator=is_one_of_factory(["python", "pyarrow"]),
     )
     cf.register_option(
-        "nullable_backend",
+        "dtype_backend",
         "pandas",
-        nullable_backend_doc,
+        dtype_backend_doc,
         validator=is_one_of_factory(["pandas", "pyarrow"]),
     )
 

pandas/core/dtypes/cast.py

@@ -961,7 +961,7 @@ def convert_dtypes(
     convert_boolean: bool = True,
     convert_floating: bool = True,
     infer_objects: bool = False,
-    nullable_backend: Literal["pandas", "pyarrow"] = "pandas",
+    dtype_backend: Literal["pandas", "pyarrow"] = "pandas",
 ) -> DtypeObj:
     """
     Convert objects to best possible type, and optionally,
@@ -983,7 +983,7 @@ def convert_dtypes(
     infer_objects : bool, defaults False
         Whether to also infer objects to float/int if possible. Is only hit if the
         object array contains pd.NA.
-    nullable_backend : str, default "pandas"
+    dtype_backend : str, default "pandas"
         Nullable dtype implementation to use.
 
         * "pandas" returns numpy-backed nullable types
@@ -1076,7 +1076,7 @@ def convert_dtypes(
     else:
         inferred_dtype = input_array.dtype
 
-    if nullable_backend == "pyarrow":
+    if dtype_backend == "pyarrow":
         from pandas.core.arrays.arrow.array import to_pyarrow_type
         from pandas.core.arrays.arrow.dtype import ArrowDtype
         from pandas.core.arrays.string_ import StringDtype

pandas/core/generic.py

@@ -6432,9 +6432,9 @@ def convert_dtypes(
 
         .. versionadded:: 2.0
             The nullable dtype implementation can be configured by calling
-            ``pd.set_option("mode.nullable_backend", "pandas")`` to use
+            ``pd.set_option("mode.dtype_backend", "pandas")`` to use
             numpy-backed nullable dtypes or
-            ``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
+            ``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
             pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
 
         Examples

pandas/core/series.py

@@ -5410,15 +5410,15 @@ def _convert_dtypes(
                 input_series = input_series.copy()
 
         if convert_string or convert_integer or convert_boolean or convert_floating:
-            nullable_backend = get_option("mode.nullable_backend")
+            dtype_backend = get_option("mode.dtype_backend")
             inferred_dtype = convert_dtypes(
                 input_series._values,
                 convert_string,
                 convert_integer,
                 convert_boolean,
                 convert_floating,
                 infer_objects,
-                nullable_backend,
+                dtype_backend,
             )
             result = input_series.astype(inferred_dtype)
         else:

pandas/io/orc.py

@@ -59,16 +59,16 @@ def read_orc(
         for the resulting DataFrame.
 
         The nullable dtype implementation can be configured by calling
-        ``pd.set_option("mode.nullable_backend", "pandas")`` to use
+        ``pd.set_option("mode.dtype_backend", "pandas")`` to use
         numpy-backed nullable dtypes or
-        ``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
+        ``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
         pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
 
         .. versionadded:: 2.0.0
 
         .. note
 
-            Currently only ``mode.nullable_backend`` set to ``"pyarrow"`` is supported.
+            Currently only ``mode.dtype_backend`` set to ``"pyarrow"`` is supported.
 
     **kwargs
         Any additional kwargs are passed to pyarrow.
@@ -90,10 +90,10 @@ def read_orc(
         orc_file = orc.ORCFile(handles.handle)
         pa_table = orc_file.read(columns=columns, **kwargs)
     if use_nullable_dtypes:
-        nullable_backend = get_option("mode.nullable_backend")
-        if nullable_backend != "pyarrow":
+        dtype_backend = get_option("mode.dtype_backend")
+        if dtype_backend != "pyarrow":
             raise NotImplementedError(
-                f"mode.nullable_backend set to {nullable_backend} is not implemented."
+                f"mode.dtype_backend set to {dtype_backend} is not implemented."
             )
         df = DataFrame(
             {

pandas/io/parquet.py

@@ -222,12 +222,12 @@ def read(
     ) -> DataFrame:
         kwargs["use_pandas_metadata"] = True
 
-        nullable_backend = get_option("mode.nullable_backend")
+        dtype_backend = get_option("mode.dtype_backend")
         to_pandas_kwargs = {}
         if use_nullable_dtypes:
             import pandas as pd
 
-            if nullable_backend == "pandas":
+            if dtype_backend == "pandas":
                 mapping = {
                     self.api.int8(): pd.Int8Dtype(),
                     self.api.int16(): pd.Int16Dtype(),
@@ -257,9 +257,9 @@ def read(
             pa_table = self.api.parquet.read_table(
                 path_or_handle, columns=columns, **kwargs
             )
-            if nullable_backend == "pandas":
+            if dtype_backend == "pandas":
                 result = pa_table.to_pandas(**to_pandas_kwargs)
-            elif nullable_backend == "pyarrow":
+            elif dtype_backend == "pyarrow":
                 result = DataFrame(
                     {
                         col_name: arrays.ArrowExtensionArray(pa_col)
@@ -509,9 +509,9 @@ def read_parquet(
         .. versionadded:: 1.2.0
 
         The nullable dtype implementation can be configured by calling
-        ``pd.set_option("mode.nullable_backend", "pandas")`` to use
+        ``pd.set_option("mode.dtype_backend", "pandas")`` to use
         numpy-backed nullable dtypes or
-        ``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
+        ``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
         pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
 
         .. versionadded:: 2.0.0

pandas/io/parsers/arrow_parser_wrapper.py

@@ -151,7 +151,7 @@ def read(self) -> DataFrame:
         )
         if (
             self.kwds["use_nullable_dtypes"]
-            and get_option("mode.nullable_backend") == "pyarrow"
+            and get_option("mode.dtype_backend") == "pyarrow"
         ):
             frame = DataFrame(
                 {

pandas/io/parsers/base_parser.py

@@ -712,7 +712,7 @@ def _infer_types(
         use_nullable_dtypes: Literal[True] | Literal[False] = (
             self.use_nullable_dtypes and no_dtype_specified
         )
-        nullable_backend = get_option("mode.nullable_backend")
+        dtype_backend = get_option("mode.dtype_backend")
         result: ArrayLike
 
         if try_num_bool and is_object_dtype(values.dtype):
@@ -770,7 +770,7 @@ def _infer_types(
                 if inferred_type != "datetime":
                     result = StringDtype().construct_array_type()._from_sequence(values)
 
-        if use_nullable_dtypes and nullable_backend == "pyarrow":
+        if use_nullable_dtypes and dtype_backend == "pyarrow":
             pa = import_optional_dependency("pyarrow")
             if isinstance(result, np.ndarray):
                 result = ArrowExtensionArray(pa.array(result, from_pandas=True))

pandas/io/parsers/readers.py

@@ -399,9 +399,9 @@
     implementation, even if no nulls are present.
 
     The nullable dtype implementation can be configured by calling
-    ``pd.set_option("mode.nullable_backend", "pandas")`` to use
+    ``pd.set_option("mode.dtype_backend", "pandas")`` to use
     numpy-backed nullable dtypes or
-    ``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
+    ``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
     pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
 
     .. versionadded:: 2.0
@@ -561,12 +561,12 @@ def _read(
             )
     elif (
         kwds.get("use_nullable_dtypes", False)
-        and get_option("mode.nullable_backend") == "pyarrow"
+        and get_option("mode.dtype_backend") == "pyarrow"
         and kwds.get("engine") == "c"
     ):
         raise NotImplementedError(
             f"use_nullable_dtypes=True and engine={kwds['engine']} with "
-            "mode.nullable_backend set to 'pyarrow' is not implemented."
+            "mode.dtype_backend set to 'pyarrow' is not implemented."
         )
     else:
         chunksize = validate_integer("chunksize", chunksize, 1)

pandas/tests/frame/methods/test_convert_dtypes.py

@@ -44,7 +44,7 @@ def test_convert_dtypes_retain_column_names(self):
         tm.assert_index_equal(result.columns, df.columns)
         assert result.columns.name == "cols"
 
-    def test_pyarrow_nullable_backend(self):
+    def test_pyarrow_dtype_backend(self):
         pa = pytest.importorskip("pyarrow")
         df = pd.DataFrame(
             {
@@ -56,7 +56,7 @@ def test_pyarrow_nullable_backend(self):
                 "f": pd.Series(pd.timedelta_range("1D", periods=3)),
             }
         )
-        with pd.option_context("mode.nullable_backend", "pyarrow"):
+        with pd.option_context("mode.dtype_backend", "pyarrow"):
             result = df.convert_dtypes()
         expected = pd.DataFrame(
             {
@@ -90,14 +90,14 @@ def test_pyarrow_nullable_backend(self):
         )
         tm.assert_frame_equal(result, expected)
 
-    def test_pyarrow_nullable_backend_already_pyarrow(self):
+    def test_pyarrow_dtype_backend_already_pyarrow(self):
         pytest.importorskip("pyarrow")
         expected = pd.DataFrame([1, 2, 3], dtype="int64[pyarrow]")
-        with pd.option_context("mode.nullable_backend", "pyarrow"):
+        with pd.option_context("mode.dtype_backend", "pyarrow"):
             result = expected.convert_dtypes()
         tm.assert_frame_equal(result, expected)
 
-    def test_pyarrow_nullable_backend_from_pandas_nullable(self):
+    def test_pyarrow_dtype_backend_from_pandas_nullable(self):
         pa = pytest.importorskip("pyarrow")
         df = pd.DataFrame(
             {
@@ -107,7 +107,7 @@ def test_pyarrow_nullable_backend_from_pandas_nullable(self):
                 "d": pd.Series([None, 100.5, 200], dtype="Float64"),
             }
         )
-        with pd.option_context("mode.nullable_backend", "pyarrow"):
+        with pd.option_context("mode.dtype_backend", "pyarrow"):
             result = df.convert_dtypes()
         expected = pd.DataFrame(
             {

pandas/tests/io/excel/test_readers.py

@@ -537,10 +537,10 @@ def test_reader_dtype_str(self, read_ext, dtype, expected):
         tm.assert_frame_equal(actual, expected)
 
     @pytest.mark.parametrize(
-        "nullable_backend",
+        "dtype_backend",
         ["pandas", pytest.param("pyarrow", marks=td.skip_if_no("pyarrow"))],
     )
-    def test_use_nullable_dtypes(self, read_ext, nullable_backend):
+    def test_use_nullable_dtypes(self, read_ext, dtype_backend):
         # GH#36712
         if read_ext in (".xlsb", ".xls"):
             pytest.skip(f"No engine for filetype: '{read_ext}'")
@@ -561,11 +561,11 @@ def test_use_nullable_dtypes(self, read_ext, nullable_backend):
         )
         with tm.ensure_clean(read_ext) as file_path:
             df.to_excel(file_path, "test", index=False)
-            with pd.option_context("mode.nullable_backend", nullable_backend):
+            with pd.option_context("mode.dtype_backend", dtype_backend):
                 result = pd.read_excel(
                     file_path, sheet_name="test", use_nullable_dtypes=True
                 )
-        if nullable_backend == "pyarrow":
+        if dtype_backend == "pyarrow":
             import pyarrow as pa
 
             from pandas.arrays import ArrowExtensionArray

pandas/tests/io/parser/dtypes/test_dtypes_basic.py

@@ -498,7 +498,7 @@ def test_use_nullable_dtypes_pyarrow_backend(all_parsers, request):
 1,2.5,True,a,,,,,12-31-2019,
 3,4.5,False,b,6,7.5,True,a,12-31-2019,
 """
-    with pd.option_context("mode.nullable_backend", "pyarrow"):
+    with pd.option_context("mode.dtype_backend", "pyarrow"):
         if engine == "c":
             request.node.add_marker(
                 pytest.mark.xfail(

pandas/tests/io/test_orc.py

@@ -309,9 +309,9 @@ def test_orc_use_nullable_dtypes_pandas_backend_not_supported(dirpath):
     input_file = os.path.join(dirpath, "TestOrcFile.emptyFile.orc")
     with pytest.raises(
         NotImplementedError,
-        match="mode.nullable_backend set to pandas is not implemented.",
+        match="mode.dtype_backend set to pandas is not implemented.",
     ):
-        with pd.option_context("mode.nullable_backend", "pandas"):
+        with pd.option_context("mode.dtype_backend", "pandas"):
             read_orc(input_file, use_nullable_dtypes=True)
 
 
@@ -337,7 +337,7 @@ def test_orc_use_nullable_dtypes_pyarrow_backend():
         }
     )
     bytes_data = df.copy().to_orc()
-    with pd.option_context("mode.nullable_backend", "pyarrow"):
+    with pd.option_context("mode.dtype_backend", "pyarrow"):
         result = read_orc(BytesIO(bytes_data), use_nullable_dtypes=True)
     expected = pd.DataFrame(
         {

pandas/tests/io/test_parquet.py

@@ -1037,7 +1037,7 @@ def test_read_use_nullable_types_pyarrow_config(self, pa, df_full):
             pd.ArrowDtype(pyarrow.timestamp(unit="us", tz="Europe/Brussels"))
         )
 
-        with pd.option_context("mode.nullable_backend", "pyarrow"):
+        with pd.option_context("mode.dtype_backend", "pyarrow"):
             check_round_trip(
                 df,
                 engine=pa,