[3.13] gh-118803: Improve documentation around ByteString deprecation (#139115) (#139137)

Author: AlexWaygood

Doc/deprecations/index.rst

@@ -7,6 +7,8 @@ Deprecations
 
 .. include:: pending-removal-in-3.16.rst
 
+.. include:: pending-removal-in-3.17.rst
+
 .. include:: pending-removal-in-future.rst
 
 C API Deprecations

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

@@ -0,0 +1,51 @@
+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
+    ``typing._UnionGenericAlias``. This class is no longer needed for the implementation,
+    but it has been retained for backward compatibility, with removal scheduled for Python
+    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.
+
+    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

@@ -289,11 +289,24 @@ Collections Abstract Base Classes -- Detailed Descriptions
          The :meth:`~sequence.index` method gained support for
          the *stop* and *start* arguments.
 
-   .. deprecated-removed:: 3.12 3.14
+   .. deprecated-removed:: 3.12 3.17
       The :class:`ByteString` ABC has been deprecated.
-      For use in typing, 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

@@ -3638,11 +3638,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`.
 
-   .. deprecated-removed:: 3.9 3.14
-      Prefer :class:`collections.abc.Buffer`, or a union like ``bytes | bytearray | memoryview``.
+   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
 
 .. 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 typing, 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
@@ -1347,6 +1361,8 @@ Deprecated
 
 .. include:: ../deprecations/pending-removal-in-3.16.rst
 
+.. include:: ../deprecations/pending-removal-in-3.17.rst
+
 .. include:: ../deprecations/pending-removal-in-future.rst
 
 .. _whatsnew312-removed:

Doc/whatsnew/3.13.rst

@@ -2034,6 +2034,8 @@ New Deprecations
 
 .. include:: ../deprecations/pending-removal-in-3.16.rst
 
+.. include:: ../deprecations/pending-removal-in-3.17.rst
+
 .. include:: ../deprecations/pending-removal-in-future.rst
 
 CPython Bytecode Changes

Lib/_collections_abc.py

@@ -1097,9 +1097,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__ = ()