Added DeprecationWarning to Series.str.__iter__

Author: SaturnFromTitan

doc/source/whatsnew/v0.12.0.rst

@@ -417,6 +417,7 @@ Bug fixes
     original ``Series`` or ``NaN``. For example,
 
     .. ipython:: python
+        :okwarning:
 
         strs = 'go', 'bow', 'joe', 'slow'
         ds = pd.Series(strs)

doc/source/whatsnew/v1.0.0.rst

@@ -356,6 +356,31 @@ When :class:`Categorical` contains ``np.nan``,
 
    pd.Categorical([1, 2, np.nan], ordered=True).min()
 
+Avoid iterating over ``Series.str``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Iterating over the `.str` accessor of :class:`Series` will now raise a
+ `DeprecationWarning` and be removed in future releases (:issue:`28277`).
+Since no clear purpose of this feature could be derived, there will be
+ no replacement.
+
+.. code-block:: ipython
+
+   In [1]: s = pd.Series(["a", "ab"])
+   In [2]: s
+   Out[2]:
+       0     a
+       1    ab
+   dtype: object
+
+   In [3]: generator = (_ for _ in s.str)
+   In [4]: next(generator)
+   Out[4]:
+   DeprecationWarning: Columnar iteration over characters will be deprecated in future releases.
+       0    a
+       1    a
+   dtype: object
+
 .. _whatsnew_1000.api_breaking.deps:
 
 Increased minimum versions for dependencies

pandas/core/strings.py

@@ -2093,6 +2093,11 @@ def __getitem__(self, key):
             return self.get(key)
 
     def __iter__(self):
+        warnings.warn(
+            "Columnar iteration over characters will be deprecated in future releases.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         i = 0
         g = self.get(i)
         while g.notna().any():

pandas/tests/test_strings.py

@@ -327,17 +327,18 @@ def test_iter(self):
         strs = "google", "wikimedia", "wikipedia", "wikitravel"
         ds = Series(strs)
 
-        for s in ds.str:
-            # iter must yield a Series
-            assert isinstance(s, Series)
+        with tm.assert_produces_warning(DeprecationWarning):
+            for s in ds.str:
+                # iter must yield a Series
+                assert isinstance(s, Series)
 
-            # indices of each yielded Series should be equal to the index of
-            # the original Series
-            tm.assert_index_equal(s.index, ds.index)
+                # indices of each yielded Series should be equal to the index of
+                # the original Series
+                tm.assert_index_equal(s.index, ds.index)
 
-            for el in s:
-                # each element of the series is either a basestring/str or nan
-                assert isinstance(el, str) or isna(el)
+                for el in s:
+                    # each element of the series is either a basestring/str or nan
+                    assert isinstance(el, str) or isna(el)
 
         # desired behavior is to iterate until everything would be nan on the
         # next iter so make sure the last element of the iterator was 'l' in
@@ -349,8 +350,9 @@ def test_iter_empty(self):
 
         i, s = 100, 1
 
-        for i, s in enumerate(ds.str):
-            pass
+        with tm.assert_produces_warning(DeprecationWarning):
+            for i, s in enumerate(ds.str):
+                pass
 
         # nothing to iterate over so nothing defined values should remain
         # unchanged
@@ -360,8 +362,9 @@ def test_iter_empty(self):
     def test_iter_single_element(self):
         ds = Series(["a"])
 
-        for i, s in enumerate(ds.str):
-            pass
+        with tm.assert_produces_warning(DeprecationWarning):
+            for i, s in enumerate(ds.str):
+                pass
 
         assert not i
         tm.assert_series_equal(ds, s)
@@ -371,8 +374,9 @@ def test_iter_object_try_string(self):
 
         i, s = 100, "h"
 
-        for i, s in enumerate(ds.str):
-            pass
+        with tm.assert_produces_warning(DeprecationWarning):
+            for i, s in enumerate(ds.str):
+                pass
 
         assert i == 100
         assert s == "h"