DOC: add storage and na_value to StringDtype reference page (#63104)

Author: jorisvandenbossche

ci/code_checks.sh

@@ -79,6 +79,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
  -i "pandas.api.typing.DataFrameGroupBy.plot PR02" \
  -i "pandas.api.typing.SeriesGroupBy.plot PR02" \
  -i "pandas.api.typing.Resampler.quantile PR01,PR07" \
+ -i "pandas.StringDtype.storage SA01" \
+ -i "pandas.StringDtype.na_value SA01" \
  -i "pandas.tseries.offsets.BDay PR02,SA01" \
  -i "pandas.tseries.offsets.BHalfYearBegin.is_on_offset GL08" \
  -i "pandas.tseries.offsets.BHalfYearBegin.n GL08" \

doc/source/reference/arrays.rst

@@ -637,6 +637,8 @@ with a bool :class:`numpy.ndarray`.
  DatetimeTZDtype.tz
  PeriodDtype.freq
  IntervalDtype.subtype
+ StringDtype.storage
+ StringDtype.na_value
 
 *********
 Utilities

doc/source/user_guide/text.rst

@@ -753,7 +753,10 @@ Differences in behavior will be primarily due to the kind of NA value.
 The four :class:`StringDtype` variants
 ======================================
 
-There are four :class:`StringDtype` variants that are available to users.
+There are four :class:`StringDtype` variants that are available to users,
+controlled by the ``storage`` and ``na_value`` parameters of :class:`StringDtype`.
+At runtime, these can be checked via the :attr:`StringDtype.storage`
+and :attr:`StringDtype.na_value` attributes.
 
 Python storage with ``np.nan`` values
 -------------------------------------

pandas/core/arrays/string_.py

@@ -119,7 +119,8 @@ class StringDtype(StorageExtensionDtype):
 
  Attributes
  ----------
- None
+ storage
+ na_value
 
  Methods
  -------
@@ -149,8 +150,40 @@ def name(self) -> str: # type: ignore[override]
 # follows NumPy semantics, which uses nan.
 @property
 defna_value(self) ->libmissing.NAType|float: # type: ignore[override]
+"""
+ The missing value representation for this dtype.
+
+ This value indicates which missing value semantics are used by this dtype.
+ Returns ``np.nan`` for the default string dtype with NumPy semantics,
+ and ``pd.NA`` for the opt-in string dtype with pandas NA semantics.
+
+ Examples
+ --------
+ >>> ser = pd.Series(["a", "b"])
+ >>> ser.dtype
+ <StringDtype(na_value=nan)>
+ >>> ser.dtype.na_value
+ nan
+ """
 returnself._na_value
 
+@property
+defstorage(self) ->str:
+"""
+ The storage backend for this dtype.
+
+ Can be either "pyarrow" or "python".
+
+ Examples
+ --------
+ >>> ser = pd.Series(["a", "b"])
+ >>> ser.dtype
+ <StringDtype(na_value=nan)>
+ >>> ser.dtype.storage
+ 'pyarrow'
+ """
+returnself._storage
+
 _metadata= ("storage", "_na_value") # type: ignore[assignment]
 
 def__init__(
@@ -185,7 +218,7 @@ def __init__(
 elifna_valueisnotlibmissing.NA:
 raiseValueError(f"'na_value' must be np.nan or pd.NA, got {na_value}")
 
-self.storage=cast(str, storage)
+self._storage=cast(str, storage)
 self._na_value=na_value
 
 def__repr__(self) ->str:
@@ -211,7 +244,7 @@ def __eq__(self, other: object) -> bool:
 
 def__setstate__(self, state: MutableMapping[str, Any]) ->None:
 # back-compat for pandas < 2.3, where na_value did not yet exist
-self.storage=state.pop("storage", "python")
+self._storage=state.pop("storage", "python")
 self._na_value=state.pop("_na_value", libmissing.NA)
 
 def__hash__(self) ->int:
@@ -306,7 +339,7 @@ def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
 # if both python and pyarrow storage -> priority to pyarrow
 storage="pyarrow"
 else:
-storage=next(iter(storages))# type: ignore[assignment]
+storage=next(iter(storages))
 
 na_value: libmissing.NAType|float
 iflen(na_values) ==2:

pandas/core/dtypes/base.py

@@ -457,8 +457,8 @@ class StorageExtensionDtype(ExtensionDtype):
 name: str
 _metadata= ("storage",)
 
-def__init__(self, storage: str|None=None) ->None:
-self.storage=storage
+def__init__(self, storage: str) ->None:
+self._storage=storage
 
 def__repr__(self) ->str:
 returnf"{self.name}[{self.storage}]"
@@ -479,6 +479,10 @@ def __hash__(self) -> int:
 defna_value(self) ->libmissing.NAType:
 returnlibmissing.NA
 
+@property
+defstorage(self) ->str:
+returnself._storage
+
 
 @set_module("pandas.api.extensions")
 defregister_extension_dtype(cls: type_t[ExtensionDtypeT]) ->type_t[ExtensionDtypeT]: