Merge pull request sphinx-doc#7012 from tk0miya/support_pep570

autodoc: Support Positional-Only Argument separator (PEP-570 compliant)
tk0miya · Jan 11, 2020 · b6b2ebd · b6b2ebd
2 parents d82edef + 9ed1629
commit b6b2ebd
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 5 deletions.
diff --git a/CHANGES b/CHANGES
@@ -34,6 +34,7 @@ Features added
 * #6696: html: ``:scale:`` option of image/figure directive not working for SVG
   images (imagesize-1.2.0 or above is required)
 * #6994: imgconverter: Support illustrator file (.ai) to .png conversion
+* autodoc: Support Positional-Only Argument separator (PEP-570 compliant)
 
 Bugs fixed
 ----------

diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py
@@ -374,11 +374,13 @@ def stringify_signature(sig: inspect.Signature, show_annotation: bool = True,
     args = []
     last_kind = None
     for param in sig.parameters.values():
-        # insert '*' between POSITIONAL args and KEYWORD_ONLY args::
-        #     func(a, b, *, c, d):
-        if param.kind == param.KEYWORD_ONLY and last_kind in (param.POSITIONAL_OR_KEYWORD,
-                                                              param.POSITIONAL_ONLY,
-                                                              None):
+        if param.kind != param.POSITIONAL_ONLY and last_kind == param.POSITIONAL_ONLY:
+            # PEP-570: Separator for Positional Only Parameter: /
+            args.append('/')
+        elif param.kind == param.KEYWORD_ONLY and last_kind in (param.POSITIONAL_OR_KEYWORD,
+                                                                param.POSITIONAL_ONLY,
+                                                                None):
+            # PEP-3102: Separator for Keyword Only Parameter: *
             args.append('*')
 
         arg = StringIO()
@@ -402,6 +404,10 @@ def stringify_signature(sig: inspect.Signature, show_annotation: bool = True,
         args.append(arg.getvalue())
         last_kind = param.kind
 
+    if last_kind == inspect.Parameter.POSITIONAL_ONLY:
+        # PEP-570: Separator for Positional Only Parameter: /
+        args.append('/')
+
     if (sig.return_annotation is inspect.Parameter.empty or
             show_annotation is False or
             show_return_annotation is False):

diff --git a/tests/roots/test-ext-autodoc/target/pep570.py b/tests/roots/test-ext-autodoc/target/pep570.py
@@ -0,0 +1,5 @@
+def foo(a, b, /, c, d):
+    pass
+
+def bar(a, b, /):
+    pass
diff --git a/tests/test_util_inspect.py b/tests/test_util_inspect.py
@@ -294,6 +294,21 @@ def test_signature_annotations():
     sig = inspect.signature(f7)
     assert stringify_signature(sig, show_return_annotation=False) == '(x: int = None, y: dict = {})'
 
+
+@pytest.mark.skipif(sys.version_info < (3, 8), reason='python 3.8+ is required.')
+@pytest.mark.sphinx(testroot='ext-autodoc')
+def test_signature_annotations_py38(app):
+    from target.pep570 import foo, bar
+
+    # case: separator in the middle
+    sig = inspect.signature(foo)
+    assert stringify_signature(sig) == '(a, b, /, c, d)'
+
+    # case: separator at tail
+    sig = inspect.signature(bar)
+    assert stringify_signature(sig) == '(a, b, /)'
+
+
 def test_safe_getattr_with_default():
     class Foo:
         def __getattr__(self, item):