Merge pull request #119 from machow/fix-star-in-sig

fix: better support for rendering /, and * in signatures

Author: machow

quartodoc/renderers/md_renderer.py

@@ -325,16 +325,36 @@ def render(self, el: Union[dc.Object, dc.Alias]):
 
     @dispatch
     def render(self, el: dc.Parameters):
+        # index for switch from positional to kw args (via an unnamed *)
         try:
             kw_only = [par.kind for par in el].index(dc.ParameterKind.keyword_only)
         except ValueError:
             kw_only = None
+
+        # index for final positionly only args (via /)
+        try:
+            pos_only = max([ii for ii, el in enumerate(el) if el.kind == dc.ParameterKind.positional_only])
+        except ValueError:
+            pos_only = None
+
 
         pars = list(map(self.render, el))
 
-        if kw_only is not None:
+        # insert a single `*,` argument to represent the shift to kw only arguments,
+        # only if the shift to kw_only was not triggered by *args (var_positional)
+        if (
+            kw_only is not None
+            and kw_only > 0
+            and el[kw_only-1].kind != dc.ParameterKind.var_positional
+        ):
             pars.insert(kw_only, sanitize("*"))
 
+        # insert a single `/, ` argument to represent shift from positional only arguments
+        # note that this must come before a single *, so it's okay that both this
+        # and block above insert into pars
+        if pos_only is not None:
+            pars.insert(pos_only + 1, sanitize("/"))
+
         return ", ".join(pars)
 
     @dispatch

quartodoc/tests/example_signature.py

@@ -6,3 +6,19 @@ def yes_annotations(
     a: int, b: int = 1, *args: list[str], c: int, d: int, **kwargs: dict[str, str]
 ):
     """A function with a signature"""
+
+
+def pos_only(x, /, a, b=2):
+    ...
+
+
+def kw_only(x, *, a, b=2):
+    ...
+
+
+def early_args(x, *args, a, b=2, **kwargs):
+    ...
+
+
+def late_args(x, a, b=2, *args, **kwargs):
+    ...

quartodoc/tests/test_renderers.py

@@ -15,7 +15,7 @@ def test_render_param_kwargs(renderer):
     f = get_object("quartodoc.tests.example_signature.no_annotations")
     res = renderer.render(f.parameters)
 
-    assert res == "a, b=1, *args, *, c, d=2, **kwargs"
+    assert res == "a, b=1, *args, c, d=2, **kwargs"
 
 
 def test_render_param_kwargs_annotated():
@@ -26,5 +26,21 @@ def test_render_param_kwargs_annotated():
 
     assert (
         res
-        == "a: int, b: int = 1, *args: list\\[str\\], *, c: int, d: int, **kwargs: dict\\[str, str\\]"
+        == "a: int, b: int = 1, *args: list\\[str\\], c: int, d: int, **kwargs: dict\\[str, str\\]"
     )
+
+
+@pytest.mark.parametrize(
+    "src, dst",
+    [
+        ("example_signature.pos_only", "x, /, a, b=2"),
+        ("example_signature.kw_only", "x, *, a, b=2"),
+        ("example_signature.early_args", "x, *args, a, b=2, **kwargs"),
+        ("example_signature.late_args", "x, a, b=2, *args, **kwargs"),
+    ],
+)
+def test_render_param_kwonly(src, dst, renderer):
+    f = get_object("quartodoc.tests", src)
+
+    res = renderer.render(f.parameters)
+    assert res == dst