Wrap signatures onto several lines when function len is over a treshold and function has the focus

pydoctor/astbuilder.py

@@ -13,12 +13,14 @@
     Type, TypeVar, Union, Set, cast
 )
 
-from pydoctor import epydoc2stan, model, node2stan, extensions, linker
-from pydoctor.epydoc.markup._pyval_repr import colorize_inline_pyval
+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)
 
+class InvalidSignatureParamName(str):
+    def isidentifier(self) -> bool:
+        return True
 
 def parseFile(path: Path) -> ast.Module:
     """Parse the contents of a Python source file."""
@@ -1032,9 +1034,9 @@ def get_default(index: int) -> Optional[ast.expr]:
 
         parameters: List[Parameter] = []
         def add_arg(name: str, kind: Any, default: Optional[ast.expr]) -> None:
-            default_val = Parameter.empty if default is None else _ValueFormatter(default, ctx=func)
+            default_val = Parameter.empty if default is None else default
                                                                                # this cast() is safe since we're checking if annotations.get(name) is None first
-            annotation = Parameter.empty if annotations.get(name) is None else _AnnotationValueFormatter(cast(ast.expr, annotations[name]), ctx=func)
+            annotation = Parameter.empty if annotations.get(name) is None else cast(ast.expr, annotations[name])
             parameters.append(Parameter(name, kind, default=default_val, annotation=annotation))
 
         for index, arg in enumerate(posonlyargs):
@@ -1056,12 +1058,15 @@ def add_arg(name: str, kind: Any, default: Optional[ast.expr]) -> None:
             add_arg(kwarg.arg, Parameter.VAR_KEYWORD, None)
 
         return_type = annotations.get('return')
-        return_annotation = Parameter.empty if return_type is None or is_none_literal(return_type) else _AnnotationValueFormatter(return_type, ctx=func)
+        return_annotation = Parameter.empty if return_type is None or is_none_literal(return_type) else return_type
         try:
             signature = Signature(parameters, return_annotation=return_annotation)
         except ValueError as ex:
             func.report(f'{func.fullName()} has invalid parameters: {ex}')
-            signature = Signature()
+            # Craft an invalid signature that does not look like a function with zero arguments.
+            signature = Signature(
+                [Parameter(InvalidSignatureParamName('...'), 
+                           kind=Parameter.POSITIONAL_OR_KEYWORD)])
 
         func.annotations = annotations
 
