Revert "gh-118803: Remove ByteString from typing and collections.abc (#118804)" (#138990)

Author: AlexWaygood

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

@@ -38,12 +38,6 @@ Pending removal in Python 3.14
     is no current event loop set and it decides to create one.
     (Contributed by Serhiy Storchaka and Guido van Rossum in :gh:`100160`.)
 
-* :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`.
-  (Contributed by Shantanu Jain in :gh:`91896`.)
-
 * :mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
   (Contributed by Alan Williams in :gh:`72346`.)
 
@@ -96,9 +90,6 @@ Pending removal in Python 3.14
     if :ref:`named placeholders <sqlite3-placeholders>` are used and
     *parameters* is a sequence instead of a :class:`dict`.
 
-* :mod:`typing`: :class:`!typing.ByteString`, deprecated since Python 3.9,
-  now causes a :exc:`DeprecationWarning` to be emitted when it is used.
-
 * :mod:`urllib`:
   :class:`!urllib.parse.Quoter` is deprecated: it was not intended to be a
   public API.

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

@@ -8,3 +8,15 @@ Pending removal in Python 3.17
     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. 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.Buffer`. (Contributed by Shantanu Jain in :gh:`91896`.)

Doc/library/collections.abc.rst

@@ -140,6 +140,9 @@ ABC                            Inherits from          Abstract Methods        Mi
                                                       ``__len__``,
                                                       ``insert``
 
+:class:`ByteString`            :class:`Sequence`      ``__getitem__``,        Inherited :class:`Sequence` methods
+                                                      ``__len__``
+
 :class:`Set`                   :class:`Collection`    ``__contains__``,       ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
                                                       ``__iter__``,           ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
                                                       ``__len__``             ``__sub__``, ``__rsub__``, ``__xor__``, ``__rxor__``
@@ -260,6 +263,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
 .. class:: Sequence
            MutableSequence
+           ByteString
 
    ABCs for read-only and mutable :term:`sequences <sequence>`.
 
@@ -285,6 +289,12 @@ Collections Abstract Base Classes -- Detailed Descriptions
          The :meth:`~sequence.index` method gained support for
          the *stop* and *start* arguments.
 
+   .. 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`.
+
 .. class:: Set
            MutableSet
 

Doc/library/stdtypes.rst

@@ -5544,6 +5544,7 @@ list is non-exhaustive.
 * :class:`collections.abc.MutableMapping`
 * :class:`collections.abc.Sequence`
 * :class:`collections.abc.MutableSequence`
+* :class:`collections.abc.ByteString`
 * :class:`collections.abc.MappingView`
 * :class:`collections.abc.KeysView`
 * :class:`collections.abc.ItemsView`

Doc/library/typing.rst

@@ -3788,6 +3788,14 @@ Aliases to container ABCs in :mod:`collections.abc`
       :class:`collections.abc.Set` now supports subscripting (``[]``).
       See :pep:`585` and :ref:`types-genericalias`.
 
+.. class:: ByteString(Sequence[int])
+
+   This type represents the types :class:`bytes`, :class:`bytearray`,
+   and :class:`memoryview` of byte sequences.
+
+   .. 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])
 
    Deprecated alias to :class:`collections.abc.Collection`.
@@ -4081,6 +4089,10 @@ convenience. This is subject to change, and not all deprecations are listed.
      - 3.9
      - Undecided (see :ref:`deprecated-aliases` for more information)
      - :pep:`585`
+   * - :class:`typing.ByteString`
+     - 3.9
+     - 3.17
+     - :gh:`91896`
    * - :data:`typing.Text`
      - 3.11
      - Undecided

Doc/whatsnew/3.12.rst

@@ -1191,9 +1191,9 @@ Deprecated
   replaced by :data:`calendar.JANUARY` and :data:`calendar.FEBRUARY`.
   (Contributed by Prince Roshan in :gh:`103636`.)
 
-* :mod:`collections.abc`: Deprecated :class:`!collections.abc.ByteString`.
+* :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`.
+  For use in type annotations, prefer a union, like ``bytes | bytearray``, or :class:`collections.abc.Buffer`.
   (Contributed by Shantanu Jain in :gh:`91896`.)
 
 * :mod:`datetime`: :class:`datetime.datetime`'s :meth:`~datetime.datetime.utcnow` and
@@ -1301,7 +1301,7 @@ Deprecated
     :class:`collections.abc.Hashable` and :class:`collections.abc.Sized` respectively, are
     deprecated. (:gh:`94309`.)
 
-  * :class:`!typing.ByteString`, deprecated since Python 3.9, now causes a
+  * :class:`typing.ByteString`, deprecated since Python 3.9, now causes a
     :exc:`DeprecationWarning` to be emitted when it is used.
     (Contributed by Alex Waygood in :gh:`91896`.)
 

Doc/whatsnew/3.14.rst

@@ -2560,15 +2560,6 @@ asyncio
          blocking_code()
          runner.run(operation_two())
 
-
-collections.abc
----------------
-
-* Remove :class:`!ByteString`, which has been deprecated since Python 3.12.
-  (Contributed by Nikita Sobolev in :gh:`118803`.)
-
-
-
 email
 -----
 
@@ -2647,13 +2638,6 @@ sqlite3
   (Contributed by Erlend E. Aasland in :gh:`118928` and :gh:`101693`.)
 
 
-typing
-------
-
-* Remove :class:`!ByteString`, which has been deprecated since Python 3.12.
-  (Contributed by Nikita Sobolev in :gh:`118803`.)
-
-
 urllib
 ------
 

Doc/whatsnew/3.5.rst

@@ -936,7 +936,7 @@ methods to match the corresponding methods of :class:`str`.
 collections.abc
 ---------------
 
-The :meth:`Sequence.index() <collections.abc.MutableSequence.index>` method now
+The :meth:`!Sequence.index` method now
 accepts *start* and *stop* arguments to match the corresponding methods
 of :class:`tuple`, :class:`list`, etc.
 (Contributed by Devin Jeanpierre in :issue:`23086`.)

Lib/_collections_abc.py

@@ -49,7 +49,7 @@ def _f(): pass
            "Mapping", "MutableMapping",
            "MappingView", "KeysView", "ItemsView", "ValuesView",
            "Sequence", "MutableSequence",
-           "Buffer",
+           "ByteString", "Buffer",
            ]
 
 # This module has been renamed from collections.abc to _collections_abc to
