Improve doc string of Categorical._contains

pandas-dev · Jun 17, 2018 · 07dd41c · 07dd41c
1 parent 3eb49bb
commit 07dd41c
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 6 deletions.
diff --git a/doc/source/whatsnew/v0.23.2.txt b/doc/source/whatsnew/v0.23.2.txt
@@ -29,7 +29,6 @@ Performance Improvements
   is likewise much faster (:issue:`21369`)
 - Improved performance of membership checks in :class:`Categorical`
   (i.e. ``x in categorical``-style checks are much faster) (:issue:`21369`)
-
 -
 
 Documentation Changes

diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py
@@ -1849,11 +1849,35 @@ def __iter__(self):
 
     @staticmethod
     def _contains(key, categories, container):
-        """Returns True if `key` is in `categories` and the
-        location of `key` in `categories` is in `container`.
+        """
+        Helper for membership check for ``key``.
 
-        This is a helper method used in :method:`Categorical.__contains__`
+        This helper method is used in :method:`Categorical.__contains__`
         and in :class:`CategoricalIndex.__contains__`.
+
+        Returns True if ``key`` is in ``categories`` and the
+        location of ``key`` in ``categories`` is in ``container``.
+
+        Parameters
+        ----------
+        key : a hashable object
+            The key to check membership for.
+        categories : Sequence
+            The possible values for ``key``. The location for ``key``
+            in ``categories`` is also its value in ``container``
+        container : Container (e.g. list-like or mapping)
+            The container to check for membership in.
+
+        Returns
+        -------
+        is_in : bool
+            True if ``key`` is in ``categories`` and location of
+            ``key`` in ``categories`` is in ``container``, else False.
+
+        Notes
+        -----
+        This method does not check for Nan values. Do that separately
+        before calling this method.
         """
 
         # is key in categories? Then get its location in categories.

diff --git a/pandas/tests/categorical/test_algos.py b/pandas/tests/categorical/test_algos.py
@@ -72,7 +72,7 @@ def test_isin_empty(empty):
 
 
 def test_contains():
-
+    # GH21508
     c = pd.Categorical(list('aabbca'), categories=list('cab'))
 
     assert 'b' in c
@@ -84,7 +84,6 @@ def test_contains():
     assert 1 not in c
 
     c = pd.Categorical(list('aabbca') + [np.nan], categories=list('cab'))
-
     assert np.nan in c