[3.14] gh-118803: Improve documentation around ByteString deprecation (GH-139115) (#139136)

gh-118803: Improve documentation around `ByteString` deprecation (GH-139115)
(cherry picked from commit 4305cc3ef3)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

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

@@ -1,6 +1,28 @@
 Pending removal in Python 3.17
 ------------------------------
 
+* :mod:`collections.abc`:
+
+  - :class:`collections.abc.ByteString` is scheduled for removal in Python 3.17.
+
+    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:`typing`:
 
   - Before Python 3.14, old-style unions were implemented using the private class
@@ -9,14 +31,21 @@ Pending removal in Python 3.17
     3.17. Users should use documented introspection helpers like :func:`typing.get_origin`
     and :func:`typing.get_args` instead of relying on private implementation details.
   - :class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for removal in
-    Python 3.17. 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`.
+    Python 3.17.
+
+    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:`collections.abc`:
-
-  - :class:`collections.abc.ByteString` is scheduled for removal in Python 3.17. 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`.)

Doc/library/collections.abc.rst

@@ -291,9 +291,22 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
    .. deprecated-removed:: 3.12 3.17
       The :class:`ByteString` ABC has been deprecated.
-      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

@@ -3790,11 +3790,25 @@ Aliases to container ABCs in :mod:`collections.abc`
 
 .. class:: ByteString(Sequence[int])
 
-   This type represents the types :class:`bytes`, :class:`bytearray`,
-   and :class:`memoryview` of byte sequences.
+   Deprecated alias to :class:`collections.abc.ByteString`.
+
+   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

@@ -1192,8 +1192,22 @@ Deprecated
   (Contributed by Prince Roshan in :gh:`103636`.)
 
 * :mod:`collections.abc`: Deprecated :class:`collections.abc.ByteString`.
-  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

@@ -1082,9 +1082,13 @@ def __instancecheck__(cls, instance):
         return super().__instancecheck__(instance)
 
 class ByteString(Sequence, metaclass=_DeprecateByteStringMeta):
-    """This unifies bytes and bytearray.
+    """Deprecated ABC serving as a common supertype of ``bytes`` and ``bytearray``.
 
-    XXX Should add all their methods.
+    This ABC is scheduled for removal in Python 3.17.
+    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__ = ()