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

[AlexWaygood]

This is a more-or-less clean revert of commit 2f4db5a. The PR adds back collections.abc.ByteString and typing.ByteString, postponing their removals to Python 3.17.

Prior to 2f4db5a, we had deprecation warnings for ByteString, but they only triggered if you subclassed ByteString or used ByteString as the second argument to isinstance() or issubclass(). Since the removal of ByteString, we've had multiple reports from users that these deprecation warnings have been insufficient and that the removal of ByteString took them by surprise:

• gh-118803: Remove ByteString from typing and collections.abc #118804 (comment)
• Remove use of typing.ByteString aio-libs/aiohttp#8408 (comment)
• Remove ByteString from typing and collections.abc #118803 (comment)

That's because many uses of ByteString do not subclass ByteString or use it as the second argument to isinstance(). Many uses of ByteString simply use it as a type annotation, and simply using it as a type annotation would not be sufficient to trigger a runtime deprecation warning informing you that the object would be removed in Python 3.14. Prior to removing the object from the collections.abc and typing modules entirely, it would be much better if we emitted a DeprecationWarning whenever the object is accessed or imported from collections.abc/typing.

Now, there's a good reason why we didn't do that in Python 3.12: ByteString is present both in collections.abc.__all__ and typing.__all__. Naively emitting a deprecation warning every time it was imported or accessed would have caused deprecation warnings to be emitted on every from collections.abc import * or from typing import * statement, which was deemed at the time to be far too noisy and disruptive (#104424). One solution would have been to remove ByteString from collections.abc.__all__ and typing.__all__, but we couldn't do that right away in Python 3.12 as it was a breaking change.

Nonetheless, removing ByteString from collections.abc.__all__ and typing.__all__ is much less of a breaking change than removing it entirely without prominent runtime deprecation warnings. Now that we're in a place where it's been deprecated in the docs for 2 releases and had some runtime deprecation warnings for 2 releases, I think we're now in a position where we can:

1. Easily add it back at runtime (what this PR does) and backport the add-back PR to 3.14
2. Remove ByteString from collections.abc.__all__ and typing.__all__ in Python 3.15
3. Add stronger deprecation warnings at runtime that put us in a good position to remove it entirely in Python 3.17

This PR should strictly improve backwards compatibility. It will not break anything for users who have already removed their uses of ByteString; they will simply be extremely well prepared for when ByteString is removed for good in Python 3.17. For users who have been unaware of the deprecation up till now, however (and there may be many such users that we don't know about in closed-source projects), this will mean that they are given much better notice that they should adapt their code for the forthcoming removal of ByteString in Python 3.17.

• Issue: Remove ByteString from typing and collections.abc #118803

---

📚 Documentation preview 📚: https://cpython-previews--138990.org.readthedocs.build/

[JelleZijlstra]

Maybe we should also change this documentation to make it clear that the type has no coherent meaning. Can do that later though.

[miss-islington-app]

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-138995 is a backport of this pull request to the 3.14 branch.