Add _typeshed.(Opt)ExcInfo (#7645)

Author: srittau

stdlib/_typeshed/__init__.pyi

@@ -7,7 +7,8 @@ import ctypes
 import mmap
 import sys
 from os import PathLike
-from typing import AbstractSet, Any, Awaitable, Container, Generic, Iterable, Protocol, TypeVar
+from types import TracebackType
+from typing import AbstractSet, Any, Awaitable, Container, Generic, Iterable, Protocol, TypeVar, Union
 from typing_extensions import Final, Literal, TypeAlias, final
 
 _KT = TypeVar("_KT")
@@ -197,6 +198,9 @@ WriteableBuffer: TypeAlias = bytearray | memoryview | array.array[Any] | mmap.mm
 # Same as _WriteableBuffer, but also includes read-only buffer types (like bytes).
 ReadableBuffer: TypeAlias = ReadOnlyBuffer | WriteableBuffer  # stable
 
+ExcInfo: TypeAlias = tuple[type[BaseException], BaseException, TracebackType]
+OptExcInfo: TypeAlias = Union[ExcInfo, tuple[None, None, None]]
+
 # stable
 if sys.version_info >= (3, 10):
     from types import NoneType as NoneType

stdlib/_typeshed/wsgi.pyi

@@ -5,7 +5,7 @@
 # See the README.md file in this directory for more information.
 
 import sys
-from sys import _OptExcInfo
+from _typeshed import OptExcInfo
 from typing import Any, Callable, Iterable, Protocol
 from typing_extensions import TypeAlias
 
@@ -19,7 +19,7 @@ else:
     # stable
     class StartResponse(Protocol):
         def __call__(
-            self, __status: str, __headers: list[tuple[str, str]], __exc_info: _OptExcInfo | None = ...
+            self, __status: str, __headers: list[tuple[str, str]], __exc_info: OptExcInfo | None = ...
         ) -> Callable[[bytes], object]: ...
 
     WSGIEnvironment: TypeAlias = dict[str, Any]  # stable

stdlib/bdb.pyi

@@ -1,3 +1,4 @@
+from _typeshed import ExcInfo
 from types import CodeType, FrameType, TracebackType
 from typing import IO, Any, Callable, Iterable, Mapping, SupportsInt, TypeVar
 from typing_extensions import Literal, ParamSpec, TypeAlias
@@ -7,14 +8,12 @@ __all__ = ["BdbQuit", "Bdb", "Breakpoint"]
 _T = TypeVar("_T")
 _P = ParamSpec("_P")
 _TraceDispatch: TypeAlias = Callable[[FrameType, str, Any], Any]  # TODO: Recursive type
-_ExcInfo: TypeAlias = tuple[type[BaseException], BaseException, FrameType]
 
 GENERATOR_AND_COROUTINE_FLAGS: Literal[672]
 
 class BdbQuit(Exception): ...
 
 class Bdb:
-
     skip: set[str] | None
     breaks: dict[str, list[int]]
     fncache: dict[str, str]
@@ -31,7 +30,7 @@ class Bdb:
     def dispatch_line(self, frame: FrameType) -> _TraceDispatch: ...
     def dispatch_call(self, frame: FrameType, arg: None) -> _TraceDispatch: ...
     def dispatch_return(self, frame: FrameType, arg: Any) -> _TraceDispatch: ...
-    def dispatch_exception(self, frame: FrameType, arg: _ExcInfo) -> _TraceDispatch: ...
+    def dispatch_exception(self, frame: FrameType, arg: ExcInfo) -> _TraceDispatch: ...
     def is_skipped_module(self, module_name: str) -> bool: ...
     def stop_here(self, frame: FrameType) -> bool: ...
     def break_here(self, frame: FrameType) -> bool: ...
@@ -40,7 +39,7 @@ class Bdb:
     def user_call(self, frame: FrameType, argument_list: None) -> None: ...
     def user_line(self, frame: FrameType) -> None: ...
     def user_return(self, frame: FrameType, return_value: Any) -> None: ...
-    def user_exception(self, frame: FrameType, exc_info: _ExcInfo) -> None: ...
+    def user_exception(self, frame: FrameType, exc_info: ExcInfo) -> None: ...
     def set_until(self, frame: FrameType, lineno: int | None = ...) -> None: ...
     def set_step(self) -> None: ...
     def set_next(self, frame: FrameType) -> None: ...

stdlib/cgitb.pyi

@@ -1,9 +1,6 @@
-from _typeshed import StrOrBytesPath
+from _typeshed import OptExcInfo, StrOrBytesPath
 from types import FrameType, TracebackType
 from typing import IO, Any, Callable
-from typing_extensions import TypeAlias
-
-_ExcInfo: TypeAlias = tuple[type[BaseException] | None, BaseException | None, TracebackType | None]
 
 __UNDEF__: object  # undocumented sentinel
 
@@ -15,8 +12,8 @@ def lookup(name: str, frame: FrameType, locals: dict[str, Any]) -> tuple[str | N
 def scanvars(
     reader: Callable[[], bytes], frame: FrameType, locals: dict[str, Any]
 ) -> list[tuple[str, str | None, Any]]: ...  # undocumented
-def html(einfo: _ExcInfo, context: int = ...) -> str: ...
-def text(einfo: _ExcInfo, context: int = ...) -> str: ...
+def html(einfo: OptExcInfo, context: int = ...) -> str: ...
+def text(einfo: OptExcInfo, context: int = ...) -> str: ...
 
 class Hook:  # undocumented
     def __init__(
@@ -28,7 +25,7 @@ class Hook:  # undocumented
         format: str = ...,
     ) -> None: ...
     def __call__(self, etype: type[BaseException] | None, evalue: BaseException | None, etb: TracebackType | None) -> None: ...
-    def handle(self, info: _ExcInfo | None = ...) -> None: ...
+    def handle(self, info: OptExcInfo | None = ...) -> None: ...
 
-def handler(info: _ExcInfo | None = ...) -> None: ...
+def handler(info: OptExcInfo | None = ...) -> None: ...
 def enable(display: int = ..., logdir: StrOrBytesPath | None = ..., context: int = ..., format: str = ...) -> None: ...

stdlib/doctest.pyi

@@ -1,5 +1,6 @@
 import types
 import unittest
+from _typeshed import ExcInfo
 from typing import Any, Callable, NamedTuple
 from typing_extensions import TypeAlias
 
@@ -125,7 +126,6 @@ class DocTestFinder:
     ) -> list[DocTest]: ...
 
 _Out: TypeAlias = Callable[[str], Any]
-_ExcInfo: TypeAlias = tuple[type[BaseException], BaseException, types.TracebackType]
 
 class DocTestRunner:
     DIVIDER: str
@@ -138,7 +138,7 @@ class DocTestRunner:
     def report_start(self, out: _Out, test: DocTest, example: Example) -> None: ...
     def report_success(self, out: _Out, test: DocTest, example: Example, got: str) -> None: ...
     def report_failure(self, out: _Out, test: DocTest, example: Example, got: str) -> None: ...
-    def report_unexpected_exception(self, out: _Out, test: DocTest, example: Example, exc_info: _ExcInfo) -> None: ...
+    def report_unexpected_exception(self, out: _Out, test: DocTest, example: Example, exc_info: ExcInfo) -> None: ...
     def run(
         self, test: DocTest, compileflags: int | None = ..., out: _Out | None = ..., clear_globs: bool = ...
     ) -> TestResults: ...
@@ -158,8 +158,8 @@ class DocTestFailure(Exception):
 class UnexpectedException(Exception):
     test: DocTest
     example: Example
-    exc_info: _ExcInfo
-    def __init__(self, test: DocTest, example: Example, exc_info: _ExcInfo) -> None: ...
+    exc_info: ExcInfo
+    def __init__(self, test: DocTest, example: Example, exc_info: ExcInfo) -> None: ...
 
 class DebugRunner(DocTestRunner): ...
 

stdlib/sys.pyi

@@ -1,18 +1,16 @@
 import sys
-from _typeshed import structseq
+from _typeshed import OptExcInfo, structseq
 from builtins import object as _object
 from importlib.abc import PathEntryFinder
 from importlib.machinery import ModuleSpec
 from io import TextIOWrapper
 from types import FrameType, ModuleType, TracebackType
-from typing import Any, AsyncGenerator, Callable, Coroutine, NoReturn, Protocol, Sequence, TextIO, TypeVar, Union, overload
+from typing import Any, AsyncGenerator, Callable, Coroutine, NoReturn, Protocol, Sequence, TextIO, TypeVar, overload
 from typing_extensions import Literal, TypeAlias, final
 
 _T = TypeVar("_T")
 
-# The following type alias are stub-only and do not exist during runtime
-_ExcInfo: TypeAlias = tuple[type[BaseException], BaseException, TracebackType]
-_OptExcInfo: TypeAlias = Union[_ExcInfo, tuple[None, None, None]]
+_OptExcInfo: TypeAlias = OptExcInfo  # TODO: obsolete, remove fall 2022 or later
 
 # Intentionally omits one deprecated and one optional method of `importlib.abc.MetaPathFinder`
 class _MetaPathFinder(Protocol):
@@ -217,7 +215,7 @@ def _getframe(__depth: int = ...) -> FrameType: ...
 def _debugmallocstats() -> None: ...
 def __displayhook__(__value: object) -> None: ...
 def __excepthook__(__exctype: type[BaseException], __value: BaseException, __traceback: TracebackType | None) -> None: ...
-def exc_info() -> _OptExcInfo: ...
+def exc_info() -> OptExcInfo: ...
 
 # sys.exit() accepts an optional argument of anything printable
 def exit(__status: object = ...) -> NoReturn: ...

stdlib/wsgiref/handlers.pyi

@@ -1,16 +1,13 @@
+from _typeshed import OptExcInfo
 from _typeshed.wsgi import ErrorStream, InputStream, StartResponse, WSGIApplication, WSGIEnvironment
 from abc import abstractmethod
-from types import TracebackType
 from typing import IO, Callable, MutableMapping
-from typing_extensions import TypeAlias
 
 from .headers import Headers
 from .util import FileWrapper
 
 __all__ = ["BaseHandler", "SimpleHandler", "BaseCGIHandler", "CGIHandler", "IISCGIHandler", "read_environ"]
 
-_exc_info: TypeAlias = tuple[type[BaseException] | None, BaseException | None, TracebackType | None]
-
 def format_date_time(timestamp: float | None) -> str: ...  # undocumented
 def read_environ() -> dict[str, str]: ...
 
@@ -40,7 +37,7 @@ class BaseHandler:
     def set_content_length(self) -> None: ...
     def cleanup_headers(self) -> None: ...
     def start_response(
-        self, status: str, headers: list[tuple[str, str]], exc_info: _exc_info | None = ...
+        self, status: str, headers: list[tuple[str, str]], exc_info: OptExcInfo | None = ...
     ) -> Callable[[bytes], None]: ...
     def send_preamble(self) -> None: ...
     def write(self, data: bytes) -> None: ...
@@ -50,7 +47,7 @@ class BaseHandler:
     def send_headers(self) -> None: ...
     def result_is_file(self) -> bool: ...
     def client_is_modern(self) -> bool: ...
-    def log_exception(self, exc_info: _exc_info) -> None: ...
+    def log_exception(self, exc_info: OptExcInfo) -> None: ...
     def handle_error(self) -> None: ...
     def error_output(self, environ: WSGIEnvironment, start_response: StartResponse) -> list[bytes]: ...
     @abstractmethod