gh-127647: Add typing.Reader and Writer protocols

Doc/library/typing.rst

@@ -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,56 @@ 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]
+
+   Protocol for reading from a file or other input stream.
+
+   .. 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.
+
+   .. method:: readline(size=...)
+
+        Read a line of data from the input stream and return it. If ``size`` is
+        specified, at most ``size`` items (bytes/characters) will be read.
+
+   .. method:: __iter__()
+
+        Read a line of data from the input stream and return it.
+
+   For example::
+
+     def read_it(reader: Reader[str]):
+         assert reader.read(11) == "--marker--\n"
+         for line in reader:
+             print(line)
+
+.. class:: Writer[T]
+
+   Protocol for writing to a file or other output stream.
+
+   .. 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")
+
+Also consider using :class:`collections.abc.Iterable` for iterating over
+the lines of an input stream::
+
+  def read_config(stream: Iterable[str]):
+      for line in stream:
+          ...
+
 Functions and decorators
 ------------------------
 

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
 -----------
 

Lib/typing.py

@@ -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,43 @@ 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 input 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 input 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, 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)

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`.