Handling of attrs and dataclass constructors

README.rst

@@ -153,6 +153,12 @@ This is the last major release to support Python 3.7.
 * Astor is no longer a requirement starting at Python 3.9.
 * `ExtRegistrar.register_post_processor()` now supports a `priority` argument that is an int.
   Highest priority callables will be called first during post-processing.
+* Better ``attrs`` support: generate precise ``__init__`` method from analyzed fields, supports 
+  principal ``attrs`` idioms: 
+   - ``attr.s(auto_attribs, kw_only, auto_detect, init)``/``attrs.define(...)``
+   - ``attr.ib(init, default, factory, converter, type, kw_only)``/``attrs.field(...)``
+   - ``attr.Factory(list)``
+  It does not support the decorators based syntax for setting the validator/factory/default or converter.
 * Fix too noisy ``--verbose`` mode (suppres some ambiguous annotations warnings).
 * Fix type processing inside restructuredtext consolidated fields.
 * Add options ``--cls-member-order`` and ``--mod-member-order`` to customize the presentation

docs/source/codedoc.rst

@@ -26,8 +26,7 @@ Pydoctor also supports *attribute docstrings*::
         """This docstring describes a class variable."""
 
         def __init__(self):
-            self.ivar = []
-            """This docstring describes an instance variable."""
+            self.ivar = [];"It can also be used inline."
 
 Attribute docstrings are not part of the Python language itself (`PEP 224 <https://www.python.org/dev/peps/pep-0224/>`_ was rejected), so these docstrings are not available at runtime.
 
@@ -284,6 +283,45 @@ If you are using explicit ``attr.ib`` definitions instead of ``auto_attribs``, p
         list_of_numbers = attr.ib(factory=list)  # type: List[int]
         """Multiple numbers."""
 
+Pydoctor look for ``attrs`` fields declarations and analyze the 
+arguments passed to ``attr.s`` and ``attr.ib`` in order to
+precisely infer what's the signature of the constructor method::
+
+    from typing import List
+    import pathlib
+    import attr
+
+    def convert_paths(p:List[str]) -> List[pathlib.Path]:
+        return [pathlib.Path(s) for s in p]
+
+    @attr.s(auto_attribs=True)
+    class Base:
+        a: int
+
+    @attr.s(auto_attribs=True, kw_only=True)
+    class SomeClass(Base):
+        a_number:int=42; "docstring of number A."
+        list_of_numbers:List[int] = attr.ib(factory=list); "List of ints"
+        converted_paths:List[pathlib.Path] = attr.ib(converter=convert_paths, factory=list); "Uses a converter"
+
+The constrcutor method will be documented as if it was explicitly defined,
+with a docstring including documentation of each parameters and a note 
+saying the method is generated by attrs::
+
+    def __init__(self, *, a: int, a_number: int = 42, 
+                 list_of_numbers: List[int] = list(), 
+                 converted_paths: List[str] = list()):
+        """
+        attrs generated method
+
+        @param a_number: docstring of number A.
+        @param list_of_numbers: C{attr.ib(factory=list)}
+            List of ints
+        @param converted_paths: C{attr.ib(converter=convert_paths, factory=list)}
+            Uses a converter
+        """
+
+Pydoctor also supports the newer APIs (``attrs.define``/``attrs.field``).
 
 Private API
 -----------

pydoctor/astbuilder.py

@@ -10,14 +10,21 @@
 from pathlib import Path
 from typing import (
     Any, Callable, Collection, Dict, Iterable, Iterator, List, Mapping, Optional, Sequence, Tuple,
-    Type, TypeVar, Union, Set, cast
+    Type, TypeVar, Union, Set, cast, TYPE_CHECKING
 )
+from pydoctor import epydoc2stan, model, extensions
 
 from pydoctor import epydoc2stan, model, extensions
 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, upgrade_annotation, iterassign, extract_docstring_linenum, infer_type, get_parents,
                                get_docstring_node, get_assign_docstring_node, unparse, NodeVisitor, Parentage, Str)
 
