More robust s-a-t patch (#123)

Author: flying-sheep

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.11
+    rev: v0.1.12
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

.vscode/launch.json

@@ -5,13 +5,23 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Python Debugger: Current File",
+            "name": "Debug current File",
             "type": "debugpy",
             "request": "launch",
             "program": "${file}",
             "pythonArgs": ["-Xfrozen_modules=off"],
             "console": "internalConsole",
             "justMyCode": false,
         },
+        {
+            "name": "Build Documentation",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "sphinx",
+            "args": ["-M", "html", ".", "_build"],
+            "cwd": "${workspaceFolder}/docs",
+            "console": "internalConsole",
+            "justMyCode": false,
+        },
     ],
 }

src/scanpydoc/elegant_typehints/__init__.py

@@ -53,11 +53,14 @@ def x() -> Tuple[int, float]:
 from dataclasses import dataclass
 
 from sphinx.ext.autodoc import ClassDocumenter
-from sphinx.ext.napoleon import NumpyDocstring  # type: ignore[attr-defined]
 
 from scanpydoc import metadata, _setup_sig
 
-from .example import example_func_prose, example_func_tuple
+from .example import (
+    example_func_prose,
+    example_func_tuple,
+    example_func_anonymous_tuple,
+)
 
 
 if TYPE_CHECKING:
@@ -68,7 +71,12 @@ def x() -> Tuple[int, float]:
     from sphinx.application import Sphinx
 
 
-__all__ = ["example_func_prose", "example_func_tuple", "setup"]
+__all__ = [
+    "example_func_prose",
+    "example_func_tuple",
+    "example_func_anonymous_tuple",
+    "setup",
+]
 
 
 HERE = Path(__file__).parent.resolve()
@@ -124,10 +132,8 @@ def setup(app: Sphinx) -> dict[str, Any]:
         ClassDocumenter.add_directive_header,
     )
 
-    from ._return_tuple import process_docstring  # , process_signature
-    from ._return_patch_numpydoc import _parse_returns_section
+    from . import _return_tuple
 
-    NumpyDocstring._parse_returns_section = _parse_returns_section  # type: ignore[method-assign,assignment]  # noqa: SLF001
-    app.connect("autodoc-process-docstring", process_docstring)
+    _return_tuple.setup(app)
 
     return metadata

src/scanpydoc/elegant_typehints/_return_patch_numpydoc.py

@@ -7,6 +7,7 @@
 from typing import Tuple as t_Tuple  # noqa: UP035
 from logging import getLogger
 
+from sphinx.ext.napoleon import NumpyDocstring  # type: ignore[attr-defined]
 from sphinx_autodoc_typehints import format_annotation
 
 
@@ -26,6 +27,8 @@
     UNION_TYPES = {Union}
 
 
+__all__ = ["process_docstring", "_parse_returns_section", "setup"]
+
 logger = getLogger(__name__)
 re_ret = re.compile("^:returns?: ")
 
