Rework Match.group handling

stdlib/typing.pyi

@@ -2,6 +2,7 @@ import collections  # Needed by aliases like DefaultDict, see mypy issue 2986
 import sys
 from abc import ABCMeta, abstractmethod
 from types import BuiltinFunctionType, CodeType, FrameType, FunctionType, MethodType, ModuleType, TracebackType
+from typing_extensions import Literal as _Literal
 
 if sys.version_info >= (3, 7):
     from types import MethodDescriptorType, MethodWrapperType, WrapperDescriptorType
@@ -563,19 +564,35 @@ class Match(Generic[AnyStr]):
     # this match instance.
     re: Pattern[AnyStr]
     def expand(self, template: AnyStr) -> AnyStr: ...
-    # TODO: The return for a group may be None, except if __group is 0 or not given.
+    # group() returns "AnyStr" or "AnyStr | None", depending on the pattern.
     @overload
-    def group(self, __group: Union[str, int] = ...) -> AnyStr: ...
+    def group(self, __group: _Literal[0] = ...) -> AnyStr: ...
     @overload
-    def group(self, __group1: Union[str, int], __group2: Union[str, int], *groups: Union[str, int]) -> Tuple[AnyStr, ...]: ...
-    def groups(self, default: AnyStr = ...) -> Sequence[AnyStr]: ...
-    def groupdict(self, default: AnyStr = ...) -> dict[str, AnyStr]: ...
+    def group(self, __group: str | int) -> AnyStr | Any: ...
+    @overload
+    def group(self, __group1: str | int, __group2: str | int, *groups: str | int) -> Tuple[AnyStr | Any, ...]: ...
+    # Each item of groups()'s return tuple is either "AnyStr" or
+    # "AnyStr | None", depending on the pattern.
+    @overload
+    def groups(self) -> Tuple[AnyStr | Any, ...]: ...
+    @overload
+    def groups(self, default: _T) -> Tuple[AnyStr | _T, ...]: ...
+    # Each value in groupdict()'s return dict is either "AnyStr" or
+    # "AnyStr | None", depending on the pattern.
+    @overload
+    def groupdict(self) -> dict[str, AnyStr | Any]: ...
+    @overload
+    def groupdict(self, default: _T) -> dict[str, AnyStr | _T]: ...
     def start(self, __group: Union[int, str] = ...) -> int: ...
     def end(self, __group: Union[int, str] = ...) -> int: ...
     def span(self, __group: Union[int, str] = ...) -> Tuple[int, int]: ...
     @property
     def regs(self) -> Tuple[Tuple[int, int], ...]: ...  # undocumented
-    def __getitem__(self, g: Union[int, str]) -> AnyStr: ...
+    # __getitem__() returns "AnyStr" or "AnyStr | None", depending on the pattern.
+    @overload
+    def __getitem__(self, __key: _Literal[0]) -> AnyStr: ...
+    @overload
+    def __getitem__(self, __key: int | str) -> AnyStr | Any: ...
     if sys.version_info >= (3, 9):
         def __class_getitem__(cls, item: Any) -> GenericAlias: ...
 
@@ -586,7 +603,6 @@ class Pattern(Generic[AnyStr]):
     pattern: AnyStr
     def search(self, string: AnyStr, pos: int = ..., endpos: int = ...) -> Optional[Match[AnyStr]]: ...
     def match(self, string: AnyStr, pos: int = ..., endpos: int = ...) -> Optional[Match[AnyStr]]: ...
-    # New in Python 3.4
     def fullmatch(self, string: AnyStr, pos: int = ..., endpos: int = ...) -> Optional[Match[AnyStr]]: ...
     def split(self, string: AnyStr, maxsplit: int = ...) -> list[AnyStr]: ...
     def findall(self, string: AnyStr, pos: int = ..., endpos: int = ...) -> list[Any]: ...