+
+if TYPE_CHECKING:
+    from typing import Protocol
+else:
+    Protocol = object
+
 def parseFile(path: Path) -> ast.Module:
     """Parse the contents of a Python source file."""
     with open(path, 'rb') as f:

pydoctor/astutils.py

@@ -3,10 +3,12 @@
 """
 from __future__ import annotations
 
+import enum
 import inspect
 import sys
 from numbers import Number
-from typing import Any, Callable, Collection, Iterator, Optional, List, Iterable, Sequence, TYPE_CHECKING, Tuple, Union, cast
+from typing import (Any, Callable, Collection, Iterator, Optional, List, Iterable,
+                    Sequence, TYPE_CHECKING, Tuple, Union, Type, TypeVar, cast)
 from inspect import BoundArguments, Signature
 import ast
 
@@ -16,6 +18,9 @@
 
 if TYPE_CHECKING:
     from pydoctor import model
+    from typing import Protocol, Literal
+else:
+    Protocol = Literal = object
 
 # AST visitors
 
@@ -88,6 +93,19 @@
         dottedname = node2dottedname(target) 
         yield dottedname
 
+def iter_decorators(decorator_list:List[ast.expr], 
+                    ctx: model.Documentable) -> Iterator[tuple[str|None, ast.AST]]:
+    """
+    Utility function to iterate decorators.
+    """
+
+    for decnode in decorator_list:
+        namenode = decnode
+        if isinstance(namenode, ast.Call):
+            namenode = namenode.func
+        dottedname = node2fullname(namenode, ctx)
+        yield dottedname, decnode
+
 def node2dottedname(node: Optional[ast.AST]) -> Optional[List[str]]:
     """
     Resove expression composed by L{ast.Attribute} and L{ast.Name} nodes to a list of names. 
@@ -103,6 +121,17 @@
     parts.reverse()
     return parts
 
