API: raise a TypeError when isin is passed a string

doc/source/api.rst

@@ -451,6 +451,7 @@ Indexing, iteration
    DataFrame.pop
    DataFrame.tail
    DataFrame.xs
+   DataFrame.isin
 
 Binary operator functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~

doc/source/release.rst

@@ -148,6 +148,9 @@ pandas 0.13
     behavior.
   - ``DataFrame.update()`` no longer raises a ``DataConflictError``, it now
     will raise a ``ValueError`` instead (if necessary) (:issue:`4732`)
+  - ``Series.isin()`` and ``DataFrame.isin()``  now raise a ``TypeError`` when
+    passed a string (:issue:`4763`). Pass a ``list`` of one element (containing
+    the string) instead.
 
 **Internal Refactoring**
 

pandas/core/frame.py

@@ -4609,6 +4609,11 @@ def isin(self, values, iloc=False):
 
 
         else:
+            if not com.is_list_like(values):
+                raise TypeError("only list-like or dict-like objects are"
+                                " allowed to be passed to DataFrame.isin(), "
+                                "you passed a "
+                                "{0!r}".format(type(values).__name__))
             return DataFrame(lib.ismember(self.values.ravel(),
                                           set(values)).reshape(self.shape),
                              self.index,

pandas/core/series.py

@@ -2805,17 +2805,47 @@ def take(self, indices, axis=0, convert=True):
 
     def isin(self, values):
         """
-        Return boolean vector showing whether each element in the Series is
-        exactly contained in the passed sequence of values
+        Return a boolean :ref:`~pandas.Series` showing whether each element in
+        the ref:`~pandas.Series` is exactly contained in the passed sequence of
+        ``values``.
 
         Parameters
         ----------
-        values : sequence
+        values : list-like
+            The sequence of values to test. Passing in a single string will
+            raise a ``TypeError``:
+
+                .. code-block:: python
+
+                   from pandas import Series
+                   s = Series(list('abc'))
+                   s.isin('a')
+
+            Instead, turn a single string into a ``list`` of one element:
+
+                .. code-block:: python
+
+                   from pandas import Series
+                   s = Series(list('abc'))
+                   s.isin(['a'])
 
         Returns
         -------
-        isin : Series (boolean dtype)
+        isin : Series (bool dtype)
+
+        Raises
+        ------
+        TypeError
+          * If ``values`` is a string
+
+        See Also
+        --------
+        pandas.DataFrame.isin
         """
+        if not com.is_list_like(values):
+            raise TypeError("only list-like objects are allowed to be passed"
+                            " to Series.isin(), you passed a "
+                            "{0!r}".format(type(values).__name__))
         value_set = set(values)
         result = lib.ismember(_values_from_object(self), value_set)
         return self._constructor(result, self.index, name=self.name)

pandas/tests/test_frame.py

@@ -10915,6 +10915,16 @@ def test_isin_dict(self):
         expected.iloc[0, 0] = True
         assert_frame_equal(result, expected)
 
+    def test_isin_with_string_scalar(self):
+        #GH4763
+        df = DataFrame({'vals': [1, 2, 3, 4], 'ids': ['a', 'b', 'f', 'n'],
+                        'ids2': ['a', 'n', 'c', 'n']},
+                        index=['foo', 'bar', 'baz', 'qux'])
+        with tm.assertRaises(TypeError):
+            df.isin('a')
+
+        with tm.assertRaises(TypeError):
+            df.isin('aaa')
 
 if __name__ == '__main__':
     # unittest.main()

pandas/tests/test_series.py

@@ -4433,6 +4433,16 @@ def test_isin(self):
         expected = Series([True, False, True, False, False, False, True, True])
         assert_series_equal(result, expected)
 
+    def test_isin_with_string_scalar(self):
+        #GH4763
+        s = Series(['A', 'B', 'C', 'a', 'B', 'B', 'A', 'C'])
+        with tm.assertRaises(TypeError):
+            s.isin('a')
+
+        with tm.assertRaises(TypeError):
+            s = Series(['aaa', 'b', 'c'])
+            s.isin('aaa')
+
     def test_fillna_int(self):
         s = Series(np.random.randint(-100, 100, 50))
         s.fillna(method='ffill', inplace=True)