Better property support

docs/epytext_demo/demo_epytext_module.py

@@ -162,13 +162,14 @@ def read_and_write(self) -> int:
     @read_and_write.setter
     def read_and_write(self, value: int) -> None:
         """
-        This is a docstring for setter.
+        This is a docstring for setter. 
+        Their are usually not explicitely documented though. 
         """
 
     @property
     def read_and_write_delete(self) -> int:
         """
-        This is a read-write-delete property.
+        This is the docstring of the property.
         """
         return 1
 
@@ -183,6 +184,13 @@ def read_and_write_delete(self) -> None:
         """
         This is a docstring for deleter.
         """
+
+    @property
+    def undoc_prop(self) -> bytes:
+        """This property has a docstring only on the setter."""
+    @undoc_prop.setter
+    def undoc_prop(self, p) -> None: # type:ignore
+        ...
 
 
 class IContact(zope.interface.Interface):

docs/restructuredtext_demo/demo_restructuredtext_module.py

@@ -130,6 +130,22 @@ def _private_inside_private(self) -> List[str]:
         :rtype: `list`
         """
         return []
+
+    @property
+    def isPrivate(self) -> bool:
+        """Whether this class is private"""
+        return True
+    @isPrivate.setter
+    def isPrivate(self, v) -> bool:
+        raise NotImplemented()
+
+    @property
+    def isPublic(self) -> bool:
+        """Whether this class is public"""
+        return False
+    @isPublic.setter
+    def isPublic(self, v) -> bool:
+        raise NotImplemented()
 
 
 
@@ -178,13 +194,14 @@ def read_and_write(self) -> int:
     @read_and_write.setter
     def read_and_write(self, value: int) -> None:
         """
-        This is a docstring for setter.
+        This is a docstring for setter. 
+        Their are usually not explicitely documented though. 
         """
 
     @property
     def read_and_write_delete(self) -> int:
         """
-        This is a read-write-delete property.
+        This is the docstring of the property.
         """
         return 1
 
@@ -199,6 +216,21 @@ def read_and_write_delete(self) -> None:
         """
         This is a docstring for deleter.
         """
+
+    @property
+    def undoc_prop(self) -> bytes:
+        """This property has a docstring only on the setter."""
+    @undoc_prop.setter
+    def undoc_prop(self, p) -> None: # type:ignore
+        ...
+
+    @property
+    def isPrivate(self) -> bool:
+        return False
+
+    @_PrivateClass.isPublic.setter
+    def isPublic(self, v):
+        self._v = v
 
 class IContact(zope.interface.Interface):
     """

docs/tests/test.py

@@ -185,7 +185,7 @@ def test_search(query:str, expected:List[str], order_is_important:bool=True) ->
             ['pydoctor.model.Class', 
              'pydoctor.factory.Factory.Class',
              'pydoctor.model.DocumentableKind.CLASS',
-             'pydoctor.model.System.Class'])
+             'pydoctor.model.System.Class'], order_is_important=False)
 
         to_stan_results = [
                     'pydoctor.epydoc.markup.ParsedDocstring.to_stan', 

pydoctor/astbuilder.py

@@ -13,7 +13,8 @@
 )
 
 import astor
