Repository: python/cpython
Pull request: gh-92332: Docs-only deprecation of `typing.Text`
Closes #92332

Problem statement:
Deprecate `typing.Text`
**Feature or enhancement**

The `typing` module has a huge API, and new features continue to be added in each version of Python. Deprecations should be done carefully and slowly, to minimise disruption for users, but we should nonetheless aim to shrink the API where features are no longer needed, so as to make the sheer size of the module less overwhelming for newcomers to Python typing.

Python 2.7 is now end-of-life, so `typing.Text` has no use anymore (its sole purpose was to provide backwards compatibility with Python 2). I propose that we should now deprecate `typing.Text`, with a view to eventually removing it.

Hints from issue discussion:
I agree on deprecating `Text` and removing it from examples, but I don't want to remove it for a long time: that just needlessly breaks previously working code.

To reduce cognitive load on readers of the `typing` module docs, we can eventually move it to a separate section about deprecated names and cover it only briefly.
> I don't want to remove it for a long time: that just needlessly breaks previously working code.

We agree.
It's [pretty easy to miss](https://github.com/python/cpython/blob/ae553b3561f0f8e1fed454bbbd55073e4ba711eb/Lib/typing.py#L3099) :).

To be clear, by "a long time" I mean something like "wait a decade and then maybe start thinking about removing it". We shouldn't set a concrete removal timeline yet.
> It's [pretty easy to miss](https://github.com/python/cpython/blob/ae553b3561f0f8e1fed454bbbd55073e4ba711eb/Lib/typing.py#L3099) :).

It's *definitely* not a big maintenance burden or anything!

Commit message: Docs-only deprecation of `typing.Text`

Patch to review:
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 88085594caaff2..30e97a81688d2f 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1976,6 +1976,11 @@ Other concrete types
 
    .. versionadded:: 3.5.2
 
+   .. deprecated:: 3.11
+      Python 2 is no longer supported at runtime, and is also no longer
+      supported by most type checkers. Users should therefore now use
+      :class:`str` instead of ``Text`` wherever possible.
+
 Abstract Base Classes
 ---------------------
 
@@ -2687,3 +2692,5 @@ convenience. This is subject to change, and not all deprecations are listed.
 |  ``typing`` versions of standard | 3.9           | Undecided         | :pep:`585`     |
 |  collections                     |               |                   |                |
 +----------------------------------+---------------+-------------------+----------------+
+|  ``typing.Text``                 | 3.11          | Undecided         | :gh:`92332`    |
++----------------------------------+---------------+-------------------+----------------+
diff --git a/Misc/NEWS.d/next/Library/2022-05-05-22-46-52.gh-issue-92332.Fv9CJx.rst b/Misc/NEWS.d/next/Library/2022-05-05-22-46-52.gh-issue-92332.Fv9CJx.rst
new file mode 100644
index 00000000000000..1d055bb2b99f40
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-05-05-22-46-52.gh-issue-92332.Fv9CJx.rst
@@ -0,0 +1,2 @@
+Deprecate :class:`typing.Text` (removal of the class is currently not
+planned). Patch by Alex Waygood.


Code review comments:
diff_hunk: @@ -1976,6 +1976,11 @@ Other concrete types
 
    .. versionadded:: 3.5.2
 
+   .. deprecated:: 3.11
+      Python 2 is no longer supported at runtime, and is also no longer
+      supported by most type checkers. Users should therefore now use
path: Doc/library/typing.rst
text: @user1:
"at runtime" is a little confusing, especially when combined with the "deprecated in Python 3.11"
```suggestion
   .. deprecated:: 3.11
      Python 2 is no longer supported and most type checkers no longer
      support type checking Python 2 code either. Users should now use
```

@author:
Nice!