gh-91896: Deprecate collections.abc.ByteString

Doc/library/collections.abc.rst

@@ -273,6 +273,12 @@ Collections Abstract Base Classes -- Detailed Descriptions
  The index() method added support for *stop* and *start*
  arguments.
 
+ .. deprecated-removed:: 3.12 3.14
+ 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`.
+
 .. class:: Set
  MutableSet
 

Doc/library/typing.rst

@@ -2139,8 +2139,7 @@ Corresponding to collections in :mod:`collections.abc`
  annotate arguments of any of the types mentioned above.
 
  .. deprecated:: 3.9
- :class:`collections.abc.ByteString` now supports subscripting (``[]``).
- See :pep:`585` and :ref:`types-genericalias`.
+ 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

@@ -792,6 +792,11 @@ Pending Removal in Python 3.14
 
  (Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)
 
+* 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`.)
+
 * Creating immutable types (:data:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
  bases using the C API.
 

Lib/_collections_abc.py

@@ -1071,8 +1071,27 @@ def count(self, value):
 Sequence.register(range)
 Sequence.register(memoryview)
 
-
-class ByteString(Sequence):
+class _DeprecateByteStringMeta(ABCMeta):
+ def __new__(cls, name, bases, namespace, **kwargs):
+ if name != "ByteString":
+ import warnings
+
+ warnings._deprecated(
+ "collections.abc.ByteString",
+ remove=(3, 14),
+ )
+ return super().__new__(cls, name, bases, namespace, **kwargs)
+
+ def __instancecheck__(cls, instance):
+ import warnings
+
+ warnings._deprecated(
+ "collections.abc.ByteString",
+ remove=(3, 14),
+ )
+ return super().__instancecheck__(instance)
+
+class ByteString(Sequence, metaclass=_DeprecateByteStringMeta):
  """This unifies bytes and bytearray.
 
  XXX Should add all their methods.

Lib/test/test_collections.py

@@ -1940,14 +1940,25 @@ def assert_index_same(seq1, seq2, index_args):
 
  def test_ByteString(self):
  for sample in [bytes, bytearray]:
- self.assertIsInstance(sample(), ByteString)
+ with self.assertWarns(DeprecationWarning):
+ self.assertIsInstance(sample(), ByteString)
  self.assertTrue(issubclass(sample, ByteString))
  for sample in [str, list, tuple]:
- self.assertNotIsInstance(sample(), ByteString)
+ with self.assertWarns(DeprecationWarning):
+ self.assertNotIsInstance(sample(), ByteString)
  self.assertFalse(issubclass(sample, ByteString))
- self.assertNotIsInstance(memoryview(b""), ByteString)
+ with self.assertWarns(DeprecationWarning):
+ self.assertNotIsInstance(memoryview(b""), ByteString)
  self.assertFalse(issubclass(memoryview, ByteString))
- self.validate_abstract_methods(ByteString, '__getitem__', '__len__')
+ 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]:

Misc/NEWS.d/next/Library/2023-03-08-02-45-46.gh-issue-91896.kgON_a.rst

@@ -0,0 +1 @@
+Deprecate :class:`collections.abc.ByteString`