-from pydoctor import epydoc2stan, model, node2stan, extensions
+import attr
+from pydoctor import epydoc2stan, model, node2stan, extensions, astutils
 from pydoctor.epydoc.markup._pyval_repr import colorize_inline_pyval
 from pydoctor.astutils import (is_none_literal, is_typing_annotation, is_using_annotations, is_using_typing_final, node2dottedname, node2fullname, 
                                is__name__equals__main__, unstring_annotation, iterassign, extract_docstring_linenum,  
@@ -147,6 +148,73 @@ def extract_final_subscript(annotation: ast.Subscript) -> ast.expr:
         assert isinstance(ann_slice, ast.expr)
         return ann_slice
 
+def is_property_def_decorator(dottedname:List[str], ctx:model.Documentable) -> bool:
+    """
+    Whether the last element of the list of names finishes by "property" or "Property".
+    """
+    if len(dottedname) >= 1 and (dottedname[-1].endswith('property') or dottedname[-1].endswith('Property')):
+        # TODO: Support property subclasses.
+        return True
+    return False
+
+def looks_like_property_func_decorator(dottedname:List[str], ctx:model.Documentable) -> bool:
+    """
+    Whether the last element of the list of names is "getter", "setter" or "deleter". 
+    Won't match C{['geter']}, because we require the list to have a least 2 elements.
+    """
+    if len(dottedname) >= 2 and dottedname[-1] in ('getter' ,'setter', 'deleter'):
+        return True
+    return False
+
+def get_inherited_property(dottedname:List[str], _parent: model.Documentable) -> Optional[model.PropertyDef]:
+    """
+    Fetch the inherited property that this new decorator overrides.
+    None if it doesn't exist.
+    """
+    if not get_property_function_kind(dottedname):
+        return None
+
+    _property_name = dottedname[:-1]
+
+    if len(_property_name) <= 1 or _property_name[-1] in _parent.contents:
+        # the property already exist
+        return None
+
+    # attr can be a getter/setter/deleter
+    _cls = _parent.resolveName('.'.join(_property_name[:-1]))
+    if _cls is None or not isinstance(_cls, model.Class):
+        # Can't make sens of property decorator
+        # the property decorator is pointing to something external OR 
+        # not found in the system yet because of cyclic imports
+        # OR to something else than a class :/
+        # Don't rename it.
+        return None
+
+    # The class on which the property is defined (_cls) does not have
+    # to be in the MRO of the parent
+    attr_def = _cls.find(_property_name[-1])
+    if not isinstance(attr_def, model.Attribute):
+        return None
+
+    if not attr_def.kind is model.DocumentableKind.PROPERTY:
+        return None
+
+    return attr_def.property_def
+
+def get_property_function_kind(dottedname:List[str]) -> Optional[model.PropertyFunctionKind]:
+    """
+    What kind of property function this decorator declares?
+    None if we can't make sens of the decorator.
+    """
+    if dottedname:
+        if dottedname[-1] == 'setter':
+            return model.PropertyFunctionKind.SETTER
+        if dottedname[-1] == 'getter':
+            return model.PropertyFunctionKind.GETTER
+        if dottedname[-1] == 'deleter':
+            return model.PropertyFunctionKind.DELETER
+    return None
+
 class ModuleVistor(NodeVisitor):
 
     def __init__(self, builder: 'ASTBuilder', module: model.Module):
@@ -766,41 +834,84 @@ def _handleFunctionDef(self,
         func_name = node.name
 
         # determine the function's kind
-        is_property = False
+
         is_classmethod = False
         is_staticmethod = False
         is_overload_func = False
+
+        is_property = False
+        property_decorator_dottedname: Optional[List[str]] = None
+
         if node.decorator_list:
-            for d in node.decorator_list:
-                if isinstance(d, ast.Call):
-                    deco_name = node2dottedname(d.func)
-                else:
-                    deco_name = node2dottedname(d)
+            for deco_name, _ in astutils.iter_decorator_list(node.decorator_list):
                 if deco_name is None:
                     continue
                 if isinstance(parent, model.Class):
-                    if deco_name[-1].endswith('property') or deco_name[-1].endswith('Property'):
+                    if is_property_def_decorator(deco_name, parent):
                         is_property = True
                     elif deco_name == ['classmethod']:
                         is_classmethod = True
                     elif deco_name == ['staticmethod']:
                         is_staticmethod = True
-                    elif len(deco_name) >= 2 and deco_name[-1] in ('setter', 'deleter'):
+                        # Pre-handle property elements
+                    elif looks_like_property_func_decorator(deco_name, parent):
+                        # Setters and deleters should have the same name as the property function,
+                        # otherwise ignore it.
+                        # This pollutes the namespace unnecessarily and is generally not recommended. 
+                        # Therefore it makes sense to stick to a single name, 
+                        # which is consistent with the former property definition.
+                        if not deco_name[-2] == func_name:
+                            continue 
+
                         # Rename the setter/deleter, so it doesn't replace
                         # the property object.
+
                         func_name = '.'.join(deco_name[-2:])
+                        property_decorator_dottedname = deco_name
+
                 # Determine if the function is decorated with overload
                 if parent.expandName('.'.join(deco_name)) in ('typing.overload', 'typing_extensions.overload'):
                     is_overload_func = True
 
-        if is_property:
-            # handle property and skip child nodes.
-            attr = self._handlePropertyDef(node, docstring, lineno)
-            if is_classmethod:
-                attr.report(f'{attr.fullName()} is both property and classmethod')
-            if is_staticmethod:
-                attr.report(f'{attr.fullName()} is both property and staticmethod')
-            raise self.SkipNode()
+
+        func_property: Optional[model.Attribute] = None
+        prop_func_kind: Optional[model.PropertyFunctionKind] = None
+        is_new_property: bool = is_property
+
+        if property_decorator_dottedname is not None:
+
+            prop_func_kind = get_property_function_kind(property_decorator_dottedname)
+
+            # Looks like inherited property
+            if len(property_decorator_dottedname)>2:
+                inherited_property = get_inherited_property(property_decorator_dottedname, parent)
+                if inherited_property:
+                    func_property = self.builder.addAttribute(node.name, 
+                            kind=model.DocumentableKind.PROPERTY, 
+                            parent=parent)
+                    func_property.setLineNumber(lineno)
+                    func_property.decorators = node.decorator_list
+                    # copy property info
+                    func_property.property_def = inherited_property.clone()
+                    is_new_property = True
+
+            else:
+                # fetch property info to add this info to it
+                maybe_prop = self.builder.current.contents.get(node.name)
+                if isinstance(maybe_prop, model.Attribute) and maybe_prop.property_def:
+                    func_property = maybe_prop
+
+        elif is_property:
+            func_property = self.builder.addAttribute(node.name, 
+                        kind=model.DocumentableKind.PROPERTY, 
+                        parent=parent)
+            func_property.setLineNumber(lineno)
+            func_property.decorators = node.decorator_list
+            prop_func_kind = model.PropertyFunctionKind.GETTER
+            # rename func X.getter
+            func_name = node.name+'.getter'
+
+        # Push and analyse function 
 
         # Check if it's a new func or exists with an overload
         existing_func = parent.contents.get(func_name)
@@ -815,7 +926,14 @@ def _handleFunctionDef(self,
             # Do not recreate function object, just re-push it
             self.builder.push(existing_func, lineno)
             func = existing_func
+        elif isinstance(existing_func, model.Function) and func_property is not None and not is_new_property:
+            # Check if this property function is overriding a previously defined
+            # property function on the same scope before pushing the new function
+            # If it does override something, just re-push the function, do not override it.
+            self.builder.push(existing_func, lineno)
+            func = existing_func
         else:
+            # create new function
             func = self.builder.pushFunction(func_name, lineno)
 
         func.is_async = is_async
@@ -887,48 +1005,25 @@ def add_arg(name: str, kind: Any, default: Optional[ast.expr]) -> None:
             func.overloads.append(model.FunctionOverload(primary=func, signature=signature, decorators=node.decorator_list))
         else:
             func.signature = signature
+
+        if func_property is not None:
+
+            if is_classmethod:
+                func_property.report(f'{func_property.fullName()} is both property and classmethod')
+            if is_staticmethod:
+                func_property.report(f'{func_property.fullName()} is both property and staticmethod')
+
+            assert prop_func_kind is not None
+            # Store the fact that this function implements one of the getter/setter/deleter
+            func_property.property_def.set(prop_func_kind, func)
+
 
     def depart_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
         self.builder.popFunction()
 
     def depart_FunctionDef(self, node: ast.FunctionDef) -> None:
         self.builder.popFunction()
 
-    def _handlePropertyDef(self,
-            node: Union[ast.AsyncFunctionDef, ast.FunctionDef],
-            docstring: Optional[ast.Str],
-            lineno: int
-            ) -> model.Attribute:
-
-        attr = self.builder.addAttribute(name=node.name, kind=model.DocumentableKind.PROPERTY, parent=self.builder.current)
-        attr.setLineNumber(lineno)
-
-        if docstring is not None:
-            attr.setDocstring(docstring)
-            assert attr.docstring is not None
-            pdoc = epydoc2stan.parse_docstring(attr, attr.docstring, attr)
-            other_fields = []
-            for field in pdoc.fields:
-                tag = field.tag()
-                if tag == 'return':
-                    if not pdoc.has_body:
-                        pdoc = field.body()
-                        # Avoid format_summary() going back to the original
-                        # empty-body docstring.
-                        attr.docstring = ''
-                elif tag == 'rtype':
-                    attr.parsed_type = field.body()
-                else:
-                    other_fields.append(field)
-            pdoc.fields = other_fields
-            attr.parsed_docstring = pdoc
-
-        if node.returns is not None:
-            attr.annotation = unstring_annotation(node.returns, attr)
-        attr.decorators = node.decorator_list
-
-        return attr
-
     def _annotations_from_function(
             self, func: Union[ast.AsyncFunctionDef, ast.FunctionDef]
             ) -> Mapping[str, Optional[ast.expr]]:
@@ -1155,6 +1250,9 @@ def addAttribute(self,
         parentMod = self.currentMod
         attr = system.Attribute(system, name, parent)
         attr.kind = kind
+        if kind is model.DocumentableKind.PROPERTY:
+            # init property info if this attribute is a property
+            attr.property_def = model.PropertyDef()
         attr.parentMod = parentMod
         system.addObject(attr)
         self.currentAttr = attr

pydoctor/astutils.py

@@ -191,6 +191,14 @@ def is_using_annotations(expr: Optional[ast.AST],
                 return True
     return False
 
+def iter_decorator_list(decorator_list:Iterable[ast.expr]) -> Iterator[Tuple[Optional[List[str]], ast.expr]]:
+    for d in decorator_list:
+        if isinstance(d, ast.Call):
+            deco_name = node2dottedname(d.func)
+        else:
+            deco_name = node2dottedname(d)
+        yield deco_name,d
+
 def is_none_literal(node: ast.expr) -> bool:
     """Does this AST node represent the literal constant None?"""
     return isinstance(node, (ast.Constant, ast.NameConstant)) and node.value is None