@@ -1120,7 +1125,7 @@ def _annotations_from_function(
         @param func: The function definition's AST.
         @return: Mapping from argument name to annotation.
             The name C{return} is used for the return type.
-            Unannotated arguments are omitted.
+            Unannotated arguments are still included with a None value.
         """
         def _get_all_args() -> Iterator[ast.arg]:
             base_args = func.args
@@ -1153,47 +1158,7 @@ def _get_all_ast_annotations() -> Iterator[Tuple[str, Optional[ast.expr]]]:
                 value, self.builder.current), self.builder.current)
             for name, value in _get_all_ast_annotations()
             }
-
-class _ValueFormatter:
-    """
-    Class to encapsulate a python value and translate it to HTML when calling L{repr()} on the L{_ValueFormatter}.
-    Used for presenting default values of parameters.
-    """
-
-    def __init__(self, value: ast.expr, ctx: model.Documentable):
-        self._colorized = colorize_inline_pyval(value)
-        """
-        The colorized value as L{ParsedDocstring}.
-        """
-
-        self._linker = ctx.docstring_linker
-        """
-        Linker.
-        """
 
-    def __repr__(self) -> str:
-        """
-        Present the python value as HTML. 
-        Without the englobing <code> tags.
-        """
-        # Using node2stan.node2html instead of flatten(to_stan()). 
-        # This avoids calling flatten() twice, 
-        # but potential XML parser errors caused by XMLString needs to be handled later.
-        return ''.join(node2stan.node2html(self._colorized.to_node(), self._linker))
-
-class _AnnotationValueFormatter(_ValueFormatter):
-    """
-    Special L{_ValueFormatter} for function annotations.
-    """
-    def __init__(self, value: ast.expr, ctx: model.Function):
-        super().__init__(value, ctx)
-        self._linker = linker._AnnotationLinker(ctx)
-
-    def __repr__(self) -> str:
-        """
-        Present the annotation wrapped inside <code> tags.
-        """
-        return '<code>%s</code>' % super().__repr__()
 
 DocumentableT = TypeVar('DocumentableT', bound=model.Documentable)
 

pydoctor/epydoc/markup/__init__.py

@@ -33,7 +33,9 @@
 from __future__ import annotations
 __docformat__ = 'epytext en'
 
-from typing import Callable, ContextManager, List, Optional, Sequence, Iterator, TYPE_CHECKING
+import contextlib
+from itertools import chain
+from typing import Callable, ContextManager, Iterable, List, Optional, Sequence, Iterator, TYPE_CHECKING
 import abc
 import sys
 import re
@@ -129,7 +131,7 @@
     markup parsers such as L{pydoctor.epydoc.markup.epytext.parse_docstring()}
     or L{pydoctor.epydoc.markup.restructuredtext.parse_docstring()}.
 
-    Subclasses must implement L{has_body()} and L{to_node()}.
+    Subclasses must at least implement L{has_body()} and L{to_node()}.
 
     A default implementation for L{to_stan()} method, relying on L{to_node()} is provided.
     But some subclasses override this behaviour.
@@ -143,11 +145,10 @@
         A list of L{Field}s, each of which encodes a single field.
         The field's bodies are encoded as C{ParsedDocstring}s.
         """
-
         self._stan: Optional[Tag] = None
-        self._summary: Optional['ParsedDocstring'] = None
 
-    @abc.abstractproperty
+    @property  
+    @abc.abstractmethod  
     def has_body(self) -> bool:
         """
         Does this docstring have a non-empty body?
@@ -168,7 +169,6 @@
         docstring_toc = new_document('toc')
         if contents:
             docstring_toc.extend(contents)
-            from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring
             return ParsedRstDocstring(docstring_toc, ())
         else:
             return None
@@ -203,25 +203,115 @@
         """
         raise NotImplementedError()
 
+    def to_text(self) -> str:
+        """
+        Translate this docstring to a string.
+        The default implementation depends on L{to_node}.
+        """
+        doc = self.to_node()
+        return ''.join(node2stan.gettext(doc))
+
+    def with_tag(self, tag: Tag) -> ParsedDocstring:
+        """
+        Wraps the L{to_stan()} result inside the given tag. 
+
+        This is useful because some code strips the main tag to keep only it's content. 
+        With this trick, the main tag is preserved. It can also be used to add
+        a custom CSS class on top of an existing parsed docstring.
+        """
+        return _ParsedDocstringWithTag(self, tag)
+
+    @classmethod
+    def combine(cls, elements: Sequence[ParsedDocstring]) -> ParsedDocstring:
+        """
+        Combine the contents of several parsed docstrings into one. 
+        """
+        return _ParsedDocstringTree(elements)
+
     def get_summary(self) -> 'ParsedDocstring':
         """
         Returns the summary of this docstring.
-
-        @note: The summary is cached.
         """
-        # Avoid rare cyclic import error, see https://github.com/twisted/pydoctor/pull/538#discussion_r845668735
-        from pydoctor import epydoc2stan
-        if self._summary is not None:
-            return self._summary
         try: 
             _document = self.to_node()
             visitor = SummaryExtractor(_document)
             _document.walk(visitor)
         except Exception: 
-            self._summary = epydoc2stan.ParsedStanOnly(tags.span(class_='undocumented')("Broken summary"))
-        else:
-            self._summary = visitor.summary or epydoc2stan.ParsedStanOnly(tags.span(class_='undocumented')("No summary"))
-        return self._summary
+            return parsed_text_with_css('Broken summary', 'undocumented')
+
+        return visitor.summary or parsed_text_with_css('No summary', 'undocumented')
+
+
+class _ParsedDocstringTree(ParsedDocstring):
+    """
+    Several parsed docstrings into a single one.
+    """
+
+    def __init__(self, elements: Sequence[ParsedDocstring]):
+        super().__init__(tuple(chain.from_iterable(e.fields for e in elements)))
+        self._elements = elements
+        self._doc: nodes.document | None = None
+
+    @property
+    def has_body(self) -> bool: 
+        return any(e.has_body for e in self._elements)
+
+    @classmethod
+    def _generate_document(cls, elements: Iterable[ParsedDocstring]) -> nodes.document:
+        doc = new_document('composite')
+        for e in elements:
+            # TODO: Some parsed doctrings simply do not implement to_node().
+            # It should be really time to fix this...
+            subdoc = e.to_node()
+            # TODO: here all childrens might not have the same document property.
+            # this should not be a problem, but docutils is likely not meant to be used like that.
+            doc.children.extend(subdoc.children)
+        return doc
+
+    def to_node(self) -> nodes.document:
+        if not self._doc:
+            self._doc = self._generate_document(self._elements)
+        return self._doc
+
+    def to_stan(self, linker: DocstringLinker) -> Tag: 
+        stan = tags.transparent()
+        for e in self._elements:
+            stan(e.to_stan(linker).children)
+        return stan
+
+class _ParsedDocstringWithTag(ParsedDocstring):
+    """
+    Wraps a parsed docstring to wrap the result of the 
+    the to_stan() method inside a custom Tag.
+    """
+    def __init__(self, 
+                 other: ParsedDocstring, 
+                 tag: Tag):
+        super().__init__(other.fields)
+        self.wrapped = other
+        """
+        The wrapped parsed docstring.
+        """
+        self._tag = tag
+        self._stan: Tag | None = None
+
+    # We double wrap it with a transparent tag so the added tags survives ParsedDocstring.combine 
+    # wich combines the content of the main div of the stan, not the div itself.
+    def to_stan(self, linker: DocstringLinker) -> Tag:
+        # Since the stan is cached inside _stan attribute we can't simply use
+        # "lambda this, linker: tags.transparent(self._tag(this.to_stan(linker)))" as the new to_stan method. 
+        # this would not behave correctly because each time to_stan will be called, the content would be duplicated.
+        if (stan:=self._stan) is not None:
+            return stan
+        self._stan = stan = Tag('')(self._tag(self.wrapped.to_stan(linker)))
+        return stan
+
+    # Boring
+    def to_node(self) -> nodes.document:
+        return self.wrapped.to_node()
+    @property
+    def has_body(self) -> bool: 
+        return self.wrapped.has_body
 
 
 ##################################################
@@ -286,14 +376,16 @@
     target URL for crossreference links.
     """
 
-    def link_to(self, target: str, label: "Flattenable") -> Tag:
+    def link_to(self, target: str, label: "Flattenable", *, is_annotation: bool = False) -> Tag:
         """
         Format a link to a Python identifier.
         This will resolve the identifier like Python itself would.
 
         @param target: The name of the Python identifier that
             should be linked to.
         @param label: The label to show for the link.
+        @param is_annotation: Generated links will give precedence to the module
+            defined varaible rather the nested definitions when there are name colisions.
         @return: The link, or just the label if the target was not found.
         """
 
@@ -325,6 +417,20 @@
         in this case error will NOT be reported at all.
         """
 
+class NotFoundLinker(DocstringLinker):
+    """A DocstringLinker implementation that cannot find any links."""
+
+    def link_to(self, target: str, label: "Flattenable", *, is_annotation: bool = False) -> Tag:
+        return tags.transparent(label)
+
+    def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
+        return tags.code(label)
+
+    @contextlib.contextmanager
+    def switch_context(self, ob: Documentable | None) -> Iterator[None]:
+        yield
+
+
 ##################################################
 ## ParseError exceptions
 ##################################################
@@ -475,11 +581,13 @@
             set_node_attributes(nodes.paragraph('', ''), document=summary_doc, lineno=1, 
             children=summary_pieces)])
 
