Move protocols to io

Author: srittau

Doc/library/io.rst

@@ -1147,6 +1147,49 @@ Text I/O
    It inherits from :class:`codecs.IncrementalDecoder`.
 
 
+Static Typing
+-------------
+
+The following protocols can be used for annotating function and method
+arguments for simple stream reading or writing operations. They are decorated
+with :func:`@runtime_checkable <runtime_checkable>`.
+
+.. class:: Reader[T]
+
+   Protocol for reading from a file or other input stream.
+
+   .. versionadded:: next
+
+   .. method:: read(size=..., /)
+
+      Read data from the input stream and return it. If ``size`` is
+      specified, at most ``size`` items (bytes/characters) will be read.
+
+   For example::
+
+     def read_it(reader: Reader[str]):
+         data = reader.read(11)
+         assert isinstance(data, str)
+
+.. class:: Writer[T]
+
+   Protocol for writing to a file or other output stream.
+
+   .. versionadded:: next
+
+   .. method:: write(data, /)
+
+      Write data to the output stream and return number of items
+      (bytes/characters) written.
+
+   For example::
+
+     def write_binary(writer: Writer[bytes]):
+         writer.write(b"Hello world!\n")
+
+See :ref:`typing-io` for other I/O related protocols and classes used for
+static type checking.
+
 Performance
 -----------
 

Doc/library/typing.rst

@@ -2803,54 +2803,28 @@ with :func:`@runtime_checkable <runtime_checkable>`.
     An ABC with one abstract method ``__round__``
     that is covariant in its return type.
 
+.. _typing-io:
+
 ABCs and Protocols for working with I/O
 ---------------------------------------
 
-.. class:: IO
-           TextIO
-           BinaryIO
+.. class:: IO[AnyStr]
+           TextIO[AnyStr]
+           BinaryIO[AnyStr]
 
-   Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
+   Generic class ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])``
    and ``BinaryIO(IO[bytes])``
    represent the types of I/O streams such as returned by
-   :func:`open`.
-
-The following protocols offer a simpler alternative for common use cases. They
-are especially useful for annotating function and method arguments and are
-decorated with :func:`@runtime_checkable <runtime_checkable>`.
-
-.. class:: Reader[T]
-
-   Protocol for reading from a file or other input stream.
-
-   .. versionadded:: next
-
-   .. method:: read(size=..., /)
-
-      Read data from the input stream and return it. If ``size`` is
-      specified, at most ``size`` items (bytes/characters) will be read.
-
-   For example::
-
-     def read_it(reader: Reader[str]):
-         data = reader.read(11)
-         assert isinstance(data, str)
-
-.. class:: Writer[T]
-
-   Protocol for writing to a file or other output stream.
+   :func:`open`. Please note that these classes are not protocols, and
+   their interface is fairly broad.
 
-   .. versionadded:: next
-
-   .. method:: write(data, /)
-
-      Write data to the output stream and return number of items
-      (bytes/characters) written.
-
-   For example::
+The protocols :class:`.io.Reader` and :class:`.io.Writer` offer a simpler
+alternative for argument types, when only the ``read()`` or ``write()``
+methods are accessed, respectively::
 
-     def write_binary(writer: Writer[bytes]):
-         writer.write(b"Hello world!\n")
+  def read_and_write(reader: Reader[str], writer: Writer[bytes]):
+      data = reader.read()
+      writer.write(data.encode())
 
 Also consider using :class:`collections.abc.Iterable` for iterating over
 the lines of an input stream::

Lib/io.py

@@ -46,12 +46,14 @@
            "BufferedReader", "BufferedWriter", "BufferedRWPair",
            "BufferedRandom", "TextIOBase", "TextIOWrapper",
            "UnsupportedOperation", "SEEK_SET", "SEEK_CUR", "SEEK_END",
-           "DEFAULT_BUFFER_SIZE", "text_encoding", "IncrementalNewlineDecoder"]
+           "DEFAULT_BUFFER_SIZE", "text_encoding", "IncrementalNewlineDecoder",
+           "Reader", "Writer"]
 
 
 import _io
 import abc
 
+from _collections_abc import _check_methods
 from _io import (DEFAULT_BUFFER_SIZE, BlockingIOError, UnsupportedOperation,
                  open, open_code, FileIO, BytesIO, StringIO, BufferedReader,
                  BufferedWriter, BufferedRWPair, BufferedRandom,
@@ -97,3 +99,49 @@ class TextIOBase(_io._TextIOBase, IOBase):
     pass
 else:
     RawIOBase.register(_WindowsConsoleIO)
+
+#
+# Static Typing Support
+#
+
+
+class Reader[T](abc.ABC):
+    """Protocol for simple I/O reader instances.
+
+    This protocol only supports blocking I/O.
+    """
+
+    __slots__ = ()
+
+    @abstractmethod
+    def read(self, size: int = ..., /) -> T:
+        """Read data from the input stream and return it.
+
+        If "size" is specified, at most "size" items (bytes/characters) will be
+        read.
+        """
+
+    @classmethod
+    def __subclasshook__(cls, C):
+        if cls is Reader:
+            return _check_methods(C, "read")
+        return NotImplemented
+
+
+class Writer[T](abc.ABC):
+    """Protocol for simple I/O writer instances.
+
+    This protocol only supports blocking I/O.
+    """
+
+    __slots__ = ()
+
+    @abstractmethod
+    def write(self, data: T, /) -> int:
+        """Write data to the output stream and return number of items written."""
+
+    @classmethod
+    def __subclasshook__(cls, C):
+        if cls is Writer:
+            return _check_methods(C, "write")
+        return NotImplemented

Lib/typing.py

@@ -90,7 +90,6 @@
     'AsyncContextManager',
 
     # Structural checks, a.k.a. protocols.
-    'Reader',
     'Reversible',
     'SupportsAbs',
     'SupportsBytes',
@@ -99,7 +98,6 @@
     'SupportsIndex',
     'SupportsInt',
     'SupportsRound',
-    'Writer',
 
     # Concrete collection types.
     'ChainMap',
@@ -2931,36 +2929,6 @@ def __round__(self, ndigits: int = 0) -> T:
         pass
 
 
-class Reader[T](Protocol):
-    """Protocol for simple I/O reader instances.
-
-    This protocol only supports blocking I/O.
-    """
-
-    __slots__ = ()
-
-    @abstractmethod
-    def read(self, size: int = ..., /) -> T:
-        """Read data from the input stream and return it.
-
-        If "size" is specified, at most "size" items (bytes/characters) will be
-        read.
-        """
-
-
-class Writer[T](Protocol):
-    """Protocol for simple I/O writer instances.
-
-    This protocol only supports blocking I/O.
-    """
-
-    __slots__ = ()
-
-    @abstractmethod
-    def write(self, data: T, /) -> int:
-        """Write data to the output stream and return number of items written."""
-
-
 def _make_nmtuple(name, fields, annotate_func, module, defaults = ()):
     nm_tpl = collections.namedtuple(name, fields,
                                     defaults=defaults, module=module)