CLN: Update docstring decorator from Appender and Substitution to doc

[HH-MWB]

We use to use Appender and Substitution decorators to share docstring cross functions. Now we implemented a new decorator doc for that use case, and it would simplify the reuse of docstrings.

The idea here is to replace Appender and Substitution with doc decorator, and move the shared docstring to a better place if possible.

Example

The original code will be look like this:

@Substitution(**_shared_doc_kwargs)
@Appender(NDFrame.fillna.__doc__)
def fillna(self, value=None, ...) -> Optional["DataFrame"]:
    return super().fillna(...)

We would like to change it to this:

@doc(NDFrame.fillna, **_shared_doc_kwargs)
def fillna(self, value=None, ...) -> Optional["DataFrame"]:
    return super().fillna(...)

Reference

• CLN: Replace Appender and Substitution with simpler doc decorator

[HH-MWB]

take

[raisadz]

Hi, I tried to make changes to file pandas/core/indexes/extension.py

-from pandas.util._decorators import Appender, cache_readonly
+from pandas.util._decorators import cache_readonly, doc, Appender
-    @Appender(Index.dropna.__doc__)
+    @doc(Index.dropna)

and had the following error

$ python make.py --single pandas.core.indexes.extension.ExtensionIndex.dropna
Traceback (most recent call last):
  File "make.py", line 361, in <module>
    sys.exit(main())
  File "make.py", line 344, in main
    globals()["pandas"] = importlib.import_module("pandas")
  File "/anaconda3/envs/pandas-dev/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/Users/raya/pandas_raya/pandas/__init__.py", line 54, in <module>
    from pandas.core.api import (
  File "/Users/raya/pandas_raya/pandas/core/api.py", line 29, in <module>
    from pandas.core.groupby import Grouper, NamedAgg
  File "/Users/raya/pandas_raya/pandas/core/groupby/__init__.py", line 1, in <module>
    from pandas.core.groupby.generic import DataFrameGroupBy, NamedAgg, SeriesGroupBy
  File "/Users/raya/pandas_raya/pandas/core/groupby/generic.py", line 54, in <module>
    from pandas.core.aggregation import (
  File "/Users/raya/pandas_raya/pandas/core/aggregation.py", line 13, in <module>
    from pandas.core.indexes.api import Index
  File "/Users/raya/pandas_raya/pandas/core/indexes/api.py", line 14, in <module>
    from pandas.core.indexes.category import CategoricalIndex
  File "/Users/raya/pandas_raya/pandas/core/indexes/category.py", line 29, in <module>
    from pandas.core.indexes.extension import ExtensionIndex, inherit_names
  File "/Users/raya/pandas_raya/pandas/core/indexes/extension.py", line 193, in <module>
    class ExtensionIndex(Index):
  File "/Users/raya/pandas_raya/pandas/core/indexes/extension.py", line 232, in ExtensionIndex
    def dropna(self, how="any"):
  File "/Users/raya/pandas_raya/pandas/util/_decorators.py", line 281, in decorator
    wrapper.__doc__ = wrapper._docstr_template.format(**kwargs)  # type: ignore
KeyError: "'any', 'all'"

[HH-MWB]

Hi, I tried to make changes to file pandas/core/indexes/extension.py

-from pandas.util._decorators import Appender, cache_readonly
+from pandas.util._decorators import cache_readonly, doc, Appender
-    @Appender(Index.dropna.__doc__)
+    @doc(Index.dropna)

and had the following error

$ python make.py --single pandas.core.indexes.extension.ExtensionIndex.dropna
Traceback (most recent call last):
...
  File "/Users/raya/pandas_raya/pandas/core/indexes/extension.py", line 232, in ExtensionIndex
    def dropna(self, how="any"):
  File "/Users/raya/pandas_raya/pandas/util/_decorators.py", line 281, in decorator
    wrapper.__doc__ = wrapper._docstr_template.format(**kwargs)  # type: ignore
KeyError: "'any', 'all'"

Hi @raisadz. Same error here. I guess this is because the base function has use { and } in the docstring, and this has a conflict with doc decorator. PR #31970 would fix this kind of issue.

[farhanreynaldo]

Hi @HH-MWB, I also tried to make change to file pandas\core\base.py:

+ doc(operation='maximum')
    def argmax(self, axis=None, skipna=True, *args, **kwargs):
        """
        Return int position of the largest value in the Series.

+      If the {operation} is achieved in multiple locations,
        the first row position is returned.

and had this error:

Line 41, in pandas.Series.argmax
Failed example:
    s.argmax()
Exception raised:
    Traceback (most recent call last):
      File "C:\Users\farhan.hutabarat\AppData\Local\Continuum\anaconda3\envs\pandas-dev\lib\doctest.py", line 1329, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.argmax[2]>", line 1, in <module>
        s.argmax()
    NameError: name 's' is not defined

I think the problem is due to this line:

>>> s = pd.Series({'Corn Flakes': 100.0, 'Almond Delight': 110.0,
        ...                'Cinnamon Toast Crunch': 120.0, 'Cocoa Puff': 110.0})
>>> s

Because the docstring use { and }. Can you suggest on what should I do?

[HH-MWB]

Because the docstring use { and }. Can you suggest on what should I do?

Hi @farhanreynaldo, I would suggest that we replace { with {{ and replace } with }} here.

[farhanreynaldo]

Because the docstring use { and }. Can you suggest on what should I do?

Hi @farhanreynaldo, I would suggest that we replace { with {{ and replace } with }} here.

It works! Thank you, @HH-MWB