-        from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring
         self.summary = ParsedRstDocstring(summary_doc, fields=[])
 
     def visit_field(self, node: nodes.Node) -> None:
         raise nodes.SkipNode()
 
     def unknown_visit(self, node: nodes.Node) -> None:
         '''Ignore all unknown nodes'''
+
+
+from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring, parsed_text_with_css

pydoctor/epydoc/markup/_napoleon.py

@@ -4,12 +4,14 @@
 """
 from __future__ import annotations
 
-from typing import List, Optional, Type
+from typing import List, Optional, Type, TYPE_CHECKING
 
 from pydoctor.epydoc.markup import ParsedDocstring, ParseError, processtypes
 from pydoctor.epydoc.markup import restructuredtext
 from pydoctor.napoleon.docstring import GoogleDocstring, NumpyDocstring
-from pydoctor.model import Attribute, Documentable
+
+if TYPE_CHECKING:
+    from pydoctor.model import Documentable
 
 
 class NapoelonDocstringParser:
@@ -64,6 +66,8 @@ def _parse_docstring(
         errors: List[ParseError],
         docstring_cls: Type[GoogleDocstring],
     ) -> ParsedDocstring:
+        # TODO: would be best to avoid this import
+        from pydoctor.model import Attribute
 
         docstring_obj = docstring_cls(
             docstring, is_attribute=isinstance(self.obj, Attribute)