+def dottedname2node(parts:List[str]) -> Union[ast.Name, ast.Attribute]:
+    """
+    Reverse operation of L{node2dottedname}.
+    """
+    assert parts, "must not be empty"
+
+    if len(parts)==1:
+        return ast.Name(parts[0], ast.Load())
+    else:
+        return ast.Attribute(dottedname2node(parts[:-1]), parts[-1], ast.Load())
+
 def node2fullname(expr: Optional[ast.AST], 
                   ctx: model.Documentable | None = None, 
                   *,
@@ -537,6 +566,113 @@
     lineno = extract_docstring_linenum(node)
     return lineno, inspect.cleandoc(value)
 
+def safe_bind_args(sig:Signature, call: ast.AST, ctx: model.Documentable) -> Optional[inspect.BoundArguments]:
+    """
+    Binds the arguments of a function call to that function's signature.
+
+    When L{bind_args} raises a L{TypeError}, it reports a warning and returns C{None}. 
+    """
+    if not isinstance(call, ast.Call):
+        return None
+    try:
+        return bind_args(sig, call)
+    except TypeError as ex:
+        message = str(ex).replace("'", '"')
+        call_dottedname = node2dottedname(call.func)
+        callable_name = f"{'.'.join(call_dottedname)}()" if call_dottedname else 'callable'
+        ctx.module.report(
+            f"Invalid arguments for {callable_name}: {message}",
+            lineno_offset=call.lineno
+            )
+        return None
+
+class _V(enum.Enum): 
+    NoValue = enum.auto()
+_T =  TypeVar('_T', bound=object)
+def _get_literal_arg(args:BoundArguments, name:str, 
+                     typecheck:Union[Type[_T], Tuple[Type[_T],...]]) -> Union['Literal[_V.NoValue]', _T]:
+    """
+    Helper function for L{get_literal_arg}. 
+
+    If the value is not present in the arguments, returns L{_V.NoValue}.
+    @raises ValueError: If the passed value is not a literal or if it's not the right type.
+    """
+    expr = args.arguments.get(name)
+    if expr is None:
+        return _V.NoValue
+
+    try:
+        value = ast.literal_eval(expr)
+    except ValueError:
+        message = (
+            f'Unable to figure out value for {name!r} argument, maybe too complex'
+            ).replace("'", '"')
+        raise ValueError(message)
+
+    if not isinstance(value, typecheck):
+        expected_type = " or ".join(repr(t.__name__) for t in (typecheck if isinstance(typecheck, tuple) else (typecheck,)))
+        message = (f'Value for {name!r} argument '
+            f'has type "{type(value).__name__}", expected {expected_type}'
+            ).replace("'", '"')
+        raise ValueError(message)
+
+    return value #type:ignore
+
+def get_literal_arg(args:BoundArguments, name:str, default:_T, 
+                          typecheck: Union[Type[_T], Tuple[Type[_T],...]], 
+                          lineno:int, ctx: model.Documentable) -> _T:
+    """
+    Retreive the literal value of an argument from the L{BoundArguments}. 
+    Only works with purely literal values (no C{Name} or C{Attribute}).
+
+    @param args: The L{BoundArguments} instance.
+    @param name: The name of the argument
+    @param default: The default value of the argument, this value is returned 
+        if the argument is not found.
+    @param typecheck: The type of the literal value this argument is expected to have.
+    @param lineno: The lineumber of the callsite, used for error reporting.
+    @param module: Module that contains the call, used for error reporting.
+    @return: The value of the argument if we can infer it, otherwise returns
+        the default value.
+    """
+    try:
+        value = _get_literal_arg(args, name, typecheck)
+    except ValueError as e:
+        ctx.module.report(str(e), lineno_offset=lineno)
+        return default
+    if value is _V.NoValue:
+        # default value
+        return default
+    else:
+        return value
+
+_SCOPE_TYPES = (ast.SetComp, ast.DictComp, ast.ListComp, ast.GeneratorExp, 
+           ast.Lambda, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+_ClassInfo = Union[Type[Any], Tuple[Type[Any],...]]
+
+def _collect_nodes(node:ast.AST, typecheck:_ClassInfo, 
+                   stop_typecheck:_ClassInfo=_SCOPE_TYPES) -> Sequence[ast.AST]:
+    class _Collector(ast.NodeVisitor):
+        def __init__(self) -> None:
+            self.collected:List[ast.AST] = []
+        def _collect(self, node:ast.AST) -> None:
+            if isinstance(node, typecheck):
+                self.collected.append(node)
+        def generic_visit(self, node: ast.AST) -> None:
+            self._collect(node)
+            if not isinstance(node, stop_typecheck):
+                super().generic_visit(node)
+
+    visitor = _Collector()
+    ast.NodeVisitor.generic_visit(visitor, node)
+    return visitor.collected
+
+def collect_assigns(node:ast.AST) -> Sequence[Union[ast.Assign, ast.AnnAssign]]:
+    """
+    Returns a list of L{ast.Assign} or L{ast.AnnAssign} declared in the given scope.
+    It does not include assignments in nested scopes.
+    """
+    return _collect_nodes(node, (ast.Assign, ast.AnnAssign)) #type:ignore
 
 def infer_type(expr: ast.expr) -> Optional[ast.expr]:
     """Infer a literal expression's type.

pydoctor/epydoc/markup/__init__.py

@@ -238,7 +238,6 @@ def parsed_text(text: str,
     return ParsedRstDocstring(set_node_attributes(new_document(source), 
             children=[text_node(text, klass) 
                       if klass else nodes.Text(text)]), ())
-
 
 ##################################################
 ## Fields

pydoctor/epydoc/markup/plaintext.py

@@ -68,7 +68,7 @@ def to_node(self) -> nodes.document:
             paragraphs = [set_node_attributes(nodes.paragraph('',''), children=[
                             set_node_attributes(nodes.Text(p.strip('\n')), document=_document, lineno=0)], 
                             document=_document, lineno=0)
-                                for p in self._text.split('\n\n')] 
+                                for p in self._text.split('\n\n') if p not in ('', '\n')] 
 
             # assemble document
             _document = set_node_attributes(_document,