CLN: a batch of replacements of @Appender() with @doc()

[smartvinnetou]

• xref CLN: Update docstring decorator from Appender and Substitution to doc #31942
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• replaces a number of uses of @appender() with @doc() in core/generic.py

[smartvinnetou]

I keep getting an error from a failed pytest. This happens in CI, see https://dev.azure.com/pandas-dev/pandas/_build/results?buildId=31810&view=logs&j=3a03f79d-0b41-5610-1aa4-b4a014d0bc70&t=4d05ed0e-1ed3-5bff-dd63-1e957f2766a9
and locally
`(pandas-dev) C:\Users\David\source\repos\pandas-smartvinnetou>pytest pandas/tests/frame/methods/test_shift.py::TestDataFrameShift::test_shift_dt64values_int_fill_deprecated
=========================================================================================================================== test session starts ===========================================================================================================================
platform win32 -- Python 3.7.4, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
rootdir: C:\Users\David\source\repos\pandas-smartvinnetou, inifile: setup.cfg
plugins: hypothesis-5.5.3, asyncio-0.10.0, cov-2.8.1, forked-1.1.3, xdist-1.31.0
collected 1 item

pandas\tests\frame\methods\test_shift.py F [100%]

================================================================================================================================ FAILURES =================================================================================================================================
______________________________________________________________________________________________________ TestDataFrameShift.test_shift_dt64values_int_fill_deprecated _______________________________________________________________________________________________________

self = <pandas.tests.frame.methods.test_shift.TestDataFrameShift object at 0x0000020E4201C088>

def test_shift_dt64values_int_fill_deprecated(self):
    # GH#31971
    ser = pd.Series([pd.Timestamp("2020-01-01"), pd.Timestamp("2020-01-02")])
    df = ser.to_frame()

    with tm.assert_produces_warning(FutureWarning):

      result = df.shift(1, fill_value=0)

pandas\tests\frame\methods\test_shift.py:195:

---

self = <contextlib._GeneratorContextManager object at 0x0000020E42021BC8>, type = None, value = None, traceback = None

def __exit__(self, type, value, traceback):
    if type is None:
        try:

          next(self.gen)

E AssertionError: Warning not set with correct stacklevel. File where warning is raised: C:\Users\David\source\repos\pandas-smartvinnetou\pandas\core\frame.py != C:\Users\David\source\repos\pandas-smartvinnetou\pandas\tests\frame\methods\test_shift.py. W
arning message: Passing <class 'int'> to shift is deprecated and will raise in a future version, pass Timestamp instead.

......\AppData\Local\Programs\Python\Python37\lib\contextlib.py:119: AssertionError
============================================================================================================================ 1 failed in 0.50s ============================================================================================================================

(pandas-dev) C:\Users\David\source\repos\pandas-smartvinnetou>
`
I changed docstings and the related decorator. I have not changed any code. The error messages are not terribly informative.

Can someone shed some light on this failed test? Is this an issue with raising the wrong warning for some reason?

[smartvinnetou]

After more investigation, I believe that the reason of the failed test the change of the depth of the stack introduced by the doc() decorator. It adds and extra frame per call to the stack (the wrapper() at https://github.com/pandas-dev/pandas/blob/master/pandas/util/_decorators.py#L224). The Appender() decorator changed the function it was decorating directly without introducing a wrapper, see https://github.com/pandas-dev/pandas/blob/master/pandas/util/_decorators.py#L381.

As the doc() decorator is called twice, there are two more frames on the stack (then there were when Appender() was used) when the FutureWarning() is raised at https://github.com/pandas-dev/pandas/blob/master/pandas/core/arrays/datetimelike.py#L790.

And then there is a mismatch when the failing test is checking the raised warning at https://github.com/pandas-dev/pandas/blob/master/pandas/_testing.py#L2366.

I can fix this mismatch by increasing the stacklevel at https://github.com/pandas-dev/pandas/blob/master/pandas/core/arrays/datetimelike.py#L795 to 9. This makes the actual_warning.filename and caller.filename values at https://github.com/pandas-dev/pandas/blob/master/pandas/_testing.py#L2372 point to pandas\\tests\\frame\\methods\\test_shift.py.

Can someone who knows the logic behind all this code confirm that this is the right change? @jorisvandenbossche ?

[jorisvandenbossche]

Can someone who knows the logic behind all this code confirm that this is the right change?

If the number of wrapping functions increased, then increasing the number specified in stacklevel is indeed the correct thing to do.

[jorisvandenbossche]

@smartvinnetou thanks a lot!