Add typing.Reader and Writer protocols

python · JelleZijlstra · Mar 6, 2025 · Dec 5, 2024 · Dec 5, 2024 · Dec 5, 2024
commit b45fec0277709c72fe42903425963a156b152067
@@ -2803,8 +2803,8 @@ with :func:`@runtime_checkable <runtime_checkable>`.
     An ABC with one abstract method ``__round__``
     that is covariant in its return type.
 
-ABCs for working with IO
-------------------------
+ABCs and Protocols for working with I/O
+---------------------------------------
 
 .. class:: IO
            TextIO
@@ -2815,6 +2815,28 @@ ABCs for working with IO
    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]
+   .. method:: read(size=...)
-   .. method:: read(size=...)
+   .. method:: read(size=..., /)
-   .. method:: read(size=...)
+   .. method:: read(size=..., /)
+   .. method:: readline(size=...)
+   .. method:: __iter__()
+
+.. class:: Writer[T]
+   .. method:: write(o)
+
+For example::
+
+  def read_it(reader: Reader[str]):
+      assert reader.read(11) == "--marker--\n"
+      for line in reader:
+          print(line)
+
+  def write_binary(writer: Writer[bytes]):
+      writer.write(b"Hello world!\n")
+
 Functions and decorators
 ------------------------
 

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -607,6 +607,14 @@ tkinter
   (Contributed by Zhikang Yan in :gh:`126899`.)
 
 
+typing
+------
+
+* Add protocols :class:`typing.Reader` and :class:`typing.Writer` as a simpler
+  alternatives to the pseudo-protocols :class:`typing.IO`,
+  :class:`typing.TextIO`, and :class:`typing.BinaryIO`.
+
+
 unicodedata
 -----------
 

@@ -90,6 +90,7 @@
     'AsyncContextManager',
 
     # Structural checks, a.k.a. protocols.
+    'Reader',
     'Reversible',
     'SupportsAbs',
     'SupportsBytes',
@@ -98,6 +99,7 @@
     'SupportsIndex',
     'SupportsInt',
     'SupportsRound',
+    'Writer',
 
     # Concrete collection types.
     'ChainMap',
@@ -2925,6 +2927,42 @@ def __round__(self, ndigits: int = 0) -> T:
         pass
 
 
+@runtime_checkable
+class Reader[T](Iterable[T], Protocol):
+    """Protocol for simple I/O reader instances.
+
+    This protocol only supports blocking I/O.
+    """
+
+    __slots__ = ()
+
+    def read(self, size: int = ..., /) -> T:
+        """Read data from the I/O stream and return it.
+
+        If "size" is specified, at most "size" items (bytes/characters) will be
+        read.
+        """
+    def readline(self, size: int = ..., /) -> T:
+        """Read a line of data from the I/O stream and return it.
+
+        If "size" is specified, at most "size" items (bytes/characters) will be
+        read.
+        """
+
+
+@runtime_checkable
+class Writer[T](Protocol):
+    """Protocol for simple I/O writer instances.
+
+    This protocol only supports blocking I/O.
+    """
+
+    __slots__ = ()
+
+    def write(self, o: T, /) -> int:
+        """Write data to the I/O 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)

diff --git a/Misc/NEWS.d/next/Library/2024-12-05-19-54-16.gh-issue-127647.Xd78Vs.rst b/Misc/NEWS.d/next/Library/2024-12-05-19-54-16.gh-issue-127647.Xd78Vs.rst
@@ -0,0 +1,3 @@
+Add protocols :class:`typing.Reader` and :class:`typing.Writer` as
+alternatives to :class:`typing.IO`, :class:`typing.TextIO`, and
+:class:`typing.BinaryIO`.