Add IO protocols to _typeshed (#4230)

stdlib/2and3/_typeshed/__init__.pyi

@@ -13,9 +13,12 @@
 # is not used, types from this module must be quoted.
 
 import sys
-from typing import Protocol, Text, Union, type_check_only
+from typing import Protocol, Text, TypeVar, Union
 from typing_extensions import Literal
 
+_T_co = TypeVar("_T_co", covariant=True)
+_T_contra = TypeVar("_T_contra", contravariant=True)
+
 # StrPath and AnyPath can be used in places where a
 # path can be used instead of a string, starting with Python 3.6.
 if sys.version_info >= (3, 6):
@@ -52,9 +55,15 @@ OpenBinaryModeReading = Literal[
 ]
 OpenBinaryMode = Union[OpenBinaryModeUpdating, OpenBinaryModeReading, OpenBinaryModeWriting]
 
-@type_check_only
 class HasFileno(Protocol):
     def fileno(self) -> int: ...
 
 FileDescriptor = int
 FileDescriptorLike = Union[int, HasFileno]
+
+class SupportsRead(Protocol[_T_co]):
+    def read(self, __length: int = ...) -> _T_co: ...
+class SupportsReadline(Protocol[_T_co]):
+    def readline(self, __length: int = ...) -> _T_co: ...
+class SupportsWrite(Protocol[_T_contra]):
+    def write(self, __s: _T_contra) -> int: ...

stdlib/2and3/builtins.pyi

@@ -15,7 +15,7 @@ from io import (
     TextIOWrapper, FileIO, BufferedRandom, BufferedReader, BufferedWriter
 )
 from types import TracebackType, CodeType
-from _typeshed import AnyPath, OpenBinaryMode, OpenTextMode, OpenBinaryModeUpdating, OpenBinaryModeWriting, OpenBinaryModeReading
+from _typeshed import AnyPath, OpenBinaryMode, OpenTextMode, OpenBinaryModeUpdating, OpenBinaryModeWriting, OpenBinaryModeReading, SupportsWrite
 from typing_extensions import Literal
 import sys
 
@@ -1480,17 +1480,13 @@ else:
 
 def ord(__c: Union[Text, bytes]) -> int: ...
 if sys.version_info >= (3,):
-    class _Writer(Protocol):
-        def write(self, __s: str) -> Any: ...
     def print(
-        *values: object, sep: Optional[Text] = ..., end: Optional[Text] = ..., file: Optional[_Writer] = ..., flush: bool = ...
+        *values: object, sep: Optional[Text] = ..., end: Optional[Text] = ..., file: Optional[SupportsWrite[str]] = ..., flush: bool = ...
     ) -> None: ...
 
 else:
-    class _Writer(Protocol):
-        def write(self, __s: Any) -> Any: ...
     # This is only available after from __future__ import print_function.
-    def print(*values: object, sep: Optional[Text] = ..., end: Optional[Text] = ..., file: Optional[_Writer] = ...) -> None: ...
+    def print(*values: object, sep: Optional[Text] = ..., end: Optional[Text] = ..., file: Optional[SupportsWrite[Any]] = ...) -> None: ...
 
 _E = TypeVar("_E", contravariant=True)
 _M = TypeVar("_M", contravariant=True)

stdlib/2and3/ftplib.pyi

@@ -9,7 +9,6 @@ from typing import (
     Iterator,
     List,
     Optional,
-    Protocol,
     Text,
     TextIO,
     Tuple,
@@ -20,6 +19,7 @@ from typing import (
 from types import TracebackType
 from socket import socket
 from ssl import SSLContext
+from _typeshed import SupportsRead, SupportsReadline
 
 _T = TypeVar("_T")
 _IntOrStr = Union[int, Text]
@@ -39,12 +39,6 @@ class error_proto(Error): ...
 
 all_errors = Tuple[Type[Exception], ...]
 
-class _Readable(Protocol):
-    def read(self, __length: int) -> bytes: ...
-
-class _ReadLineable(Protocol):
-    def readline(self, _length: int) -> bytes: ...
-
 class FTP:
     debugging: int
 
@@ -118,13 +112,13 @@ class FTP:
     def storbinary(
         self,
         cmd: Text,
-        fp: _Readable,
+        fp: SupportsRead[bytes],
         blocksize: int = ...,
         callback: Optional[Callable[[bytes], Any]] = ...,
         rest: Optional[_IntOrStr] = ...,
     ) -> str: ...
     def retrlines(self, cmd: Text, callback: Optional[Callable[[str], Any]] = ...) -> str: ...
-    def storlines(self, cmd: Text, fp: _ReadLineable, callback: Optional[Callable[[bytes], Any]] = ...) -> str: ...
+    def storlines(self, cmd: Text, fp: SupportsReadline[bytes], callback: Optional[Callable[[bytes], Any]] = ...) -> str: ...
     def acct(self, password: Text) -> str: ...
     def nlst(self, *args: Text) -> List[str]: ...
     # Technically only the last arg can be a Callable but ...

stdlib/2and3/pydoc.pyi

@@ -1,6 +1,7 @@
 import sys
-from typing import Any, AnyStr, Callable, Container, Dict, IO, List, Mapping, MutableMapping, NoReturn, Optional, Protocol, Text, Tuple, Type, Union
+from typing import Any, AnyStr, Callable, Container, Dict, IO, List, Mapping, MutableMapping, NoReturn, Optional, Text, Tuple, Type, Union
 from types import FunctionType, MethodType, ModuleType, TracebackType
+from _typeshed import SupportsWrite
 if sys.version_info >= (3,):
     from reprlib import Repr
 else:
@@ -133,12 +134,10 @@ 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 = ..., renderer: Optional[Doc] = ...) -> str: ...
-def doc(thing: Union[str, object], title: str = ..., forceload: bool = ..., output: Optional[_Writable] = ...) -> None: ...
+def doc(thing: Union[str, object], title: str = ..., forceload: bool = ..., output: Optional[SupportsWrite[str]] = ...) -> None: ...
 def writedoc(thing: Union[str, object], forceload: bool = ...) -> None: ...
 def writedocs(dir: str, pkgpath: str = ..., done: Optional[Any] = ...) -> None: ...
 

stdlib/2and3/pyexpat/__init__.pyi

@@ -1,4 +1,5 @@
-from typing import List, Tuple, Optional, Callable, Any, Protocol, Union, Dict, Text
+from typing import List, Tuple, Optional, Callable, Any, Union, Dict, Text
+from _typeshed import SupportsRead
 
 import pyexpat.errors as errors
 import pyexpat.model as model
@@ -15,9 +16,6 @@ class ExpatError(Exception):
 
 error = ExpatError
 
-class _Reader(Protocol):
-    def read(self, length: int) -> bytes: ...
-
 XML_PARAM_ENTITY_PARSING_NEVER: int
 XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE: int
 XML_PARAM_ENTITY_PARSING_ALWAYS: int
@@ -26,7 +24,7 @@ _Model = Tuple[int, int, Optional[str], tuple]
 
 class XMLParserType(object):
     def Parse(self, __data: Union[Text, bytes], __isfinal: bool = ...) -> int: ...
-    def ParseFile(self, __file: _Reader) -> int: ...
+    def ParseFile(self, __file: SupportsRead[bytes]) -> int: ...
     def SetBase(self, __base: Text) -> None: ...
     def GetBase(self) -> Optional[str]: ...
     def GetInputContext(self) -> Optional[bytes]: ...

stdlib/2and3/shutil.pyi

@@ -3,9 +3,9 @@ import sys
 
 from typing import (
     List, Iterable, Callable, Any, Tuple, Sequence, NamedTuple,
-    AnyStr, Optional, Union, Set, TypeVar, overload, Type, Protocol, Text
+    AnyStr, Optional, Union, Set, TypeVar, overload, Type, Text
 )
-from _typeshed import StrPath
+from _typeshed import StrPath, SupportsRead, SupportsWrite
 
 if sys.version_info >= (3, 6):
     _AnyStr = str
@@ -34,16 +34,7 @@ else:
     class SpecialFileError(EnvironmentError): ...
     class ExecError(EnvironmentError): ...
 
-_S_co = TypeVar("_S_co", covariant=True)
-_S_contra = TypeVar("_S_contra", contravariant=True)
-
-class _Reader(Protocol[_S_co]):
-    def read(self, length: int) -> _S_co: ...
-
-class _Writer(Protocol[_S_contra]):
-    def write(self, data: _S_contra) -> Any: ...
-
-def copyfileobj(fsrc: _Reader[AnyStr], fdst: _Writer[AnyStr],
+def copyfileobj(fsrc: SupportsRead[AnyStr], fdst: SupportsWrite[AnyStr],
                 length: int = ...) -> None: ...
 
 if sys.version_info >= (3,):

stdlib/2and3/traceback.pyi

@@ -1,8 +1,7 @@
-# Stubs for traceback
-
-from typing import Any, Dict, Generator, IO, Iterator, List, Mapping, Optional, Protocol, Tuple, Type, Iterable
+from typing import Any, Dict, Generator, IO, Iterator, List, Mapping, Optional, Tuple, Type, Iterable
 from types import FrameType, TracebackType
 import sys
+from _typeshed import SupportsWrite
 
 _PT = Tuple[str, int, str, Optional[str]]
 
@@ -36,10 +35,8 @@ if sys.version_info >= (3, 5):
     def extract_stack(f: Optional[FrameType] = ...,
                       limit: Optional[int] = ...) -> StackSummary: ...
     def format_list(extracted_list: List[FrameSummary]) -> List[str]: ...
-    class _Writer(Protocol):
-        def write(self, s: str) -> Any: ...
     # undocumented
-    def print_list(extracted_list: List[FrameSummary], file: Optional[_Writer] = ...) -> None: ...
+    def print_list(extracted_list: List[FrameSummary], file: Optional[SupportsWrite[str]] = ...) -> None: ...
 else:
     def extract_tb(tb: Optional[TracebackType], limit: Optional[int] = ...) -> List[_PT]: ...
     def extract_stack(f: Optional[FrameType] = ...,

stdlib/2and3/xml/etree/ElementTree.pyi

@@ -11,7 +11,6 @@ from typing import (
     List,
     MutableSequence,
     Optional,
-    Protocol,
     Sequence,
     Text,
     Tuple,
@@ -19,7 +18,7 @@ from typing import (
     Union,
     overload,
 )
-from _typeshed import AnyPath, FileDescriptor
+from _typeshed import AnyPath, FileDescriptor, SupportsWrite
 import sys
 from typing_extensions import Literal
 
@@ -60,9 +59,6 @@ else:
 _file_or_filename = Union[AnyPath, FileDescriptor, IO[Any]]
 
 if sys.version_info >= (3, 8):
-    class _Writeable(Protocol):
-        def write(self, __s: str) -> Any: ...
-
     @overload
     def canonicalize(
         xml_data: Optional[_parser_input_type] = ...,
@@ -81,7 +77,7 @@ if sys.version_info >= (3, 8):
     def canonicalize(
         xml_data: Optional[_parser_input_type] = ...,
         *,
-        out: _Writeable,
+        out: SupportsWrite[str],
         from_file: Optional[_file_or_filename] = ...,
         with_comments: bool = ...,
         strip_text: bool = ...,

stdlib/2and3/xml/sax/saxutils.pyi

@@ -1,23 +1,21 @@
 import sys
-from typing import Mapping, Text, Optional, Protocol, Union, TextIO
+from typing import Mapping, Text, Optional, Union, TextIO
 from io import TextIOBase, RawIOBase
 from codecs import StreamWriter, StreamReaderWriter
+from _typeshed import SupportsWrite
 
 from xml.sax import handler
 from xml.sax import xmlreader
 
-class _Writable(Protocol):
-    def write(self, data: str) -> None: ...
-
 def escape(data: Text, entities: Mapping[Text, Text] = ...) -> Text: ...
 def unescape(data: Text, entities: Mapping[Text, Text] = ...) -> Text: ...
 def quoteattr(data: Text, entities: Mapping[Text, Text] = ...) -> Text: ...
 
 class XMLGenerator(handler.ContentHandler):
     if sys.version_info >= (3, 0):
-        def __init__(self, out: Optional[Union[TextIOBase, RawIOBase, StreamWriter, StreamReaderWriter, _Writable]] = ..., encoding: str = ..., short_empty_elements: bool = ...) -> None: ...
+        def __init__(self, out: Optional[Union[TextIOBase, RawIOBase, StreamWriter, StreamReaderWriter, SupportsWrite[str]]] = ..., encoding: str = ..., short_empty_elements: bool = ...) -> None: ...
     else:
-        def __init__(self, out: Optional[Union[TextIOBase, RawIOBase, StreamWriter, StreamReaderWriter, _Writable]] = ..., encoding: Text = ...) -> None: ...
+        def __init__(self, out: Optional[Union[TextIOBase, RawIOBase, StreamWriter, StreamReaderWriter, SupportsWrite[str]]] = ..., encoding: Text = ...) -> None: ...
     def startDocument(self): ...
     def endDocument(self): ...
     def startPrefixMapping(self, prefix, uri): ...