REF: Dispatch string methods to ExtensionArray

pandas/core/arrays/categorical.py

@@ -2316,6 +2316,9 @@ def replace(self, to_replace, value, inplace: bool = False):
     # ------------------------------------------------------------------------
     # String methods interface
     def _str_map(self, f, na_value=np.nan, dtype=np.dtype(object)):
+        # Optimization to apply the callable `f` to the categories once
+        # and rebuild the result by `take`ing from the result with the codes.
+        # Returns the same type as the object-dtype impelmentation though.
         from pandas.core.arrays import PandasArray
 
         categories = self.categories

pandas/core/strings/__init__.py

@@ -1,3 +1,31 @@
+"""
+Implementation of pandas.Series.str and its interface.
+
+* strings.accessor.StringMethods : Accessor for Series.str
+* strings.base.BaseStringArrayMethods: Mixin ABC for EAs to implement str methods
+
+Most methods on the StringMethods accessor follow the pattern:
+
+    1. extract the array from the series (or index)
+    2. Call that array's impelmentation of the string method
+    3. Wrap the result (in a Series, index, or DataFrame)
+
+Pandas extension arrays implementing string methods should inherit from
+pandas.core.strings.base.BaseStringArrayMethods. This is an ABC defining
+the various string methods. To avoid namespace clashes and pollution,
+these are prefixed with `_str_`. So ``Series.str.upper()`` calls
+``Series.array._str_upper()``. The interface isn't currently public
+to other string extension arrays.
+"""
+# Pandas current implementation is in ObjectStringArrayMixin. This is designed
+# to work on object-dtype ndarrays.
+#
+# BaseStringArrayMethods
+#  - ObjectStringArrayMixin
+#     - StringArray
+#     - PandasArray
+#     - Categorical
+
 from .accessor import StringMethods
 from .base import BaseStringArrayMethods
 

pandas/core/strings/accessor.py

@@ -140,6 +140,8 @@ class StringMethods(NoNewAttributesMixin):
     dtype: object
     """
 
+    # Note: see the docstring in pandas.core.strings.__init__
+    # for an explanation of the implementation.
     # TODO: Dispatch all the methods
     # Currently the following are not dispatched to the array
     # * cat

pandas/core/strings/base.py

@@ -10,8 +10,8 @@ class BaseStringArrayMethods(abc.ABC):
     """
     Base class for extension arrays implementing string methods.
 
-    This is our ExtensionArrays can override the implementation of
-    Series.str.<method>. We don't currenlty expect this to work with
+    This is where our ExtensionArrays can override the implementation of
+    Series.str.<method>. We don't expect this to work with
     3rd-party extension arrays.
 
     * User calls Series.str.<method>