Added FutureWarning to Series.str.__iter__ (pandas-dev#29909)

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

@@ -467,6 +467,7 @@ Other API changes
 - :meth:`Series.dropna` has dropped its ``**kwargs`` argument in favor of a single ``how`` parameter.
   Supplying anything else than ``how`` to ``**kwargs`` raised a ``TypeError`` previously (:issue:`29388`)
 - When testing pandas, the new minimum required version of pytest is 5.0.1 (:issue:`29664`)
+- :meth:`Series.str.__iter__` was deprecated and will be removed in future releases (:issue:`28277`).
 
 
 .. _whatsnew_1000.api.documentation:

pandas/core/strings.py

@@ -2091,6 +2091,11 @@ def __getitem__(self, key):
             return self.get(key)
 
     def __iter__(self):
+        warnings.warn(
+            "Columnar iteration over characters will be deprecated in future releases.",
+            FutureWarning,
+            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(FutureWarning):
+            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(FutureWarning):
+            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(FutureWarning):
+            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(FutureWarning):
+            for i, s in enumerate(ds.str):
+                pass
 
         assert i == 100
         assert s == "h"