argparse: Add overloads for arg parser methods (#10307)

Author: qthequartermasterman

stdlib/argparse.pyi

@@ -169,9 +169,9 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer):
             add_help: bool = True,
             allow_abbrev: bool = True,
         ) -> None: ...
-    # Ignore errors about overlapping overloads
+
     @overload
-    def parse_args(self, args: Sequence[str] | None = None, namespace: None = None) -> Namespace: ...  # type: ignore[misc]
+    def parse_args(self, args: Sequence[str] | None = None, namespace: Namespace | None = None) -> Namespace: ...  # type: ignore[misc]
     @overload
     def parse_args(self, args: Sequence[str] | None, namespace: _N) -> _N: ...
     @overload
@@ -209,16 +209,27 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer):
     def print_help(self, file: IO[str] | None = None) -> None: ...
     def format_usage(self) -> str: ...
     def format_help(self) -> str: ...
-    def parse_known_args(
-        self, args: Sequence[str] | None = None, namespace: Namespace | None = None
-    ) -> tuple[Namespace, list[str]]: ...
+    @overload
+    def parse_known_args(self, args: Sequence[str] | None = None, namespace: Namespace | None = None) -> tuple[Namespace, list[str]]: ...  # type: ignore[misc]
+    @overload
+    def parse_known_args(self, args: Sequence[str] | None, namespace: _N) -> tuple[_N, list[str]]: ...
+    @overload
+    def parse_known_args(self, *, namespace: _N) -> tuple[_N, list[str]]: ...
     def convert_arg_line_to_args(self, arg_line: str) -> list[str]: ...
     def exit(self, status: int = 0, message: str | None = None) -> NoReturn: ...
     def error(self, message: str) -> NoReturn: ...
-    def parse_intermixed_args(self, args: Sequence[str] | None = None, namespace: Namespace | None = None) -> Namespace: ...
-    def parse_known_intermixed_args(
-        self, args: Sequence[str] | None = None, namespace: Namespace | None = None
-    ) -> tuple[Namespace, list[str]]: ...
+    @overload
+    def parse_intermixed_args(self, args: Sequence[str] | None = None, namespace: Namespace | None = None) -> Namespace: ...  # type: ignore[misc]
+    @overload
+    def parse_intermixed_args(self, args: Sequence[str] | None, namespace: _N) -> _N: ...
+    @overload
+    def parse_intermixed_args(self, *, namespace: _N) -> _N: ...
+    @overload
+    def parse_known_intermixed_args(self, args: Sequence[str] | None = None, namespace: Namespace | None = None) -> tuple[Namespace, list[str]]: ...  # type: ignore[misc]
+    @overload
+    def parse_known_intermixed_args(self, args: Sequence[str] | None, namespace: _N) -> tuple[_N, list[str]]: ...
+    @overload
+    def parse_known_intermixed_args(self, *, namespace: _N) -> tuple[_N, list[str]]: ...
     # undocumented
     def _get_optional_actions(self) -> list[Action]: ...
     def _get_positional_actions(self) -> list[Action]: ...