From 05fe47718c2a95198aaf61ee664fa3df63f114ef Mon Sep 17 00:00:00 2001 From: Tanya-Jain Date: Fri, 12 Oct 2018 19:37:02 +0530 Subject: [PATCH 1/5] DOC: Improve the docstring of pd.Index.contains --- pandas/core/indexes/base.py | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 51c84d6e28cb4..0e59dcbcda425 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2005,15 +2005,37 @@ def __contains__(self, key): return False _index_shared_docs['contains'] = """ - return a boolean if this key is IN the index + Return a boolean if this key is in the index. Parameters ---------- - key : object + key : label + The key requested. Immutable-like, 1-dimensional. Returns ------- - boolean + bool + Result of the key search. + + See Also + -------- + CategoricalIndex : Returns a bool if the 1-dimensional, Categorical key + is in index. + Index.isin : Returns ndarray of boolean dtype if list-like key is in + index. + + Examples + -------- + >>> l1 = pd.Index([1, 2, (3, 4), 5]) + >>> t = (3, 4) + >>> num1 = 1 + >>> num2 = 6 + >>> l1.contains(num1) + True + >>> l1.contains(num2) + False + >>> l1.contains(t) + True """ @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) From f0f875d229846299f199c142b19a0124a502d3ee Mon Sep 17 00:00:00 2001 From: Tanya-Jain Date: Sat, 13 Oct 2018 10:43:01 +0530 Subject: [PATCH 2/5] DOC: Improvement on Index.contains for reviews on PR #23100 - Description for key has more clarity on its behaviour. - Removed :class: `CategoricalIndex` from the See Also section as the methods: CategoricalIndex.contains, Float64Index.contains and like, behave similarly to `Index.contains`. Hence, keeping only `Index.isin` - Use `idx` for naming variables for objects of :class: `Index` instead of `l` for passing list-like key, to encourage pandas docstring standards and clarity. - Directly call the values in :method: `Index.contains` to prevent additional memory usage. --- pandas/core/indexes/base.py | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 0e59dcbcda425..b1f9fa2bcb41d 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2010,7 +2010,8 @@ def __contains__(self, key): Parameters ---------- key : label - The key requested. Immutable-like, 1-dimensional. + The key can be of the same type as the label of :class: `Index`, + hence immutable-like and 1-dimensional if it is a tuple. Returns ------- @@ -2019,23 +2020,20 @@ def __contains__(self, key): See Also -------- - CategoricalIndex : Returns a bool if the 1-dimensional, Categorical key - is in index. Index.isin : Returns ndarray of boolean dtype if list-like key is in index. Examples -------- - >>> l1 = pd.Index([1, 2, (3, 4), 5]) - >>> t = (3, 4) - >>> num1 = 1 - >>> num2 = 6 - >>> l1.contains(num1) + >>> idx = pd.Index([1, 2, (3, 4), 5]) + >>> idx + Index([1, 2, (3, 4), 5], dtype='object') + >>> idx.contains((3,4)) True - >>> l1.contains(num2) - False - >>> l1.contains(t) + >>> idx.contains(1) True + >>> idx.contains(6) + False """ @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) From a65f51d057c26571f9806b18f27d77c2568f4d11 Mon Sep 17 00:00:00 2001 From: Tanya-Jain Date: Wed, 24 Oct 2018 04:27:15 +0530 Subject: [PATCH 3/5] Rephrasing, Testing and Validating docstring - Rephrased description as a boolean indicator - Removed a space after :class: for correct rendering checked by the command `./doc/make.py html --single=pandas.Index.contains` - Moved the easier example cases first. - Added the missing space after comma following PEP8 - Validation tests passed with a warning of absence of an extended description. Tested via command `./scripts/validate_docstrings.py pandas.Index.contains` - No doctests problem were reported for lines 2008-2036 by testing via command `flake8 --doctests pandas/core/indexes/base.py` --- pandas/core/indexes/base.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index b1f9fa2bcb41d..dd8ab00a86024 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2005,35 +2005,35 @@ def __contains__(self, key): return False _index_shared_docs['contains'] = """ - Return a boolean if this key is in the index. + Return a boolean indicating whether this key is in the index. Parameters ---------- key : label - The key can be of the same type as the label of :class: `Index`, + The key can be of the same type as the label of :class:`Index`, hence immutable-like and 1-dimensional if it is a tuple. Returns ------- bool - Result of the key search. + Result indicating whether the key search is in the index. See Also -------- - Index.isin : Returns ndarray of boolean dtype if list-like key is in - index. + Index.isin : Returns an ndarray of boolean dtype indicating whether the + list-like key is in the index. Examples -------- >>> idx = pd.Index([1, 2, (3, 4), 5]) >>> idx Index([1, 2, (3, 4), 5], dtype='object') - >>> idx.contains((3,4)) - True >>> idx.contains(1) True >>> idx.contains(6) False + >>> idx.contains((3, 4)) + True """ @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) From dedb267e6829ee6c6e5c188514a3d8ad11eccb59 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 7 Dec 2018 12:35:36 +0000 Subject: [PATCH 4/5] Improving Index.contains example, and reusing docstring for __contains__ --- pandas/core/indexes/base.py | 43 +++++++++++++---------------- pandas/core/indexes/category.py | 2 +- pandas/core/indexes/datetimelike.py | 2 +- pandas/core/indexes/multi.py | 2 +- pandas/core/indexes/period.py | 2 +- 5 files changed, 23 insertions(+), 28 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 1964d532b487f..9fbe8f37f053f 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2260,6 +2260,7 @@ def union(self, other): Examples -------- + >>> idx1 = pd.Index([1, 2, 3, 4]) >>> idx2 = pd.Index([3, 4, 5, 6]) >>> idx1.union(idx2) @@ -3811,26 +3812,6 @@ def _is_memory_usage_qualified(self): def is_type_compatible(self, kind): return kind == self.inferred_type - _index_shared_docs['__contains__'] = """ - Return a boolean if this key is IN the index. - - Parameters - ---------- - key : object - - Returns - ------- - boolean - """ - - @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs) - def __contains__(self, key): - hash(key) - try: - return key in self._engine - except (OverflowError, TypeError, ValueError): - return False - _index_shared_docs['contains'] = """ Return a boolean indicating whether this key is in the index. @@ -3852,17 +3833,31 @@ def __contains__(self, key): Examples -------- - >>> idx = pd.Index([1, 2, (3, 4), 5]) + >>> idx = pd.Index([1, 2, 3, 4]) >>> idx - Index([1, 2, (3, 4), 5], dtype='object') - >>> idx.contains(1) + Int64Index([1, 2, 3, 4], dtype='int64') + + >>> idx.contains(2) True >>> idx.contains(6) False - >>> idx.contains((3, 4)) + + This is equivalent to: + + >>> 2 in idx True + >>> 6 in idx + False """ + @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) + def __contains__(self, key): + hash(key) + try: + return key in self._engine + except (OverflowError, TypeError, ValueError): + return False + @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) def contains(self, key): hash(key) diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 6d26894514a9c..9ce4949992f4c 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -359,7 +359,7 @@ def ordered(self): def _reverse_indexer(self): return self._data._reverse_indexer() - @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs) + @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) def __contains__(self, key): # if key is a NaN, check if any NaN is in self. if isna(key): diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 52127811b584a..dd2537c11a94c 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -150,7 +150,7 @@ def _box_values_as_index(self): from pandas.core.index import Index return Index(self._box_values(self.asi8), name=self.name, dtype=object) - @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs) + @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) def __contains__(self, key): try: res = self.get_loc(key) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 5e26a3c6c439e..b8712f1678f4e 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -755,7 +755,7 @@ def _shallow_copy_with_infer(self, values, **kwargs): **kwargs) return self._shallow_copy(values, **kwargs) - @Appender(_index_shared_docs['__contains__'] % _index_doc_kwargs) + @Appender(_index_shared_docs['contains'] % _index_doc_kwargs) def __contains__(self, key): hash(key) try: diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py index 3d69a0a84f7ae..727f819e69056 100644 --- a/pandas/core/indexes/period.py +++ b/pandas/core/indexes/period.py @@ -400,7 +400,7 @@ def _mpl_repr(self): def _engine(self): return self._engine_type(lambda: self, len(self)) - @Appender(_index_shared_docs['__contains__']) + @Appender(_index_shared_docs['contains']) def __contains__(self, key): if isinstance(key, Period): if key.freq != self.freq: From 93dcd9d0a9241b835c583e920d5ef3a9ceb9e4d0 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 7 Dec 2018 12:39:57 +0000 Subject: [PATCH 5/5] Improving texts of the docstring --- pandas/core/indexes/base.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 9fbe8f37f053f..0e393476bdf5f 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -3813,18 +3813,17 @@ def is_type_compatible(self, kind): return kind == self.inferred_type _index_shared_docs['contains'] = """ - Return a boolean indicating whether this key is in the index. + Return a boolean indicating whether the provided key is in the index. Parameters ---------- key : label - The key can be of the same type as the label of :class:`Index`, - hence immutable-like and 1-dimensional if it is a tuple. + The key to check if it is present in the index. Returns ------- bool - Result indicating whether the key search is in the index. + Whether the key search is in the index. See Also --------