Add cached property support (#433)

* TST: Add test case for cached_property.

* BUG: Fix detection of cached_property attrs.

Co-authored-by: Tirth Patel <tirthasheshpatel@gmail.com>

* Wrap cached_property import in try/except for Python 3.7.

Co-authored-by: Tirth Patel <tirthasheshpatel@gmail.com>

numpydoc/docscrape.py

@@ -12,6 +12,13 @@
 import sys
 
 
+# TODO: Remove try-except when support for Python 3.7 is dropped
+try:
+    from functools import cached_property
+except ImportError:  # cached_property added in Python 3.8
+    cached_property = property
+
+
 def strip_blank_lines(l):
     "Remove leading and trailing blank lines from a list of lines"
     while l and not l[0].strip():
@@ -706,7 +713,7 @@ def properties(self):
                 not name.startswith("_")
                 and (
                     func is None
-                    or isinstance(func, property)
+                    or isinstance(func, (property, cached_property))
                     or inspect.isdatadescriptor(func)
                 )
                 and self._is_show_member(name)

numpydoc/tests/test_docscrape.py

@@ -1,6 +1,7 @@
 from collections import namedtuple
 from copy import deepcopy
 import re
+import sys
 import textwrap
 import warnings
 
@@ -1624,6 +1625,26 @@ def __call__(self):
         nds._error_location(msg=msg)
 
 
+@pytest.mark.skipif(
+    sys.version_info < (3, 8), reason="cached_property was added in 3.8"
+)
+def test_class_docstring_cached_property():
+    """Ensure that properties marked with the `cached_property` decorator
+    are listed in the Methods section. See gh-432."""
+    from functools import cached_property
+
+    class Foo:
+        _x = [1, 2, 3]
+
+        @cached_property
+        def val(self):
+            return self._x
+
+    class_docstring = get_doc_object(Foo)
+    assert len(class_docstring["Attributes"]) == 1
+    assert class_docstring["Attributes"][0].name == "val"
+
+
 if __name__ == "__main__":
     import pytest