@@ -76,7 +79,11 @@ def process_docstring(  # noqa: PLR0913
     if len(idxs_ret_names) == len(ret_types):
         for l, rt in zip(idxs_ret_names, ret_types):
             typ = format_annotation(rt, app.config)
-            lines[l : l + 1] = [f"{lines[l]} : {typ}"]
+            if (line := lines[l]).lstrip() in {":returns: :", ":return: :", ":"}:
+                transformed = f"{line[:-1]}{typ}"
+            else:
+                transformed = f"{line} : {typ}"
+            lines[l : l + 1] = [transformed]
 
 
 def _get_idxs_ret_names(lines: Sequence[str]) -> list[int]:
@@ -100,6 +107,40 @@ def _get_idxs_ret_names(lines: Sequence[str]) -> list[int]:
     # Meat
     idxs_ret_names = []
     for l, line in enumerate([l[i_prefix:] for l in lines[l_start : l_end + 1]]):
-        if line.isidentifier() and lines[l + l_start + 1].startswith("    "):
+        if (line == ":" or line.isidentifier()) and (
+            lines[l + l_start + 1].startswith("    ")
+        ):
             idxs_ret_names.append(l + l_start)
     return idxs_ret_names
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:  # noqa: ARG001
+    """Parse return section as prose instead of tuple by default."""
+    lines_raw = list(self._dedent(self._consume_to_next_section()))
+    lines = self._format_block(":returns: ", lines_raw)
+    if lines and lines[-1]:
+        lines.append("")
+    return lines
+
+
+def _delete_sphinx_autodoc_typehints_docstring_processor(app: Sphinx) -> None:
+    for listener in app.events.listeners["autodoc-process-docstring"].copy():
+        handler_name = getattr(listener.handler, "__name__", None)
+        # https://github.com/tox-dev/sphinx-autodoc-typehints/blob/a5c091f725da8374347802d54c16c3d38833d41c/src/sphinx_autodoc_typehints/patches.py#L69
+        if handler_name == "napoleon_numpy_docstring_return_type_processor":
+            app.disconnect(listener.id)
+
+
+def setup(app: Sphinx) -> None:
+    """Patches the Sphinx app and :mod:`sphinx.ext.napoleon` in some ways.
+
+    1. Replaces the return section parser of napoleon’s NumpyDocstring
+       with one that just adds a prose section.
+    2. Removes sphinx-autodoc-typehints’s docstring processor that expects
+       NumpyDocstring’s old behavior.
+    2. Adds our own docstring processor that adds tuple return types
+       If the docstring contains a definition list of appropriate length.
+    """
+    NumpyDocstring._parse_returns_section = _parse_returns_section  # type: ignore[method-assign,assignment]  # noqa: SLF001
+    _delete_sphinx_autodoc_typehints_docstring_processor(app)
+    app.connect("autodoc-process-docstring", process_docstring, 1000)

src/scanpydoc/elegant_typehints/_return_tuple.py

@@ -31,3 +31,16 @@ def example_func_tuple() -> tuple[int, str]:  # pragma: no cover
         An example str
     """
     return (1, "foo")
+
+
+def example_func_anonymous_tuple() -> tuple[int, str]:  # pragma: no cover
+    """Example function with anonymous return tuple.
+
+    Returns
+    -------
+    :
+        An example int
+    :
+        An example str
+    """
+    return (1, "foo")

src/scanpydoc/elegant_typehints/example.py

@@ -122,7 +122,7 @@ def _get_annotations(obj: _SourceObjectType) -> dict[str, Any]:
         from get_annotations import get_annotations
 
     try:
-        return get_annotations(obj)  # type: ignore[arg-type]
+        return get_annotations(obj)  # type: ignore[no-any-return,arg-type,unused-ignore]
     except TypeError:  # pragma: no cover
         return {}
 

src/scanpydoc/rtd_github_links/__init__.py

@@ -29,7 +29,11 @@ def test_all_get_installed(
         scanpydoc.__path__, f"{scanpydoc.__name__}."
     ):
         mod = import_module(mod_name)
-        if mod_name in DEPRECATED or not hasattr(mod, "setup"):
+        if (
+            mod_name in DEPRECATED
+            or any(m.startswith("_") for m in mod_name.split("."))
+            or not hasattr(mod, "setup")
+        ):
             continue
         setups_seen.add(mod_name)
         monkeypatch.setattr(mod, "setup", partial(setups_called.__setitem__, mod_name))

tests/test_base.py

@@ -17,18 +17,13 @@
     get_origin,
 )
 from pathlib import Path
+from operator import attrgetter
 from collections.abc import Mapping, Callable
 
 import pytest
-import sphinx_autodoc_typehints as sat
-from sphinx.ext import napoleon
 from sphinx.errors import ExtensionError
-from sphinx_autodoc_typehints.patches import (
-    napoleon_numpy_docstring_return_type_processor,
-)
 
 from scanpydoc.elegant_typehints._formatting import typehints_formatter
-from scanpydoc.elegant_typehints._return_tuple import process_docstring
 
 
 if TYPE_CHECKING:
@@ -81,6 +76,16 @@ def app(make_app_setup: Callable[..., Sphinx]) -> Sphinx:
 
 @pytest.fixture()
 def process_doc(app: Sphinx) -> ProcessDoc:
+    listeners = sorted(
+        (l for l in app.events.listeners["autodoc-process-docstring"]),
+        key=attrgetter("priority"),
+    )
+    assert [f"{l.handler.__module__}.{l.handler.__qualname__}" for l in listeners] == [
+        "sphinx.ext.napoleon._process_docstring",
+        "sphinx_autodoc_typehints.process_docstring",
+        "scanpydoc.elegant_typehints._return_tuple.process_docstring",
+    ]
+
     def process(fn: Callable[..., Any], *, run_napoleon: bool = False) -> list[str]:
         lines = (inspect.getdoc(fn) or "").split("\n")
         if isinstance(fn, property):
@@ -89,13 +94,13 @@ def process(fn: Callable[..., Any], *, run_napoleon: bool = False) -> list[str]:
             name = fn.__name__
         else:
             name = "???"
-        napoleon_numpy_docstring_return_type_processor(
-            app, "function", name, fn, None, lines
-        )
-        if run_napoleon:
-            napoleon._process_docstring(app, "function", name, fn, None, lines)  # noqa: SLF001
-        sat.process_docstring(app, "function", name, fn, None, lines)
-        process_docstring(app, "function", name, fn, None, lines)
+        for listener in listeners:
+            if (
+                not run_napoleon
+                and listener.handler.__module__ == "sphinx.ext.napoleon"
+            ):
+                continue
+            listener.handler(app, "function", name, fn, None, lines)
         return lines
 
     return process
@@ -402,6 +407,32 @@ def fn_test() -> None:  # pragma: no cover
         ]
 
 
+def test_return_tuple_anonymous(process_doc: ProcessDoc) -> None:
+    def fn_test() -> tuple[int, str]:  # pragma: no cover
+        """
+        Returns
+        -------
+        :
+            An int!
+        :
+            A str!
+        """  # noqa: D401, D205
+        return (1, "foo")
+
+    lines = [
+        l
+        for l in process_doc(fn_test, run_napoleon=True)
+        if l
+        if not re.match(r"^:(rtype|param)( \w+)?:", l)
+    ]
+    assert lines == [
+        ":returns: :py:class:`int`",
+        "              An int!",
+        "          :py:class:`str`",
+        "              A str!",
+    ]
+
+
 def test_return_nodoc(process_doc: ProcessDoc) -> None:
     def fn() -> tuple[int, str]:  # pragma: no cover
         """No return section."""