CLN: @doc - base.py & indexing.py

pandas/core/arrays/categorical.py

@@ -15,6 +15,7 @@
     Substitution,
     cache_readonly,
     deprecate_kwarg,
+    doc,
 )
 from pandas.util._validators import validate_bool_kwarg, validate_fillna_kwargs
 
@@ -51,7 +52,7 @@
     _extension_array_shared_docs,
     try_cast_to_ea,
 )
-from pandas.core.base import NoNewAttributesMixin, PandasObject, _shared_docs
+from pandas.core.base import IndexOpsMixin, NoNewAttributesMixin, PandasObject
 import pandas.core.common as com
 from pandas.core.construction import array, extract_array, sanitize_array
 from pandas.core.indexers import check_array_indexer, deprecate_ndim_indexing
@@ -1352,8 +1353,7 @@ def memory_usage(self, deep=False):
         """
         return self._codes.nbytes + self.dtype.categories.memory_usage(deep=deep)
 
-    @Substitution(klass="Categorical")
-    @Appender(_shared_docs["searchsorted"])
+    @doc(IndexOpsMixin.searchsorted, klass="Categorical")
     def searchsorted(self, value, side="left", sorter=None):
         # searchsorted is very performance sensitive. By converting codes
         # to same dtype as self.codes, we get much faster performance.

pandas/core/base.py

@@ -4,7 +4,7 @@
 
 import builtins
 import textwrap
-from typing import Dict, FrozenSet, List, Optional, Union
+from typing import FrozenSet, List, Optional, Union
 
 import numpy as np
 
@@ -13,7 +13,7 @@
 from pandas.compat import PYPY
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
-from pandas.util._decorators import Appender, Substitution, cache_readonly, doc
+from pandas.util._decorators import cache_readonly, doc
 from pandas.util._validators import validate_bool_kwarg
 
 from pandas.core.dtypes.cast import is_nested_object
@@ -36,7 +36,6 @@
 from pandas.core.construction import create_series_with_explicit_dtype
 import pandas.core.nanops as nanops
 
-_shared_docs: Dict[str, str] = dict()
 _indexops_doc_kwargs = dict(
     klass="IndexOpsMixin",
     inplace="",
@@ -1402,26 +1401,26 @@ def memory_usage(self, deep=False):
     def factorize(self, sort=False, na_sentinel=-1):
         return algorithms.factorize(self, sort=sort, na_sentinel=na_sentinel)
 
-    _shared_docs[
-        "searchsorted"
-    ] = """
+    @doc(klass="Index")
+    def searchsorted(self, value, side="left", sorter=None) -> np.ndarray:
+        """
         Find indices where elements should be inserted to maintain order.
 
-        Find the indices into a sorted %(klass)s `self` such that, if the
+        Find the indices into a sorted {klass} `self` such that, if the
         corresponding elements in `value` were inserted before the indices,
         the order of `self` would be preserved.
 
         .. note::
 
-            The %(klass)s *must* be monotonically sorted, otherwise
+            The {klass} *must* be monotonically sorted, otherwise
             wrong locations will likely be returned. Pandas does *not*
             check this for you.
 
         Parameters
         ----------
         value : array_like
             Values to insert into `self`.
-        side : {'left', 'right'}, optional
+        side : {{'left', 'right'}}, optional
             If 'left', the index of the first suitable location found is given.
             If 'right', return the last such index.  If there is no suitable
             index, return either 0 or N (where N is the length of `self`).
@@ -1488,10 +1487,6 @@ def factorize(self, sort=False, na_sentinel=-1):
         >>> x.searchsorted(1)
         0  # wrong result, correct would be 1
         """
-
-    @Substitution(klass="Index")
-    @Appender(_shared_docs["searchsorted"])
-    def searchsorted(self, value, side="left", sorter=None) -> np.ndarray:
         return algorithms.searchsorted(self._values, value, side=side, sorter=sorter)
 
     def drop_duplicates(self, keep="first", inplace=False):

pandas/core/indexes/datetimelike.py

