Restrict legal argument combinations; no nesting

Author: h-vetinari

doc/source/text.rst

@@ -305,18 +305,20 @@ The same alignment can be used when ``others`` is a ``DataFrame``:
 Concatenating a Series and many objects into a Series
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-All list-likes (including iterators, ``dict``-views, etc.) can be arbitrarily combined in a list-like container:
+All one-dimensional list-likes can be arbitrarily combined in a list-like container (including iterators, ``dict``-views, etc.):
 
 .. ipython:: python
 
-    s.str.cat([u, t.values, ['A', 'B', 'C', 'D'], d.values, f], na_rep='-')
+    s
+    u
+    s.str.cat([u, pd.Index(u.values), ['A', 'B', 'C', 'D']], na_rep='-')
 
-All elements must match in length to the calling ``Series``, except those having an index if ``join`` is not None:
+All elements must match in length to the calling ``Series`` (or ``Index``), except those having an index if ``join`` is not None:
 
 .. ipython:: python
 
-    s.str.cat([u, v, ['A', 'B', 'C', 'D'], d.values, f.loc[[1]]],
-               join='outer', na_rep='-')
+    v
+    s.str.cat([u, v, ['A', 'B', 'C', 'D']], join='outer', na_rep='-')
 
 If using ``join='right'`` on a list of ``others`` that contains different indexes,
 the union of these indexes will be used as the basis for the final concatenation:

doc/source/whatsnew/v0.23.0.txt

@@ -314,8 +314,9 @@ The :func:`DataFrame.assign` now accepts dependent keyword arguments for python
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Previously, :meth:`Series.str.cat` did not -- in contrast to most of ``pandas`` -- align :class:`Series` on their index before concatenation (see :issue:`18657`).
-The method has now gained a keyword ``join`` to control the manner of alignment. In v.0.23 it will default to None (meaning no alignment), but this default will change
-to ``'left'`` in a future version of pandas.
+The method has now gained a keyword ``join`` to control the manner of alignment, see examples below and in :ref:`here <text.concatenate>`.
+
+In v.0.23 `join` will default to None (meaning no alignment), but this default will change to ``'left'`` in a future version of pandas.
 
 .. ipython:: python
 
@@ -324,12 +325,9 @@ to ``'left'`` in a future version of pandas.
     s.str.cat(t)
     s.str.cat(t, join='left', na_rep='-')
 
-In particular, ``others`` does not need to be of the same length as the calling ``Series`` (if both have an index and ``join is not None``).
-For more examples, see :ref:`here <text.concatenate>`.
-    
-For categorical data, it is now possible to call :meth:`Series.str.cat` for ``CategoricalIndex`` as well (previously raised a ``ValueError``).
-Finally, if ``others is not None``, the resulting ``Series``/``Index`` will now remain categorical if the calling
-``Series``/``Index`` is categorical.
+Furthermore:
+- meth:`Series.str.cat` now works as well for ``CategoricalIndex`` as well (previously raised a ``ValueError``; see :issue:`20842`)
+- If concatenating with something (i.e. `others is not None`) the resulting ``Series``/``Index`` will now remain categorical if the calling ``Series``/``Index`` is categorical (see :issue:`20843`)
 
 .. _whatsnew_0230.enhancements.astype_category:
 

pandas/core/strings.py

@@ -1938,19 +1938,20 @@ def cons_row(x):
     def _get_series_list(self, others, ignore_index=False):
         """
         Auxiliary function for :meth:`str.cat`. Turn potentially mixed input
-        into list of Series (elements without an index must match the length of
-        the calling Series/Index).
+        into a list of Series (elements without an index must match the length
+        of the calling Series/Index).
 
         Parameters
         ----------
-        input : Series, DataFrame, np.ndarrary, list-like or list-like of those
+        input : Series, DataFrame, np.ndarray, list-like or list-like of
+            objects that are either Series, np.ndarray (1-dim) or list-like
         ignore_index : boolean, default False
             Determines whether to forcefully align with index of the caller
 
         Returns
         -------
-        tuple : first element: input transformed into list of Series
-            second element: Boolean whether FutureWarning should be raised
+        tuple : (input transformed into list of Series,
+                 Boolean whether FutureWarning should be raised)
         """
 
         # once str.cat defaults to alignment, this function can be simplified;
@@ -1961,6 +1962,10 @@ def _get_series_list(self, others, ignore_index=False):
         # self._orig is either Series or Index
         idx = self._orig if isinstance(self._orig, Index) else self._orig.index
 
