Address Adam's feedback

Author: AlexWaygood

Doc/deprecations/pending-removal-in-3.17.rst

@@ -5,14 +5,23 @@ Pending removal in Python 3.17
 
   - :class:`collections.abc.ByteString` is scheduled for removal in Python 3.17.
 
-    ``ByteString`` was originally intended to be an abstract type that would serve as a
-    supertype of both :class:`bytes` and :class:`bytearray`, but its semantics were never
-    clearly specified, and it was never understood properly by type checkers. See
-    :pep:`PEP 688 <688#current-options>` for more details.
+    Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj``
+    implements the :ref:`buffer protocol <bufferobjects>` at runtime. For use
+    in type annotations, either use :class:`Buffer` or a union that explicitly
+    specifies the types your code supports (e.g.,
+    ``bytes | bytearray | memoryview``).
+
+    :class:`!ByteString` was originally intended to be an abstract class that
+    would serve as a supertype of both :class:`bytes` and :class:`bytearray`.
+    However, since the ABC never had any methods, knowing that an object was an
+    instance of :class:`!ByteString` never actually told you anything useful
+    about the object. Other common buffer types such as :class:`memoryview`
+    were also never understood as subtypes of :class:`!ByteString` (either at
+    runtime or by static type checkers).
+
+    See :pep:`PEP 688 <688#current-options>` for more details.
+    (Contributed by Shantanu Jain in :gh:`91896`.)
 
-    Prefer :class:`~collections.abc.Sequence` or :class:`~collections.abc.Buffer`. For
-    use in type annotations, prefer a union, like ``bytes | bytearray``, or
-    :class:`collections.abc.Buffer`. (Contributed by Shantanu Jain in :gh:`91896`.)
 
 * :mod:`typing`:
 
@@ -24,12 +33,19 @@ Pending removal in Python 3.17
   - :class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for removal in
     Python 3.17.
 
-   ``ByteString`` was originally intended to be an abstract type that would serve as a
-    supertype of both :class:`bytes` and :class:`bytearray`, but its semantics were never
-    clearly specified, and it was never understood properly by type checkers. See
-    :pep:`PEP 688 <688#current-options>` for more details.
-
-    Prefer :class:`~collections.abc.Sequence` or :class:`~collections.abc.Buffer`. For
-    use in type annotations, prefer a union, like ``bytes | bytearray``, or
-    :class:`collections.abc.Buffer`.
+    Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj``
+    implements the :ref:`buffer protocol <bufferobjects>` at runtime. For use
+    in type annotations, either use :class:`~collections.abc.Buffer` or a union
+    that explicitly specifies the types your code supports (e.g.,
+    ``bytes | bytearray | memoryview``).
+
+    :class:`!ByteString` was originally intended to be an abstract class that
+    would serve as a supertype of both :class:`bytes` and :class:`bytearray`.
+    However, since the ABC never had any methods, knowing that an object was an
+    instance of :class:`!ByteString` never actually told you anything useful
+    about the object. Other common buffer types such as :class:`memoryview`
+    were also never understood as subtypes of :class:`!ByteString` (either at
+    runtime or by static type checkers).
+
+    See :pep:`PEP 688 <688#current-options>` for more details.
     (Contributed by Shantanu Jain in :gh:`91896`.)

Doc/library/collections.abc.rst

@@ -292,15 +292,21 @@ Collections Abstract Base Classes -- Detailed Descriptions
    .. deprecated-removed:: 3.12 3.17
       The :class:`ByteString` ABC has been deprecated.
 
-      ``ByteString`` was originally intended to be an abstract type that would
-      serve as a supertype of both :class:`bytes` and :class:`bytearray`, but
-      its semantics were never clearly specified, and it was never understood
-      properly by type checkers. See :pep:`PEP 688 <688#current-options>` for
-      more details.
-
-      For use in type annotations, prefer a union, like ``bytes | bytearray``, or
-      :class:`collections.abc.Buffer`.
-      For use as an ABC, prefer :class:`Sequence` or :class:`collections.abc.Buffer`.
+      Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj``
+      implements the :ref:`buffer protocol <bufferobjects>` at runtime. For use
+      in type annotations, either use :class:`Buffer` or a union that
+      explicitly specifies the types your code supports (e.g.,
+      ``bytes | bytearray | memoryview``).
+
+      :class:`!ByteString` was originally intended to be an abstract class that
+      would serve as a supertype of both :class:`bytes` and :class:`bytearray`.
+      However, since the ABC never had any methods, knowing that an object was
+      an instance of :class:`!ByteString` never actually told you anything
+      useful about the object. Other common buffer types such as
+      :class:`memoryview` were also never understood as subtypes of
+      :class:`!ByteString` (either at runtime or by static type checkers).
+
+      See :pep:`PEP 688 <688#current-options>` for more details.
 
 .. class:: Set
            MutableSet

