gh-118803: Improve documentation around ByteString deprecation

Author: AlexWaygood

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

@@ -9,14 +9,27 @@ 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.
+
+   ``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`.
     (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.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.
+
+    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,6 +291,13 @@ 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`.

Doc/library/typing.rst

@@ -3790,8 +3790,13 @@ 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`.
+
+   ``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.
 
    .. deprecated-removed:: 3.9 3.17
       Prefer :class:`collections.abc.Buffer`, or a union like ``bytes | bytearray | memoryview``.

Doc/whatsnew/3.12.rst

@@ -1192,6 +1192,12 @@ Deprecated
   (Contributed by Prince Roshan in :gh:`103636`.)
 
 * :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`.
   (Contributed by Shantanu Jain in :gh:`91896`.)

Lib/_collections_abc.py

@@ -1082,9 +1082,12 @@ 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.
+    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``.
     """
 
     __slots__ = ()