pydoc: various improvements (#3863)

Co-authored-by: hauntsaninja <>

stdlib/2and3/pydoc.pyi

@@ -1,5 +1,5 @@
 import sys
-from typing import Any, AnyStr, Callable, Container, Dict, IO, List, Mapping, MutableMapping, NoReturn, Optional, Text, Tuple, Type, Union
+from typing import Any, AnyStr, Callable, Container, Dict, IO, List, Mapping, MutableMapping, NoReturn, Optional, Protocol, Text, Tuple, Type, Union
 from types import FunctionType, MethodType, ModuleType, TracebackType
 if sys.version_info >= (3,):
     from reprlib import Repr
@@ -41,6 +41,7 @@ def importfile(path: str) -> ModuleType: ...
 def safeimport(path: str, forceload: bool = ..., cache: MutableMapping[str, ModuleType] = ...) -> ModuleType: ...
 
 class Doc:
+    PYTHONDOCS: str
     def document(self, object: object, name: Optional[str] = ..., *args: Any) -> str: ...
     def fail(self, object: object, name: Optional[str] = ..., *args: Any) -> NoReturn: ...
     def docmodule(self, object: object, name: Optional[str] = ..., *args: Any) -> str: ...
@@ -49,7 +50,7 @@ class Doc:
     def docother(self, object: object, name: Optional[str] = ..., *args: Any) -> str: ...
     def docproperty(self, object: object, name: Optional[str] = ..., *args: Any) -> str: ...
     def docdata(self, object: object, name: Optional[str] = ..., *args: Any) -> str: ...
-    def getdocloc(self, object: object) -> Optional[str]: ...
+    def getdocloc(self, object: object, basedir: str = ...) -> Optional[str]: ...
 
 class HTMLRepr(Repr):
     maxlist: int
@@ -67,8 +68,8 @@ class HTMLRepr(Repr):
     def repr_unicode(self, x: AnyStr, level: complex) -> str: ...
 
 class HTMLDoc(Doc):
-    def repr(self, object: object) -> str: ...
-    def escape(self, test: str) -> str: ...
+    repr: Callable[[object], str]
+    escape: Callable[[str], str]
     def page(self, title: str, contents: str) -> str: ...
     def heading(self, title: str, fgcol: str, bgcol: str, extras: str = ...) -> str: ...
     def section(self, title: str, fgcol: str, bgcol: str, contents: str, width: int = ..., prelude: str = ..., marginalia: Optional[str] = ..., gap: str = ...) -> str: ...
@@ -79,7 +80,7 @@ class HTMLDoc(Doc):
     def namelink(self, name: str, *dicts: MutableMapping[str, str]) -> str: ...
     def classlink(self, object: object, modname: str) -> str: ...
     def modulelink(self, object: object) -> str: ...
-    def modpkglink(self, data: Tuple[str, str, bool, bool]) -> str: ...
+    def modpkglink(self, modpkginfo: Tuple[str, str, bool, bool]) -> str: ...
     def markup(self, text: str, escape: Optional[Callable[[str], str]] = ..., funcs: Mapping[str, str] = ..., classes: Mapping[str, str] = ..., methods: Mapping[str, str] = ...) -> str: ...
     def formattree(self, tree: List[Union[Tuple[type, Tuple[type, ...]], List[Any]]], modname: str, parent: Optional[type] = ...) -> str: ...
     def docmodule(self, object: object, name: Optional[str] = ..., mod: Optional[str] = ..., *ignored) -> str: ...
@@ -90,6 +91,7 @@ class HTMLDoc(Doc):
     def docother(self, object: object, name: Optional[str] = ..., mod: Optional[Any] = ..., *ignored) -> str: ...
     def docdata(self, object: object, name: Optional[str] = ..., mod: Optional[Any] = ..., cl: Optional[Any] = ..., *ignored) -> str: ...
     def index(self, dir: str, shadowed: Optional[MutableMapping[str, bool]] = ...) -> str: ...
+    def filelink(self, url: str, path: str) -> str: ...
 
 class TextRepr(Repr):
     maxlist: int
@@ -104,7 +106,7 @@ class TextRepr(Repr):
     def repr_instance(self, x: object, level: complex) -> str: ...
 
 class TextDoc(Doc):
-    def repr(self, object: object) -> str: ...
+    repr: Callable[[object], str]
     def bold(self, text: str) -> str: ...
     def indent(self, text: str, prefix: str = ...) -> str: ...
     def section(self, title: str, contents: str) -> str: ...
@@ -131,10 +133,12 @@ text: TextDoc
 html: HTMLDoc
 
 class _OldStyleClass: ...
+class _Writable(Protocol):
+    def write(self, __obj: str) -> Any: ...
 
 def resolve(thing: Union[str, object], forceload: bool = ...) -> Optional[Tuple[object, str]]: ...
-def render_doc(thing: Union[str, object], title: str = ..., forceload: bool = ...) -> str: ...
-def doc(thing: Union[str, object], title: str = ..., forceload: bool = ...) -> None: ...
+def render_doc(thing: Union[str, object], title: str = ..., forceload: bool = ..., renderer: Optional[Doc] = ...) -> str: ...
+def doc(thing: Union[str, object], title: str = ..., forceload: bool = ..., output: Optional[_Writable] = ...) -> None: ...
 def writedoc(thing: Union[str, object], forceload: bool = ...) -> None: ...
 def writedocs(dir: str, pkgpath: str = ..., done: Optional[Any] = ...) -> None: ...
 
@@ -174,7 +178,9 @@ class ModuleScanner:
     def run(self, callback: Callable[[Optional[str], str, str], None], key: Optional[Any] = ..., completer: Optional[Callable[[], None]] = ..., onerror: Optional[Callable[[str], None]] = ...) -> None: ...
 
 def apropos(key: str) -> None: ...
-def serve(port: int, callback: Optional[Callable[[Any], None]] = ..., completer: Optional[Callable[[], None]] = ...) -> None: ...
-def gui() -> None: ...
 def ispath(x: Any) -> bool: ...
 def cli() -> None: ...
+
+if sys.version_info < (3,):
+    def serve(port: int, callback: Optional[Callable[[Any], None]] = ..., completer: Optional[Callable[[], None]] = ...) -> None: ...
+    def gui() -> None: ...

tests/stubtest_whitelists/py3_common.txt

@@ -598,23 +598,14 @@ posix.waitid_result._make
 posix.waitid_result._replace
 pstats.Stats.__init__
 pwd.getpwnam
-pydoc.Doc.getdocloc
 pydoc.HTMLDoc.docdata
 pydoc.HTMLDoc.docproperty
 pydoc.HTMLDoc.docroutine
-pydoc.HTMLDoc.escape
-pydoc.HTMLDoc.modpkglink
-pydoc.HTMLDoc.repr
 pydoc.TextDoc.docdata
 pydoc.TextDoc.docmodule
 pydoc.TextDoc.docother
 pydoc.TextDoc.docproperty
 pydoc.TextDoc.docroutine
-pydoc.TextDoc.repr
-pydoc.doc
-pydoc.gui
-pydoc.render_doc
-pydoc.serve
 random.Random.randrange
 random.Random.triangular
 random.SystemRandom.getstate