Opened 10 years ago

Closed 10 years ago

#23688 closed Cleanup/optimization (fixed)

cached_property should preserve docstring of wrapped function

Reported by: John-Scott Atlakson Owned by: nobody
Component: Utilities Version: 1.7
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: yes Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.

Change History (2)

comment:1 by Baptiste Mispelon, 10 years ago

Component: UncategorizedUtilities
Easy pickings: set
Needs tests: set
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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.

comment:2 by Tim Graham <timograham@…>, 10 years ago

Resolution: fixed
Status: newclosed

In dbf7a3df45e733c1e51d98318fd87de5ffc160a8:

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

Note: See TracTickets for help on using tickets.
Back to Top