+        err_msg = ('others must be Series, Index, DataFrame, np.ndarrary or '
+                   'list-like (either containing only strings or containing '
+                   'only objects of type Series/Index/list-like/np.ndarray')
+
         if isinstance(others, Series):
             fut_warn = not others.index.equals(idx)
             los = [Series(others.values, index=idx)
@@ -1988,15 +1993,32 @@ def _get_series_list(self, others, ignore_index=False):
                 los = []
                 fut_warn = False
                 while others:
-                    tmp = self._get_series_list(others.pop(0),
-                                                ignore_index=ignore_index)
+                    nxt = others.pop(0)
+                    # safety for iterators etc.; exclude indexed objects
+                    if (is_list_like(nxt) and
+                            not isinstance(nxt, (DataFrame, Series, Index))):
+                        nxt = list(nxt)
+
+                    # nested list-likes are forbidden - content must be strings
+                    is_legal = (is_list_like(nxt) and
+                                all(isinstance(x, compat.string_types)
+                                    for x in nxt))
+                    # DataFrame is false positive of is_legal
+                    # because "x in df" returns column names
+                    if isinstance(nxt, DataFrame) or not is_legal:
+                        raise TypeError(err_msg)
+
+                    tmp = self._get_series_list(nxt, ignore_index=ignore_index)
                     los = los + tmp[0]
                     fut_warn = fut_warn or tmp[1]
                 return (los, fut_warn)
+            # test if there is a mix of list-like and string/NaN/None
+            elif (any(is_list_like(x) for x in others)
+                  and any(not is_list_like(x) for x in others)):
+                raise TypeError(err_msg)
             else:
                 return ([Series(others, index=idx)], False)
-        raise ValueError('others must be Series, Index, DataFrame, '
-                         'np.ndarrary or list-like')
+        raise TypeError(err_msg)
 
     def cat(self, others=None, sep=None, na_rep=None, join=None):
         """
@@ -2015,9 +2037,9 @@ def cat(self, others=None, sep=None, na_rep=None, join=None):
             calling Series/Index, with the exception of indexed objects (i.e.
             Series/Index/DataFrame) if `join` is not None.
 
-            If others is a list-like that contains an arbitrary combination of
-            the above, then all elements will be unpacked and must satisfy the
-            above criteria individually.
+            If others is a list-like that contains a combination of Series,
+            np.ndarray (1-dim) or list-like, then all elements will be unpacked
+            and must satisfy the above criteria individually.
 
             If others is None, the method returns the concatenation of all
             strings in the calling Series/Index.
@@ -2158,7 +2180,7 @@ def cat(self, others=None, sep=None, na_rep=None, join=None):
             # turn anything in "others" into lists of Series
             tmp = self._get_series_list(others, ignore_index=(join is None))
             others, fut_warn = tmp
-        except ValueError:
+        except ValueError:  # let TypeError raised by _get_series_list pass
             if join is None:
                 # legacy warning
                 raise ValueError('All arrays must be same length')

pandas/tests/test_strings.py

@@ -349,6 +349,29 @@ def test_str_cat_mixed_inputs(self, series_or_index):
         with tm.assert_raises_regex(ValueError, rgx):
             s.str.cat([z, list(s)])
 
+        # errors for incorrect arguments in list-like
+        rgx = 'others must be Series, Index, DataFrame,.*'
+
+        # mix of string and Series
+        with tm.assert_raises_regex(TypeError, rgx):
+            s.str.cat([s, 's'])
+
+        # DataFrame in list
+        with tm.assert_raises_regex(TypeError, rgx):
+            s.str.cat([s, d])
+
+        # 2-dim ndarray in list
+        with tm.assert_raises_regex(TypeError, rgx):
+            s.str.cat([s, d.values])
+
+        # nested lists
+        with tm.assert_raises_regex(TypeError, rgx):
+            s.str.cat([s, [s, d]])
+
+        # forbidden input type, e.g. int
+        with tm.assert_raises_regex(TypeError, rgx):
+            s.str.cat(1)
+
     @pytest.mark.parametrize('series_or_index, join', [
         ('series', 'left'), ('series', 'outer'),
         ('series', 'inner'), ('series', 'right'),
@@ -410,28 +433,15 @@ def test_str_cat_align_mixed_inputs(self, join):
     def test_str_cat_special_cases(self):
         s = Series(['a', 'b', 'c', 'd'])
         t = Series(['d', 'a', 'e', 'b'], index=[3, 0, 4, 1])
-        d = concat([t, t], axis=1)
-
-        # lists of elements with different types - unaligned
-        mix = [t, t.values, ['A', 'B', 'C', 'D'], d, d.values]
-        exp = Series(['addAdddd', 'baaBaaaa', 'ceeCeeee', 'dbbDbbbb'])
-        with tm.assert_produces_warning(expected_warning=FutureWarning):
-            # FutureWarning to switch to alignment by default
-            tm.assert_series_equal(s.str.cat(mix, join=None), exp)
-
-        # lists of elements with different types - aligned with na_rep
-        exp = Series(['aadAaadd', 'bbaBbbaa', 'c-eC--ee', 'ddbDddbb'])
-        tm.assert_series_equal(s.str.cat(mix, join='left', na_rep='-'), exp)
 
         # iterator of elements with different types
-        exp = Series(['aadAaadd', 'bbaBbbaa', 'c-eC--ee',
-                      'ddbDddbb', '-e--ee--'])
-        tm.assert_series_equal(s.str.cat(iter(mix), join='outer', na_rep='-'),
-                               exp)
+        exp = Series(['aaA', 'bbB', 'c-C', 'ddD', '-e-'])
+        tm.assert_series_equal(s.str.cat(iter([t, ['A', 'B', 'C', 'D']]),
+                                         join='outer', na_rep='-'), exp)
 
         # right-align with different indexes in others
-        exp = Series(['aa--', 'd-dd'], index=[0, 3])
-        tm.assert_series_equal(s.str.cat([t.loc[[0]], d.loc[[3]]],
+        exp = Series(['aa-', 'd-d'], index=[0, 3])
+        tm.assert_series_equal(s.str.cat([t.loc[[0]], t.loc[[3]]],
                                          join='right', na_rep='-'), exp)
 
     def test_cat_on_filtered_index(self):