Update pydoc for Python 3.13 (#12305)

Author: max-muoto

stdlib/@tests/stubtest_allowlists/py313.txt

@@ -106,11 +106,6 @@ os.path.splitroot
 # `__replace__` to be special cased in dataclasses
 pstats.FunctionProfile.__replace__
 pstats.StatsProfile.__replace__
-pydoc.pager
-pydoc.pipepager
-pydoc.plainpager
-pydoc.tempfilepager
-pydoc.ttypager
 site.gethistoryfile
 site.register_readline
 sre_compile.SRE_FLAG_TEMPLATE

stdlib/pydoc.pyi

@@ -5,7 +5,7 @@ from builtins import list as _list  # "list" conflicts with method name
 from collections.abc import Callable, Container, Mapping, MutableMapping
 from reprlib import Repr
 from types import MethodType, ModuleType, TracebackType
-from typing import IO, Any, AnyStr, Final, NoReturn, TypeVar
+from typing import IO, Any, AnyStr, Final, NoReturn, Protocol, TypeVar
 from typing_extensions import TypeGuard
 
 __all__ = ["help"]
@@ -17,6 +17,9 @@ __date__: Final[str]
 __version__: Final[str]
 __credits__: Final[str]
 
+class _Pager(Protocol):
+    def __call__(self, text: str, title: str = "") -> None: ...
+
 def pathdirs() -> list[str]: ...
 def getdoc(object: object) -> str: ...
 def splitdoc(doc: AnyStr) -> tuple[AnyStr, AnyStr]: ...
@@ -229,16 +232,36 @@ class TextDoc(Doc):
             doc: Any | None = None,
         ) -> str: ...
 
-def pager(text: str) -> None: ...
-def getpager() -> Callable[[str], None]: ...
+if sys.version_info >= (3, 13):
+    def pager(text: str, title: str = "") -> None: ...
+
+else:
+    def pager(text: str) -> None: ...
+
 def plain(text: str) -> str: ...
-def pipepager(text: str, cmd: str) -> None: ...
-def tempfilepager(text: str, cmd: str) -> None: ...
-def ttypager(text: str) -> None: ...
-def plainpager(text: str) -> None: ...
 def describe(thing: Any) -> str: ...
 def locate(path: str, forceload: bool = ...) -> object: ...
 
+if sys.version_info >= (3, 13):
+    def get_pager() -> _Pager: ...
+    def pipe_pager(text: str, cmd: str, title: str = "") -> None: ...
+    def tempfile_pager(text: str, cmd: str, title: str = "") -> None: ...
+    def tty_pager(text: str, title: str = "") -> None: ...
+    def plain_pager(text: str, title: str = "") -> None: ...
+
+    # For backwards compatibility.
+    getpager = get_pager
+    pipepager = pipe_pager
+    tempfilepager = tempfile_pager
+    ttypager = tty_pager
+    plainpager = plain_pager
+else:
+    def getpager() -> Callable[[str], None]: ...
+    def pipepager(text: str, cmd: str) -> None: ...
+    def tempfilepager(text: str, cmd: str) -> None: ...
+    def ttypager(text: str) -> None: ...
+    def plainpager(text: str) -> None: ...
+
 text: TextDoc
 html: HTMLDoc