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)

0 commit comments

Comments
 (0)