@@ -10,7 +10,7 @@
 from pandas._libs.tslibs import timezones
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
-from pandas.util._decorators import Appender, cache_readonly
+from pandas.util._decorators import Appender, cache_readonly, doc
 
 from pandas.core.dtypes.common import (
     ensure_int64,
@@ -31,7 +31,7 @@
 from pandas.core import algorithms
 from pandas.core.arrays import DatetimeArray, PeriodArray, TimedeltaArray
 from pandas.core.arrays.datetimelike import DatetimeLikeArrayMixin
-from pandas.core.base import _shared_docs
+from pandas.core.base import IndexOpsMixin
 import pandas.core.indexes.base as ibase
 from pandas.core.indexes.base import Index, _index_shared_docs
 from pandas.core.indexes.extension import (
@@ -206,7 +206,7 @@ def take(self, indices, axis=0, allow_fill=True, fill_value=None, **kwargs):
             self, indices, axis, allow_fill, fill_value, **kwargs
         )
 
-    @Appender(_shared_docs["searchsorted"])
+    @doc(IndexOpsMixin.searchsorted, klass="Datetime-like Index")
     def searchsorted(self, value, side="left", sorter=None):
         if isinstance(value, str):
             raise TypeError(

pandas/core/indexing.py

@@ -5,7 +5,7 @@
 from pandas._libs.indexing import _NDFrameIndexerBase
 from pandas._libs.lib import item_from_zerodim
 from pandas.errors import AbstractMethodError
-from pandas.util._decorators import Appender
+from pandas.util._decorators import doc
 
 from pandas.core.dtypes.common import (
     is_float,
@@ -872,7 +872,7 @@ def _getbool_axis(self, key, axis: int):
         return self.obj._take_with_is_copy(inds, axis=axis)
 
 
-@Appender(IndexingMixin.loc.__doc__)
+@doc(IndexingMixin.loc)
 class _LocIndexer(_LocationIndexer):
     _takeable: bool = False
     _valid_types = (
@@ -884,7 +884,7 @@ class _LocIndexer(_LocationIndexer):
     # -------------------------------------------------------------------
     # Key Checks
 
-    @Appender(_LocationIndexer._validate_key.__doc__)
+    @doc(_LocationIndexer._validate_key)
     def _validate_key(self, key, axis: int):
 
         # valid for a collection of labels (we check their presence later)
@@ -1343,7 +1343,7 @@ def _validate_read_indexer(
                 )
 
 
-@Appender(IndexingMixin.iloc.__doc__)
+@doc(IndexingMixin.iloc)
 class _iLocIndexer(_LocationIndexer):
     _valid_types = (
         "integer, integer slice (START point is INCLUDED, END "
@@ -2079,7 +2079,7 @@ def __setitem__(self, key, value):
         self.obj._set_value(*key, value=value, takeable=self._takeable)
 
 
-@Appender(IndexingMixin.at.__doc__)
+@doc(IndexingMixin.at)
 class _AtIndexer(_ScalarAccessIndexer):
     _takeable = False
 
@@ -2099,7 +2099,7 @@ def _convert_key(self, key, is_setter: bool = False):
         return tuple(lkey)
 
 
-@Appender(IndexingMixin.iat.__doc__)
+@doc(IndexingMixin.iat)
 class _iAtIndexer(_ScalarAccessIndexer):
     _takeable = True
 

pandas/core/series.py

@@ -2470,8 +2470,7 @@ def __rmatmul__(self, other):
         """
         return self.dot(np.transpose(other))
 
-    @Substitution(klass="Series")
-    @Appender(base._shared_docs["searchsorted"])
+    @doc(base.IndexOpsMixin.searchsorted, klass="Series")
     def searchsorted(self, value, side="left", sorter=None):
         return algorithms.searchsorted(self._values, value, side=side, sorter=sorter)
 

pandas/tests/util/test_doc.py

@@ -14,13 +14,15 @@ def cumsum(whatever):
 
 @doc(
     cumsum,
-    """
-    Examples
-    --------
+    dedent(
+        """
+        Examples
+        --------
 
-    >>> cumavg([1, 2, 3])
-    2
-    """,
+        >>> cumavg([1, 2, 3])
+        2
+        """
+    ),
     method="cumavg",
     operation="average",
 )

pandas/util/_decorators.py

@@ -250,9 +250,10 @@ def doc(*args: Union[str, Callable], **kwargs: str) -> Callable[[F], F]:
     A decorator take docstring templates, concatenate them and perform string
     substitution on it.
 
-    This decorator is robust even if func.__doc__ is None. This decorator will
-    add a variable "_docstr_template" to the wrapped function to save original
-    docstring template for potential usage.
+    This decorator will add a variable "_doc_args" to the wrapped function to
+    keep track the original docstring template for potential usage. If it should
+    be consider as a template, it will be saved as a string. Otherwise, it will
+    be saved as callable, and later user __doc__ and dedent to get docstring.
 
     Parameters
     ----------
@@ -268,17 +269,26 @@ def decorator(func: F) -> F:
         def wrapper(*args, **kwargs) -> Callable:
             return func(*args, **kwargs)
 
-        templates = [func.__doc__ if func.__doc__ else ""]
+        # collecting and docstring templates
+        wrapper._doc_args: List[Union[str, Callable]] = []  # type: ignore
+        if func.__doc__:
+            wrapper._doc_args.append(dedent(func.__doc__))  # type: ignore
+
         for arg in args:
-            if isinstance(arg, str):
-                templates.append(arg)
-            elif hasattr(arg, "_docstr_template"):
-                templates.append(arg._docstr_template)  # type: ignore
-            elif arg.__doc__:
-                templates.append(arg.__doc__)
-
-        wrapper._docstr_template = "".join(dedent(t) for t in templates)  # type: ignore
-        wrapper.__doc__ = wrapper._docstr_template.format(**kwargs)  # type: ignore
+            if hasattr(arg, "_doc_args"):
+                wrapper._doc_args.extend(arg._doc_args)  # type: ignore
+            elif isinstance(arg, str) or arg.__doc__:
+                wrapper._doc_args.append(arg)  # type: ignore
+
+        # formatting templates and concatenating docstring
+        wrapper.__doc__ = "".join(
+            [
+                arg.format(**kwargs)
+                if isinstance(arg, str)
+                else dedent(arg.__doc__)  # type: ignore
+                for arg in wrapper._doc_args  # type: ignore
+            ]
+        )
 
         return cast(F, wrapper)