Skip to content

Commit fabdd5d

Browse files
authored
REF: Rename mode.nullable_backend to mode.dtype_backend (#50291)
1 parent bf7960d commit fabdd5d

File tree

15 files changed

+55
-54
lines changed

15 files changed

+55
-54
lines changed

doc/source/whatsnew/v2.0.0.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,10 @@ The available extras, found in the :ref:`installation guide<install.dependencies
2828
``[all, performance, computation, timezone, fss, aws, gcp, excel, parquet, feather, hdf5, spss, postgresql, mysql,
2929
sql-other, html, xml, plot, output_formatting, clipboard, compression, test]`` (:issue:`39164`).
3030

31-
.. _whatsnew_200.enhancements.io_use_nullable_dtypes_and_nullable_backend:
31+
.. _whatsnew_200.enhancements.io_use_nullable_dtypes_and_dtype_backend:
3232

33-
Configuration option, ``mode.nullable_backend``, to return pyarrow-backed dtypes
34-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
33+
Configuration option, ``mode.dtype_backend``, to return pyarrow-backed dtypes
34+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3535

3636
The ``use_nullable_dtypes`` keyword argument has been expanded to the following functions to enable automatic conversion to nullable dtypes (:issue:`36712`)
3737

@@ -41,7 +41,7 @@ The ``use_nullable_dtypes`` keyword argument has been expanded to the following
4141
* :func:`read_sql_query`
4242
* :func:`read_sql_table`
4343

44-
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
44+
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
4545
to select the nullable dtypes implementation.
4646

4747
* :func:`read_csv` (with ``engine="pyarrow"`` or ``engine="python"``)
@@ -50,12 +50,12 @@ to select the nullable dtypes implementation.
5050
* :func:`read_orc`
5151

5252

53-
And the following methods will also utilize the ``mode.nullable_backend`` option.
53+
And the following methods will also utilize the ``mode.dtype_backend`` option.
5454

5555
* :meth:`DataFrame.convert_dtypes`
5656
* :meth:`Series.convert_dtypes`
5757

58-
By default, ``mode.nullable_backend`` is set to ``"pandas"`` to return existing, numpy-backed nullable dtypes, but it can also
58+
By default, ``mode.dtype_backend`` is set to ``"pandas"`` to return existing, numpy-backed nullable dtypes, but it can also
5959
be set to ``"pyarrow"`` to return pyarrow-backed, nullable :class:`ArrowDtype` (:issue:`48957`, :issue:`49997`).
6060

6161
.. ipython:: python
@@ -65,12 +65,12 @@ be set to ``"pyarrow"`` to return pyarrow-backed, nullable :class:`ArrowDtype` (
6565
1,2.5,True,a,,,,,
6666
3,4.5,False,b,6,7.5,True,a,
6767
""")
68-
with pd.option_context("mode.nullable_backend", "pandas"):
68+
with pd.option_context("mode.dtype_backend", "pandas"):
6969
df = pd.read_csv(data, use_nullable_dtypes=True)
7070
df.dtypes
7171
7272
data.seek(0)
73-
with pd.option_context("mode.nullable_backend", "pyarrow"):
73+
with pd.option_context("mode.dtype_backend", "pyarrow"):
7474
df_pyarrow = pd.read_csv(data, use_nullable_dtypes=True, engine="pyarrow")
7575
df_pyarrow.dtypes
7676

pandas/core/config_init.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -539,10 +539,11 @@ def use_inf_as_na_cb(key) -> None:
539539
The default storage for StringDtype.
540540
"""
541541

542-
nullable_backend_doc = """
542+
dtype_backend_doc = """
543543
: string
544-
The nullable dtype implementation to return.
545-
Available options: 'pandas', 'pyarrow', the default is 'pandas'.
544+
The nullable dtype implementation to return. Only applicable to certain
545+
operations where documented. Available options: 'pandas', 'pyarrow',
546+
the default is 'pandas'.
546547
"""
547548

548549
with cf.config_prefix("mode"):
@@ -553,9 +554,9 @@ def use_inf_as_na_cb(key) -> None:
553554
validator=is_one_of_factory(["python", "pyarrow"]),
554555
)
555556
cf.register_option(
556-
"nullable_backend",
557+
"dtype_backend",
557558
"pandas",
558-
nullable_backend_doc,
559+
dtype_backend_doc,
559560
validator=is_one_of_factory(["pandas", "pyarrow"]),
560561
)
561562

pandas/core/dtypes/cast.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -961,7 +961,7 @@ def convert_dtypes(
961961
convert_boolean: bool = True,
962962
convert_floating: bool = True,
963963
infer_objects: bool = False,
964-
nullable_backend: Literal["pandas", "pyarrow"] = "pandas",
964+
dtype_backend: Literal["pandas", "pyarrow"] = "pandas",
965965
) -> DtypeObj:
966966
"""
967967
Convert objects to best possible type, and optionally,
@@ -983,7 +983,7 @@ def convert_dtypes(
983983
infer_objects : bool, defaults False
984984
Whether to also infer objects to float/int if possible. Is only hit if the
985985
object array contains pd.NA.
986-
nullable_backend : str, default "pandas"
986+
dtype_backend : str, default "pandas"
987987
Nullable dtype implementation to use.
988988
989989
* "pandas" returns numpy-backed nullable types
@@ -1076,7 +1076,7 @@ def convert_dtypes(
10761076
else:
10771077
inferred_dtype = input_array.dtype
10781078

1079-
if nullable_backend == "pyarrow":
1079+
if dtype_backend == "pyarrow":
10801080
from pandas.core.arrays.arrow.array import to_pyarrow_type
10811081
from pandas.core.arrays.arrow.dtype import ArrowDtype
10821082
from pandas.core.arrays.string_ import StringDtype

pandas/core/generic.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6432,9 +6432,9 @@ def convert_dtypes(
64326432
64336433
.. versionadded:: 2.0
64346434
The nullable dtype implementation can be configured by calling
6435-
``pd.set_option("mode.nullable_backend", "pandas")`` to use
6435+
``pd.set_option("mode.dtype_backend", "pandas")`` to use
64366436
numpy-backed nullable dtypes or
6437-
``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
6437+
``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
64386438
pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
64396439
64406440
Examples

pandas/core/series.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5410,15 +5410,15 @@ def _convert_dtypes(
54105410
input_series = input_series.copy()
54115411

54125412
if convert_string or convert_integer or convert_boolean or convert_floating:
5413-
nullable_backend = get_option("mode.nullable_backend")
5413+
dtype_backend = get_option("mode.dtype_backend")
54145414
inferred_dtype = convert_dtypes(
54155415
input_series._values,
54165416
convert_string,
54175417
convert_integer,
54185418
convert_boolean,
54195419
convert_floating,
54205420
infer_objects,
5421-
nullable_backend,
5421+
dtype_backend,
54225422
)
54235423
result = input_series.astype(inferred_dtype)
54245424
else:

pandas/io/orc.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -59,16 +59,16 @@ def read_orc(
5959
for the resulting DataFrame.
6060
6161
The nullable dtype implementation can be configured by calling
62-
``pd.set_option("mode.nullable_backend", "pandas")`` to use
62+
``pd.set_option("mode.dtype_backend", "pandas")`` to use
6363
numpy-backed nullable dtypes or
64-
``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
64+
``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
6565
pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
6666
6767
.. versionadded:: 2.0.0
6868
6969
.. note
7070
71-
Currently only ``mode.nullable_backend`` set to ``"pyarrow"`` is supported.
71+
Currently only ``mode.dtype_backend`` set to ``"pyarrow"`` is supported.
7272
7373
**kwargs
7474
Any additional kwargs are passed to pyarrow.
@@ -90,10 +90,10 @@ def read_orc(
9090
orc_file = orc.ORCFile(handles.handle)
9191
pa_table = orc_file.read(columns=columns, **kwargs)
9292
if use_nullable_dtypes:
93-
nullable_backend = get_option("mode.nullable_backend")
94-
if nullable_backend != "pyarrow":
93+
dtype_backend = get_option("mode.dtype_backend")
94+
if dtype_backend != "pyarrow":
9595
raise NotImplementedError(
96-
f"mode.nullable_backend set to {nullable_backend} is not implemented."
96+
f"mode.dtype_backend set to {dtype_backend} is not implemented."
9797
)
9898
df = DataFrame(
9999
{

pandas/io/parquet.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -222,12 +222,12 @@ def read(
222222
) -> DataFrame:
223223
kwargs["use_pandas_metadata"] = True
224224

225-
nullable_backend = get_option("mode.nullable_backend")
225+
dtype_backend = get_option("mode.dtype_backend")
226226
to_pandas_kwargs = {}
227227
if use_nullable_dtypes:
228228
import pandas as pd
229229

230-
if nullable_backend == "pandas":
230+
if dtype_backend == "pandas":
231231
mapping = {
232232
self.api.int8(): pd.Int8Dtype(),
233233
self.api.int16(): pd.Int16Dtype(),
@@ -257,9 +257,9 @@ def read(
257257
pa_table = self.api.parquet.read_table(
258258
path_or_handle, columns=columns, **kwargs
259259
)
260-
if nullable_backend == "pandas":
260+
if dtype_backend == "pandas":
261261
result = pa_table.to_pandas(**to_pandas_kwargs)
262-
elif nullable_backend == "pyarrow":
262+
elif dtype_backend == "pyarrow":
263263
result = DataFrame(
264264
{
265265
col_name: arrays.ArrowExtensionArray(pa_col)
@@ -509,9 +509,9 @@ def read_parquet(
509509
.. versionadded:: 1.2.0
510510
511511
The nullable dtype implementation can be configured by calling
512-
``pd.set_option("mode.nullable_backend", "pandas")`` to use
512+
``pd.set_option("mode.dtype_backend", "pandas")`` to use
513513
numpy-backed nullable dtypes or
514-
``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
514+
``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
515515
pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
516516
517517
.. versionadded:: 2.0.0

pandas/io/parsers/arrow_parser_wrapper.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ def read(self) -> DataFrame:
151151
)
152152
if (
153153
self.kwds["use_nullable_dtypes"]
154-
and get_option("mode.nullable_backend") == "pyarrow"
154+
and get_option("mode.dtype_backend") == "pyarrow"
155155
):
156156
frame = DataFrame(
157157
{

pandas/io/parsers/base_parser.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -712,7 +712,7 @@ def _infer_types(
712712
use_nullable_dtypes: Literal[True] | Literal[False] = (
713713
self.use_nullable_dtypes and no_dtype_specified
714714
)
715-
nullable_backend = get_option("mode.nullable_backend")
715+
dtype_backend = get_option("mode.dtype_backend")
716716
result: ArrayLike
717717

718718
if try_num_bool and is_object_dtype(values.dtype):
@@ -770,7 +770,7 @@ def _infer_types(
770770
if inferred_type != "datetime":
771771
result = StringDtype().construct_array_type()._from_sequence(values)
772772

773-
if use_nullable_dtypes and nullable_backend == "pyarrow":
773+
if use_nullable_dtypes and dtype_backend == "pyarrow":
774774
pa = import_optional_dependency("pyarrow")
775775
if isinstance(result, np.ndarray):
776776
result = ArrowExtensionArray(pa.array(result, from_pandas=True))

pandas/io/parsers/readers.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -399,9 +399,9 @@
399399
implementation, even if no nulls are present.
400400
401401
The nullable dtype implementation can be configured by calling
402-
``pd.set_option("mode.nullable_backend", "pandas")`` to use
402+
``pd.set_option("mode.dtype_backend", "pandas")`` to use
403403
numpy-backed nullable dtypes or
404-
``pd.set_option("mode.nullable_backend", "pyarrow")`` to use
404+
``pd.set_option("mode.dtype_backend", "pyarrow")`` to use
405405
pyarrow-backed nullable dtypes (using ``pd.ArrowDtype``).
406406
407407
.. versionadded:: 2.0
@@ -561,12 +561,12 @@ def _read(
561561
)
562562
elif (
563563
kwds.get("use_nullable_dtypes", False)
564-
and get_option("mode.nullable_backend") == "pyarrow"
564+
and get_option("mode.dtype_backend") == "pyarrow"
565565
and kwds.get("engine") == "c"
566566
):
567567
raise NotImplementedError(
568568
f"use_nullable_dtypes=True and engine={kwds['engine']} with "
569-
"mode.nullable_backend set to 'pyarrow' is not implemented."
569+
"mode.dtype_backend set to 'pyarrow' is not implemented."
570570
)
571571
else:
572572
chunksize = validate_integer("chunksize", chunksize, 1)

pandas/tests/frame/methods/test_convert_dtypes.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ def test_convert_dtypes_retain_column_names(self):
4444
tm.assert_index_equal(result.columns, df.columns)
4545
assert result.columns.name == "cols"
4646

47-
def test_pyarrow_nullable_backend(self):
47+
def test_pyarrow_dtype_backend(self):
4848
pa = pytest.importorskip("pyarrow")
4949
df = pd.DataFrame(
5050
{
@@ -56,7 +56,7 @@ def test_pyarrow_nullable_backend(self):
5656
"f": pd.Series(pd.timedelta_range("1D", periods=3)),
5757
}
5858
)
59-
with pd.option_context("mode.nullable_backend", "pyarrow"):
59+
with pd.option_context("mode.dtype_backend", "pyarrow"):
6060
result = df.convert_dtypes()
6161
expected = pd.DataFrame(
6262
{
@@ -90,14 +90,14 @@ def test_pyarrow_nullable_backend(self):
9090
)
9191
tm.assert_frame_equal(result, expected)
9292

93-
def test_pyarrow_nullable_backend_already_pyarrow(self):
93+
def test_pyarrow_dtype_backend_already_pyarrow(self):
9494
pytest.importorskip("pyarrow")
9595
expected = pd.DataFrame([1, 2, 3], dtype="int64[pyarrow]")
96-
with pd.option_context("mode.nullable_backend", "pyarrow"):
96+
with pd.option_context("mode.dtype_backend", "pyarrow"):
9797
result = expected.convert_dtypes()
9898
tm.assert_frame_equal(result, expected)
9999

100-
def test_pyarrow_nullable_backend_from_pandas_nullable(self):
100+
def test_pyarrow_dtype_backend_from_pandas_nullable(self):
101101
pa = pytest.importorskip("pyarrow")
102102
df = pd.DataFrame(
103103
{
@@ -107,7 +107,7 @@ def test_pyarrow_nullable_backend_from_pandas_nullable(self):
107107
"d": pd.Series([None, 100.5, 200], dtype="Float64"),
108108
}
109109
)
110-
with pd.option_context("mode.nullable_backend", "pyarrow"):
110+
with pd.option_context("mode.dtype_backend", "pyarrow"):
111111
result = df.convert_dtypes()
112112
expected = pd.DataFrame(
113113
{

pandas/tests/io/excel/test_readers.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -537,10 +537,10 @@ def test_reader_dtype_str(self, read_ext, dtype, expected):
537537
tm.assert_frame_equal(actual, expected)
538538

539539
@pytest.mark.parametrize(
540-
"nullable_backend",
540+
"dtype_backend",
541541
["pandas", pytest.param("pyarrow", marks=td.skip_if_no("pyarrow"))],
542542
)
543-
def test_use_nullable_dtypes(self, read_ext, nullable_backend):
543+
def test_use_nullable_dtypes(self, read_ext, dtype_backend):
544544
# GH#36712
545545
if read_ext in (".xlsb", ".xls"):
546546
pytest.skip(f"No engine for filetype: '{read_ext}'")
@@ -561,11 +561,11 @@ def test_use_nullable_dtypes(self, read_ext, nullable_backend):
561561
)
562562
with tm.ensure_clean(read_ext) as file_path:
563563
df.to_excel(file_path, "test", index=False)
564-
with pd.option_context("mode.nullable_backend", nullable_backend):
564+
with pd.option_context("mode.dtype_backend", dtype_backend):
565565
result = pd.read_excel(
566566
file_path, sheet_name="test", use_nullable_dtypes=True
567567
)
568-
if nullable_backend == "pyarrow":
568+
if dtype_backend == "pyarrow":
569569
import pyarrow as pa
570570

571571
from pandas.arrays import ArrowExtensionArray

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -498,7 +498,7 @@ def test_use_nullable_dtypes_pyarrow_backend(all_parsers, request):
498498
1,2.5,True,a,,,,,12-31-2019,
499499
3,4.5,False,b,6,7.5,True,a,12-31-2019,
500500
"""
501-
with pd.option_context("mode.nullable_backend", "pyarrow"):
501+
with pd.option_context("mode.dtype_backend", "pyarrow"):
502502
if engine == "c":
503503
request.node.add_marker(
504504
pytest.mark.xfail(

pandas/tests/io/test_orc.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -309,9 +309,9 @@ def test_orc_use_nullable_dtypes_pandas_backend_not_supported(dirpath):
309309
input_file = os.path.join(dirpath, "TestOrcFile.emptyFile.orc")
310310
with pytest.raises(
311311
NotImplementedError,
312-
match="mode.nullable_backend set to pandas is not implemented.",
312+
match="mode.dtype_backend set to pandas is not implemented.",
313313
):
314-
with pd.option_context("mode.nullable_backend", "pandas"):
314+
with pd.option_context("mode.dtype_backend", "pandas"):
315315
read_orc(input_file, use_nullable_dtypes=True)
316316

317317

@@ -337,7 +337,7 @@ def test_orc_use_nullable_dtypes_pyarrow_backend():
337337
}
338338
)
339339
bytes_data = df.copy().to_orc()
340-
with pd.option_context("mode.nullable_backend", "pyarrow"):
340+
with pd.option_context("mode.dtype_backend", "pyarrow"):
341341
result = read_orc(BytesIO(bytes_data), use_nullable_dtypes=True)
342342
expected = pd.DataFrame(
343343
{

pandas/tests/io/test_parquet.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1037,7 +1037,7 @@ def test_read_use_nullable_types_pyarrow_config(self, pa, df_full):
10371037
pd.ArrowDtype(pyarrow.timestamp(unit="us", tz="Europe/Brussels"))
10381038
)
10391039

1040-
with pd.option_context("mode.nullable_backend", "pyarrow"):
1040+
with pd.option_context("mode.dtype_backend", "pyarrow"):
10411041
check_round_trip(
10421042
df,
10431043
engine=pa,

0 commit comments

Comments
 (0)