Attempt to clarify the ByteString situation (#9783)

See python/cpython#102092

This makes the behaviour of typing.ByteString better match its
documentation.

Author: hauntsaninja

stdlib/builtins.pyi

@@ -36,7 +36,6 @@ from typing import (  # noqa: Y022
     IO,
     Any,
     BinaryIO,
-    ByteString,
     ClassVar,
     Generic,
     Mapping,
@@ -592,7 +591,7 @@ class str(Sequence[str]):
     def __rmul__(self, __value: SupportsIndex) -> str: ...  # type: ignore[misc]
     def __getnewargs__(self) -> tuple[str]: ...
 
-class bytes(ByteString):
+class bytes(Sequence[int]):
     @overload
     def __new__(cls, __o: Iterable[SupportsIndex] | SupportsIndex | SupportsBytes | ReadableBuffer) -> Self: ...
     @overload
@@ -697,7 +696,7 @@ class bytes(ByteString):
 
     def __buffer__(self, __flags: int) -> memoryview: ...
 
-class bytearray(MutableSequence[int], ByteString):
+class bytearray(MutableSequence[int]):
     @overload
     def __init__(self) -> None: ...
     @overload

stdlib/typing.pyi

@@ -771,7 +771,7 @@ class TextIO(IO[str]):
     @abstractmethod
     def __enter__(self) -> TextIO: ...
 
-class ByteString(Sequence[int], metaclass=ABCMeta): ...
+ByteString: typing_extensions.TypeAlias = bytes | bytearray | memoryview
 
 # Functions
 

tests/stubtest_allowlists/py37.txt

@@ -23,6 +23,7 @@ collections.AsyncGenerator.ag_await
 collections.AsyncGenerator.ag_code
 collections.AsyncGenerator.ag_frame
 collections.AsyncGenerator.ag_running
+collections.ByteString  # see comments in py3_common.txt
 collections.Callable
 collections.Mapping.__reversed__  # Set to None at runtime for a better error message
 contextvars.ContextVar.get

tests/stubtest_allowlists/py38.txt

@@ -29,6 +29,7 @@ collections.AsyncGenerator.ag_await
 collections.AsyncGenerator.ag_code
 collections.AsyncGenerator.ag_frame
 collections.AsyncGenerator.ag_running
+collections.ByteString  # see comments in py3_common.txt
 collections.Callable
 collections.ItemsView.__reversed__
 collections.KeysView.__reversed__

tests/stubtest_allowlists/py39.txt

@@ -27,6 +27,7 @@ collections.AsyncGenerator.ag_await
 collections.AsyncGenerator.ag_code
 collections.AsyncGenerator.ag_frame
 collections.AsyncGenerator.ag_running
+collections.ByteString  # see comments in py3_common.txt
 collections.Callable
 collections.Mapping.__reversed__  # Set to None at runtime for a better error message
 collections.ItemsView.__reversed__

tests/stubtest_allowlists/py3_common.txt

@@ -667,6 +667,11 @@ xml.etree.ElementTree.Element.__iter__
 xml.etree.cElementTree.Element.__iter__
 typing.IO.__iter__  # See https://github.com/python/typeshed/commit/97bc450acd60c1bcdafef3ce8fbe3b95a9c0cac3
 
+# Pretend typing.ByteString is a Union, to better match its documented semantics.
+# As a side effect, this changes the definition of collections.abc.ByteString, which is okay,
+# because it's not an ABC that makes any sense and was deprecated in 3.12
+_collections_abc.ByteString
+
 # ==========
 # Missing from deprecated modules
 # Any of these can be added if someone needs them