cached_property should preserve docstring of wrapped function

[John-Scott Atlakson]

This was prompted by noticing an issue in the ​Wagtail sphinx documentation where Sphinx pulls the docstring for cached_property rather than the decorated methods (specific and specific_class in the Wagtail documentation). The ​Sphinx documentation says decorators need to be well-behaved and preserve the docstring so I've submitted a ​pull request in attempt to make it well-behaved.

Berker Peksag requested I open a ticket to discuss and to add tests. I'm not sure how to test this since this results in downstream issues when other projects use cached_property AND try to auto-generate documentation using Sphinx. If someone can point me in the right direction I'll be happy to put together a test case, but it's late Sunday evening where I'm at and it's not occurring to me how to sensibly proceed.

FYI, this specific issue has been brought up on the ​mailing list before but there was no direct response on this point.

[Baptiste Mispelon]

Hi,

This seems like a reasonable addition to me.

To test this, you could do something like this:

def test_preserve_docstring(self):
    class Foo(object):
        @cached_property
        def bar(self):
            """Here is the docstring..."""
            return True

    self.assertEqual(Foo.bar.__doc__, "Here is the docstring...")

Thanks.

[Tim Graham <timograham@…>]

In dbf7a3df45e733c1e51d98318fd87de5ffc160a8:

Fixed #23688 -- Updated cached_property to preserve docstring of original function