https://github.com/python/cpython/commit/4305cc3ef35a35f9b2c163ae0ffeea219da5af5d
commit: 4305cc3ef35a35f9b2c163ae0ffeea219da5af5d
branch: main
author: Alex Waygood <[email protected]>
committer: AlexWaygood <[email protected]>
date: 2025-09-18T17:29:59Z
summary:
gh-118803: Improve documentation around `ByteString` deprecation (#139115)
files:
M Doc/deprecations/pending-removal-in-3.17.rst
M Doc/library/collections.abc.rst
M Doc/library/typing.rst
M Doc/whatsnew/3.12.rst
M Lib/_collections_abc.py
diff --git a/Doc/deprecations/pending-removal-in-3.17.rst
b/Doc/deprecations/pending-removal-in-3.17.rst
index 4fd4bde24d42b3..0a1c2f08cab3bd 100644
--- 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 9deaaee06a6bec..3d126bc83f5842 100644
--- 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 ef8752fea3bb6b..cf979205ff2cee 100644
--- 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 8e0cb652a73b03..2b6939cd323dcf 100644
--- 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 28427077127890..241d40d57409ae 100644
--- a/Lib/_collections_abc.py
+++ b/Lib/_collections_abc.py
@@ -1082,9 +1082,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__ = ()
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
