Support positional and keyword-only arguments

Currently the signature parsing logic fails when confronted with a `/`
or a `*`, rather than recognizing them as demarcating positional-only
and keyword-only arguments.

This patch supports parsing signatures with these features, but doesn't
pass this information along to the `ArgSig` or `FunctionSig` classes,
since the information would not be used anyway.

Author: pganssle-google

mypy/stubdoc.py

@@ -175,6 +175,8 @@ def __init__(self, function_name: str) -> None:
         self.ret_type = "Any"
         self.found = False
         self.args: list[ArgSig] = []
+        self.pos_only: int | None = None
+        self.keyword_only: int | None = None
         # Valid signatures found so far.
         self.signatures: list[FunctionSig] = []
 
@@ -261,6 +263,15 @@ def add_token(self, token: tokenize.TokenInfo) -> None:
                     return
 
             if token.string == ")":
+                if (
+                    self.state[-1] == STATE_ARGUMENT_LIST
+                    and self.keyword_only is not None
+                    and self.keyword_only == len(self.args)
+                    and not self.arg_name
+                ):
+                    # Error condition: * must be followed by arguments
+                    self.reset()
+                    return
                 self.state.pop()
 
             # arg_name is empty when there are no args. e.g. func()
@@ -280,6 +291,27 @@ def add_token(self, token: tokenize.TokenInfo) -> None:
             self.arg_type = None
             self.arg_default = None
             self.accumulator = ""
+        elif (
+            token.type == tokenize.OP
+            and (token.string in {"*", "/"})
+            and self.state[-1] == STATE_ARGUMENT_LIST
+        ):
+            if token.string == "/":
+                if self.pos_only is not None or self.keyword_only is not None or not self.args:
+                    # Error cases:
+                    # - / shows up more than once
+                    # - / shows up after *
+                    # - / shows up before any arguments
+                    self.reset()
+                    return
+                self.pos_only = len(self.args)
+            else:
+                if self.keyword_only is not None:
+                    # * is not allowed after *
+                    self.reset()
+                    return
+                self.keyword_only = len(self.args)
+            self.state.append(STATE_ARGUMENT_TYPE)
 
         elif token.type == tokenize.OP and token.string == "->" and self.state[-1] == STATE_INIT:
             self.accumulator = ""

mypy/test/teststubgen.py

@@ -399,6 +399,79 @@ def test_infer_sig_from_docstring_bad_indentation(self) -> None:
             None,
         )
 
+    def test_infer_sig_from_docstring_positional_only_arguments(self) -> None:
+        assert_equal(
+            infer_sig_from_docstring("func(self, /) -> str", "func"),
+            [FunctionSig(name="func", args=[ArgSig(name="self")], ret_type="str")],
+        )
+
+        assert_equal(
+            infer_sig_from_docstring("func(self, x, /) -> str", "func"),
+            [
+                FunctionSig(
+                    name="func", args=[ArgSig(name="self"), ArgSig(name="x")], ret_type="str"
+                )
+            ],
+        )
+
+        assert_equal(
+            infer_sig_from_docstring("func(x, /, y) -> int", "func"),
+            [FunctionSig(name="func", args=[ArgSig(name="x"), ArgSig(name="y")], ret_type="int")],
+        )
+
+    def test_infer_sig_from_docstring_keyword_only_arguments(self) -> None:
+        assert_equal(
+            infer_sig_from_docstring("func(*, x) -> str", "func"),
+            [FunctionSig(name="func", args=[ArgSig(name="x")], ret_type="str")],
+        )
+
+        assert_equal(
+            infer_sig_from_docstring("func(x, *, y) -> str", "func"),
+            [FunctionSig(name="func", args=[ArgSig(name="x"), ArgSig(name="y")], ret_type="str")],
+        )
+
+        assert_equal(
+            infer_sig_from_docstring("func(*, x, y) -> str", "func"),
+            [FunctionSig(name="func", args=[ArgSig(name="x"), ArgSig(name="y")], ret_type="str")],
+        )
+
+    def test_infer_sig_from_docstring_pos_only_and_keyword_only_arguments(self) -> None:
+        assert_equal(
+            infer_sig_from_docstring("func(x, /, *, y) -> str", "func"),
+            [FunctionSig(name="func", args=[ArgSig(name="x"), ArgSig(name="y")], ret_type="str")],
+        )
+
+        assert_equal(
+            infer_sig_from_docstring("func(x,  /, y,  *, z) -> str", "func"),
+            [
+                FunctionSig(
+                    name="func",
+                    args=[ArgSig(name="x"), ArgSig(name="y"), ArgSig(name="z")],
+                    ret_type="str",
+                )
+            ],
+        )
+
+    def test_infer_sig_from_docstring_pos_only_and_keyword_only_arguments_errors(self) -> None:
+        # / as first argument
+        assert_equal(infer_sig_from_docstring("func(/, x) -> str", "func"), [])
+
+        # * as last argument
+        assert_equal(infer_sig_from_docstring("func(x, *) -> str", "func"), [])
+
+        # / after *
+        assert_equal(infer_sig_from_docstring("func(x, *, /,  y) -> str", "func"), [])
+
+        # Two /
+        assert_equal(infer_sig_from_docstring("func(x, /, /, *,  y) -> str", "func"), [])
+
+        assert_equal(infer_sig_from_docstring("func(x, /, y,  /, *,  z) -> str", "func"), [])
+
+        # Two *
+        assert_equal(infer_sig_from_docstring("func(x, /, *, *,  y) -> str", "func"), [])
+
+        assert_equal(infer_sig_from_docstring("func(x, /, *, y, *,  z) -> str", "func"), [])
+
     def test_infer_arg_sig_from_anon_docstring(self) -> None:
         assert_equal(
             infer_arg_sig_from_anon_docstring("(*args, **kwargs)"),