bpo-40360: Deprecate lib2to3 module in light of PEP 617 (GH-19663)
Deprecate lib2to3 module in light of PEP 617.
We anticipate removal in the 3.12 timeframe.
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index eb4c918..1d7bd26 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -9,9 +9,7 @@
of *fixers* to transform it into valid Python 3.x code. The standard library
contains a rich set of fixers that will handle almost all code. 2to3 supporting
library :mod:`lib2to3` is, however, a flexible and generic library, so it is
-possible to write your own fixers for 2to3. :mod:`lib2to3` could also be
-adapted to custom applications in which Python code needs to be edited
-automatically.
+possible to write your own fixers for 2to3.
.. _2to3-using:
@@ -466,9 +464,17 @@
--------------
+.. deprecated:: 3.10
+ Python 3.9 will switch to a PEG parser (see :pep:`617`), and Python 3.10 may
+ include new language syntax that is not parsable by lib2to3's LL(1) parser.
+ The ``lib2to3`` module may be removed from the standard library in a future
+ Python version. Consider third-party alternatives such as `LibCST`_ or
+ `parso`_.
+
.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
-.. XXX What is the public interface anyway?
+.. _LibCST: https://libcst.readthedocs.io/
+.. _parso: https://parso.readthedocs.io/