fix: Support cached properties

Issue #86: #86

Author: pawamoy

Diff for: config/mypy.ini

@@ -1,2 +1,5 @@
 [mypy]
 ignore_missing_imports = true
+
+[mypy-tests.fixtures.*]
+ignore_errors = true

Diff for: pyproject.toml

@@ -20,8 +20,7 @@ include = [
 
 [tool.poetry.dependencies]
 python = "^3.6"
-dataclasses = {version = ">=0.7 <0.9", python = "3.6"}
-typing-extensions = {version = "^3.7.4.3", python = "3.6 || 3.7"}
+cached-property = {version = "^1.5.2", python = "<3.8"}
 
 [tool.poetry.dev-dependencies]
 autoflake = "^1.4"

Diff for: src/pytkdocs/loader.py

@@ -20,6 +20,11 @@
 from pytkdocs.parsers.docstrings import PARSERS
 from pytkdocs.properties import RE_SPECIAL
 
+try:
+    from functools import cached_property  # type: ignore
+except ImportError:
+    from cached_property import cached_property  # type: ignore
+
 
 class ObjectNode:
     """
@@ -138,7 +143,16 @@ def is_property(self) -> bool:
         Returns:
             If this node's object is a property.
         """
-        return isinstance(self.obj, property)
+        return isinstance(self.obj, property) or self.is_cached_property()
+
+    def is_cached_property(self) -> bool:
+        """
+        Tell if this node's object is a cached property.
+
+        Returns:
+            If this node's object is a cached property.
+        """
+        return isinstance(self.obj, cached_property)
 
     def parent_is_class(self) -> bool:
         """
@@ -608,19 +622,27 @@ def get_property_documentation(self, node: ObjectNode) -> Attribute:
         """
         prop = node.obj
         path = node.dotted_path
-        properties = ["property", "readonly" if prop.fset is None else "writable"]
+        properties = ["property"]
+        if node.is_cached_property():
+            # cached_property is always writable, see the docs
+            properties.extend(["writable", "cached"])
+            sig_source_func = prop.func
+        else:
+            properties.append("readonly" if prop.fset is None else "writable")
+            sig_source_func = prop.fget
+
         source: Optional[Source]
 
         try:
-            signature = inspect.signature(prop.fget)
+            signature = inspect.signature(sig_source_func)
         except (TypeError, ValueError) as error:
             self.errors.append(f"Couldn't get signature for '{path}': {error}")
             attr_type = None
         else:
             attr_type = signature.return_annotation
 
         try:
-            source = Source(*inspect.getsourcelines(prop.fget))
+            source = Source(*inspect.getsourcelines(sig_source_func))
         except (OSError, TypeError) as error:
             self.errors.append(f"Couldn't get source for '{path}': {error}")
             source = None

Diff for: tests/fixtures/cached_properties.py

@@ -0,0 +1,10 @@
+try:
+    from functools import cached_property
+except ImportError:
+    from cached_property import cached_property
+
+
+class C:
+    @cached_property
+    def aaa(self):
+        """aaa"""

Diff for: tests/test_loader.py

@@ -497,3 +497,12 @@ def test_inherited_properties_docstrings():
     assert obj.docstring == "SuperClass.read_only docs"
     obj = loader.get_object_documentation("tests.fixtures.inherited_properties:SubClass.mutable")
     assert obj.docstring == "SuperClass.mutable getter docs"
+
+
+def test_loading_cached_properties():
+    """Load cached properties."""
+    loader = Loader(new_path_syntax=True)
+    obj = loader.get_object_documentation("tests.fixtures.cached_properties:C")
+    assert len(obj.children) == 1
+    assert obj.children[0].name == obj.children[0].docstring == "aaa"
+    assert "cached" in obj.children[0].properties