Doc/library/typing.rst

@@ -3792,14 +3792,23 @@ Aliases to container ABCs in :mod:`collections.abc`
 
    Deprecated alias to :class:`collections.abc.ByteString`.
 
-   ``ByteString`` was originally intended to be an abstract type that would
-   serve as a supertype of both :class:`bytes` and :class:`bytearray`. However,
-   its semantics were never clearly specified, and it was never understood
-   properly by type checkers. See :pep:`PEP 688 <688#current-options>` for more
-   details.
+   Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj``
+   implements the :ref:`buffer protocol <bufferobjects>` at runtime. For use in
+   type annotations, either use :class:`~collections.abc.Buffer` or a union
+   that explicitly specifies the types your code supports (e.g.,
+   ``bytes | bytearray | memoryview``).
+
+   :class:`!ByteString` was originally intended to be an abstract class that
+   would serve as a supertype of both :class:`bytes` and :class:`bytearray`.
+   However, since the ABC never had any methods, knowing that an object was an
+   instance of :class:`!ByteString` never actually told you anything useful
+   about the object. Other common buffer types such as :class:`memoryview` were
+   also never understood as subtypes of :class:`!ByteString` (either at runtime
+   or by static type checkers).
+
+   See :pep:`PEP 688 <688#current-options>` for more details.
 
    .. deprecated-removed:: 3.9 3.17
-      Prefer :class:`collections.abc.Buffer`, or a union like ``bytes | bytearray | memoryview``.
 
 .. class:: Collection(Sized, Iterable[T_co], Container[T_co])
 

Doc/whatsnew/3.12.rst

@@ -1193,13 +1193,21 @@ Deprecated
 
 * :mod:`collections.abc`: Deprecated :class:`collections.abc.ByteString`.
 
-  ``ByteString`` was originally intended to be an abstract type that would
-  serve as a supertype of both :class:`bytes` and :class:`bytearray`, but its
-  semantics were never clearly specified, and it was never understood properly
-  by type checkers. See :pep:`PEP 688 <688#current-options>` for more details.
-
-  Prefer :class:`Sequence` or :class:`collections.abc.Buffer`.
-  For use in type annotations, prefer a union, like ``bytes | bytearray``, or :class:`collections.abc.Buffer`.
+  Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj`` implements
+  the :ref:`buffer protocol <bufferobjects>` at runtime. For use in type
+  annotations, either use :class:`~collections.abc.Buffer` or a union
+  that explicitly specifies the types your code supports (e.g.,
+  ``bytes | bytearray | memoryview``).
+
+  :class:`!ByteString` was originally intended to be an abstract class that
+  would serve as a supertype of both :class:`bytes` and :class:`bytearray`.
+  However, since the ABC never had any methods, knowing that an object was an
+  instance of :class:`!ByteString` never actually told you anything useful
+  about the object. Other common buffer types such as :class:`memoryview` were
+  also never understood as subtypes of :class:`!ByteString` (either at
+  runtime or by static type checkers).
+
+  See :pep:`PEP 688 <688#current-options>` for more details.
   (Contributed by Shantanu Jain in :gh:`91896`.)
 
 * :mod:`datetime`: :class:`datetime.datetime`'s :meth:`~datetime.datetime.utcnow` and

Lib/_collections_abc.py

@@ -1085,9 +1085,10 @@ class ByteString(Sequence, metaclass=_DeprecateByteStringMeta):
     """Deprecated ABC serving as a common supertype of ``bytes`` and ``bytearray``.
 
     This ABC is scheduled for removal in Python 3.17.
-    For use in type annotations, prefer a union, like ``bytes | bytearray``, or
-    ``collections.abc.Buffer``. For use as an ABC, prefer ``Sequence`` or
-    ``collections.abc.Buffer``.
+    Use ``isinstance(obj, collections.abc.Buffer)`` to test if ``obj``
+    implements the buffer protocol at runtime. For use in type annotations,
+    either use ``Buffer`` or a union that explicitly specifies the types your
+    code supports (e.g., ``bytes | bytearray | memoryview``).
     """
 
     __slots__ = ()