gh-118803: Improve documentation around `ByteString` deprecation (#139115)

diff --git a/Doc/deprecations/pending-removal-in-3.17.rst b/Doc/deprecations/pending-removal-in-3.17.rst
index 4fd4bde24d42b3f749bec48044b1c6c352a5a264..0a1c2f08cab3bd795617c1a6a7a5a7dbf92a0af1 100644 (file)
--- a/Doc/deprecations/pending-removal-in-3.17.rst
+++ b/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`.
-    (Contributed by Shantanu Jain in :gh:`91896`.)
+    Python 3.17.
 
-* :mod:`collections.abc`:
+    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).
 
-  - :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`.)
+    See :pep:`PEP 688 <688#current-options>` for more details.
+    (Contributed by Shantanu Jain in :gh:`91896`.)

diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 9deaaee06a6becf5e360b1eb08ab7f8cb261ea94..3d126bc83f58429aa3155604acd0638a15e2bd62 100644 (file)
--- a/Doc/library/collections.abc.rst
+++ b/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

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index ef8752fea3bb6b2ea518c41c246a6af4524cf52b..cf979205ff2cee9d5ab6a8f8a4bda2991d5851e8 100644 (file)
--- a/Doc/library/typing.rst
+++ b/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])
 

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 8e0cb652a73b03253da93a966f848d1bacbcceb8..2b6939cd323dcf70be22f632918566e155770799 100644 (file)
--- a/Doc/whatsnew/3.12.rst
+++ b/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

diff --git a/Lib/_collections_abc.py b/Lib/_collections_abc.py
index 2842707712789060329c81e8f57b9acb967d8428..241d40d57409aeb6deb604a2d798f8d347381e92 100644 (file)
--- a/Lib/_collections_abc.py
+++ b/Lib/_collections_abc.py
@@ -1082,9 +1082,13 @@ class _DeprecateByteStringMeta(ABCMeta):
         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__ = ()