@@ -1061,6 +1061,37 @@ def count(self, value):
 Sequence.register(range)
 Sequence.register(memoryview)
 
+class _DeprecateByteStringMeta(ABCMeta):
+    def __new__(cls, name, bases, namespace, **kwargs):
+        if name != "ByteString":
+            import warnings
+
+            warnings._deprecated(
+                "collections.abc.ByteString",
+                remove=(3, 17),
+            )
+        return super().__new__(cls, name, bases, namespace, **kwargs)
+
+    def __instancecheck__(cls, instance):
+        import warnings
+
+        warnings._deprecated(
+            "collections.abc.ByteString",
+            remove=(3, 17),
+        )
+        return super().__instancecheck__(instance)
+
+class ByteString(Sequence, metaclass=_DeprecateByteStringMeta):
+    """This unifies bytes and bytearray.
+
+    XXX Should add all their methods.
+    """
+
+    __slots__ = ()
+
+ByteString.register(bytes)
+ByteString.register(bytearray)
+
 
 class MutableSequence(Sequence):
     """All the operations on a read-write sequence.

Lib/test/test_collections.py

@@ -26,7 +26,7 @@
 from collections.abc import Set, MutableSet
 from collections.abc import Mapping, MutableMapping, KeysView, ItemsView, ValuesView
 from collections.abc import Sequence, MutableSequence
-from collections.abc import Buffer
+from collections.abc import ByteString, Buffer
 
 
 class TestUserObjects(unittest.TestCase):
@@ -1934,6 +1934,28 @@ def assert_index_same(seq1, seq2, index_args):
                         assert_index_same(
                             nativeseq, seqseq, (letter, start, stop))
 
+    def test_ByteString(self):
+        for sample in [bytes, bytearray]:
+            with self.assertWarns(DeprecationWarning):
+                self.assertIsInstance(sample(), ByteString)
+            self.assertTrue(issubclass(sample, ByteString))
+        for sample in [str, list, tuple]:
+            with self.assertWarns(DeprecationWarning):
+                self.assertNotIsInstance(sample(), ByteString)
+            self.assertFalse(issubclass(sample, ByteString))
+        with self.assertWarns(DeprecationWarning):
+            self.assertNotIsInstance(memoryview(b""), ByteString)
+        self.assertFalse(issubclass(memoryview, ByteString))
+        with self.assertWarns(DeprecationWarning):
+            self.validate_abstract_methods(ByteString, '__getitem__', '__len__')
+
+        with self.assertWarns(DeprecationWarning):
+            class X(ByteString): pass
+
+        with self.assertWarns(DeprecationWarning):
+            # No metaclass conflict
+            class Z(ByteString, Awaitable): pass
+
     def test_Buffer(self):
         for sample in [bytes, bytearray, memoryview]:
             self.assertIsInstance(sample(b"x"), Buffer)