a close reading of the pickle module (#12971)

stdlib/pickle.pyi

@@ -1,7 +1,20 @@
+from _pickle import (
+    PickleError as PickleError,
+    Pickler as Pickler,
+    PicklingError as PicklingError,
+    Unpickler as Unpickler,
+    UnpicklingError as UnpicklingError,
+    _BufferCallback,
+    _ReadableFileobj,
+    _ReducedType,
+    dump as dump,
+    dumps as dumps,
+    load as load,
+    loads as loads,
+)
 from _typeshed import ReadableBuffer, SupportsWrite
-from collections.abc import Callable, Iterable, Iterator, Mapping
-from typing import Any, ClassVar, Protocol, SupportsBytes, SupportsIndex, final
-from typing_extensions import TypeAlias
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any, ClassVar, SupportsBytes, SupportsIndex, final
 
 __all__ = [
     "PickleBuffer",
@@ -93,10 +106,6 @@ DEFAULT_PROTOCOL: int
 
 bytes_types: tuple[type[Any], ...]  # undocumented
 
-class _ReadableFileobj(Protocol):
-    def read(self, n: int, /) -> bytes: ...
-    def readline(self) -> bytes: ...
-
 @final
 class PickleBuffer:
     def __init__(self, buffer: ReadableBuffer) -> None: ...
@@ -105,84 +114,6 @@ class PickleBuffer:
     def __buffer__(self, flags: int, /) -> memoryview: ...
     def __release_buffer__(self, buffer: memoryview, /) -> None: ...
 
-_BufferCallback: TypeAlias = Callable[[PickleBuffer], Any] | None
-
-def dump(
-    obj: Any,
-    file: SupportsWrite[bytes],
-    protocol: int | None = None,
-    *,
-    fix_imports: bool = True,
-    buffer_callback: _BufferCallback = None,
-) -> None: ...
-def dumps(
-    obj: Any, protocol: int | None = None, *, fix_imports: bool = True, buffer_callback: _BufferCallback = None
-) -> bytes: ...
-def load(
-    file: _ReadableFileobj,
-    *,
-    fix_imports: bool = True,
-    encoding: str = "ASCII",
-    errors: str = "strict",
-    buffers: Iterable[Any] | None = (),
-) -> Any: ...
-def loads(
-    data: ReadableBuffer,
-    /,
-    *,
-    fix_imports: bool = True,
-    encoding: str = "ASCII",
-    errors: str = "strict",
-    buffers: Iterable[Any] | None = (),
-) -> Any: ...
-
-class PickleError(Exception): ...
-class PicklingError(PickleError): ...
-class UnpicklingError(PickleError): ...
-
-_ReducedType: TypeAlias = (
-    str
-    | tuple[Callable[..., Any], tuple[Any, ...]]
-    | tuple[Callable[..., Any], tuple[Any, ...], Any]
-    | tuple[Callable[..., Any], tuple[Any, ...], Any, Iterator[Any] | None]
-    | tuple[Callable[..., Any], tuple[Any, ...], Any, Iterator[Any] | None, Iterator[Any] | None]
-)
-
-class Pickler:
-    fast: bool
-    dispatch_table: Mapping[type, Callable[[Any], _ReducedType]]
-    bin: bool  # undocumented
-    dispatch: ClassVar[dict[type, Callable[[Unpickler, Any], None]]]  # undocumented, _Pickler only
-
-    def __init__(
-        self,
-        file: SupportsWrite[bytes],
-        protocol: int | None = None,
-        *,
-        fix_imports: bool = True,
-        buffer_callback: _BufferCallback = None,
-    ) -> None: ...
-    def reducer_override(self, obj: Any) -> Any: ...
-    def dump(self, obj: Any, /) -> None: ...
-    def clear_memo(self) -> None: ...
-    def persistent_id(self, obj: Any) -> Any: ...
-
-class Unpickler:
-    dispatch: ClassVar[dict[int, Callable[[Unpickler], None]]]  # undocumented, _Unpickler only
-
-    def __init__(
-        self,
-        file: _ReadableFileobj,
-        *,
-        fix_imports: bool = True,
-        encoding: str = "ASCII",
-        errors: str = "strict",
-        buffers: Iterable[Any] | None = (),
-    ) -> None: ...
-    def load(self) -> Any: ...
-    def find_class(self, module_name: str, global_name: str, /) -> Any: ...
-    def persistent_load(self, pid: Any) -> Any: ...
-
 MARK: bytes
 STOP: bytes
 POP: bytes
@@ -266,6 +197,36 @@ READONLY_BUFFER: bytes
 def encode_long(x: int) -> bytes: ...  # undocumented
 def decode_long(data: Iterable[SupportsIndex] | SupportsBytes | ReadableBuffer) -> int: ...  # undocumented
 
-# pure-Python implementations
-_Pickler = Pickler  # undocumented
-_Unpickler = Unpickler  # undocumented
+# undocumented pure-Python implementations
+class _Pickler:
+    fast: bool
+    dispatch_table: Mapping[type, Callable[[Any], _ReducedType]]
+    bin: bool  # undocumented
+    dispatch: ClassVar[dict[type, Callable[[Unpickler, Any], None]]]  # undocumented, _Pickler only
+    reducer_override: Callable[[Any], Any]
+    def __init__(
+        self,
+        file: SupportsWrite[bytes],
+        protocol: int | None = None,
+        *,
+        fix_imports: bool = True,
+        buffer_callback: _BufferCallback = None,
+    ) -> None: ...
+    def dump(self, obj: Any) -> None: ...
+    def clear_memo(self) -> None: ...
+    def persistent_id(self, obj: Any) -> Any: ...
+
+class _Unpickler:
+    dispatch: ClassVar[dict[int, Callable[[Unpickler], None]]]  # undocumented, _Unpickler only
+    def __init__(
+        self,
+        file: _ReadableFileobj,
+        *,
+        fix_imports: bool = True,
+        encoding: str = "ASCII",
+        errors: str = "strict",
+        buffers: Iterable[Any] | None = None,
+    ) -> None: ...
+    def load(self) -> Any: ...
+    def find_class(self, module: str, name: str) -> Any: ...
+    def persistent_load(self, pid: Any) -> Any: ...