feat: Allow method descriptors to be serialized as methods

Co-authored-by: Joel Gibson <[email protected]>
PR #103: #103

Author: jmrgibson

src/pytkdocs/loader.py

@@ -174,6 +174,18 @@ def is_method(self) -> bool:
         function_type = type(lambda: None)
         return self.parent_is_class() and isinstance(self.obj, function_type)
 
+    def is_method_descriptor(self) -> bool:
+        """
+        Tell if this node's object is a method descriptor.
+
+        Built-in methods (e.g. those implemented in C/Rust) are often
+        method descriptors, rather than normal methods.
+
+        Returns:
+            If this node's object is a method descriptor.
+        """
+        return inspect.ismethoddescriptor(self.obj)
+
     def is_staticmethod(self) -> bool:
         """
         Tell if this node's object is a staticmethod.
@@ -361,6 +373,8 @@ def get_object_documentation(self, dotted_path: str, members: Optional[Union[Set
             root_object = self.get_staticmethod_documentation(leaf)
         elif leaf.is_classmethod():
             root_object = self.get_classmethod_documentation(leaf)
+        elif leaf.is_method_descriptor():
+            root_object = self.get_regular_method_documentation(leaf)
         elif leaf.is_method():
             root_object = self.get_regular_method_documentation(leaf)
         elif leaf.is_function():
@@ -836,7 +850,7 @@ def get_regular_method_documentation(self, node: ObjectNode) -> Method:
 
     def get_method_documentation(self, node: ObjectNode, properties: Optional[List[str]] = None) -> Method:
         """
-        Get the documentation for a method.
+        Get the documentation for a method or method descriptor.
 
         Arguments:
             node: The node representing the method and its parents.
@@ -847,6 +861,7 @@ def get_method_documentation(self, node: ObjectNode, properties: Optional[List[s
         """
         method = node.obj
         path = node.dotted_path
+        signature: Optional[inspect.Signature]
         source: Optional[Source]
 
         try:
@@ -863,12 +878,23 @@ def get_method_documentation(self, node: ObjectNode, properties: Optional[List[s
             else:
                 properties.append("async")
 
+        try:
+            # for "built-in" functions, e.g. those implemented in C,
+            # inspect.signature() uses the __text_signature__ attribute, which
+            # provides a limited but still useful amount of signature information.
+            # "built-in" functions with no __text_signature__ will
+            # raise a ValueError().
+            signature = inspect.signature(method)
+        except ValueError as error:
+            self.errors.append(f"Couldn't read signature for '{path}': {error}")
+            signature = None
+
         return Method(
             name=node.name,
             path=path,
             file_path=node.file_path,
             docstring=inspect.getdoc(method),
-            signature=inspect.signature(method),
+            signature=signature,
             properties=properties or [],
             source=source,
         )

tests/fixtures/method_descriptor.py

@@ -0,0 +1,3 @@
+"""See https://docs.python.org/3/library/inspect.html#inspect.ismethoddescriptor for details"""
+
+descriptor = int.__add__

tests/test_loader.py

@@ -522,3 +522,14 @@ def test_loading_cached_properties():
     assert len(obj.children) == 1
     assert obj.children[0].name == obj.children[0].docstring == "aaa"
     assert "cached" in obj.children[0].properties
+
+
+def test_method_descriptor():
+    """Load a method descriptor."""
+    loader = Loader(new_path_syntax=True)
+    obj = loader.get_object_documentation("tests.fixtures.method_descriptor:descriptor")
+    assert obj.name == "descriptor"
+    assert obj.signature
+    assert len(obj.signature.parameters) == 2
+    assert obj.docstring
+    assert obj.category == "method"