From 93a51a644201b627ff960dfd17800515760f1ad2 Mon Sep 17 00:00:00 2001
From: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Date: Fri, 19 Nov 2021 05:15:23 -0800
Subject: [PATCH] Update typing-extensions README (#951)

- Add an explicit inclusion policy: new stuff can go in here as soon as there is a PEP
- Remove obsolete discussion of the typing PyPI package
- Organize the list of contents by Python version, so it's easier to find the interesting bits. Maybe we should deprecate the stuff that was new in 3.5/3.6 at some point.
---
 typing_extensions/README.rst | 121 ++++++++++++++++++++---------------
 1 file changed, 69 insertions(+), 52 deletions(-)

diff --git a/typing_extensions/README.rst b/typing_extensions/README.rst
index 54b7eb7bf..3730457f4 100644
--- a/typing_extensions/README.rst
+++ b/typing_extensions/README.rst
@@ -9,15 +9,19 @@ Typing Extensions
 Overview
 ========
 
-The ``typing_extensions`` module contains both backports of ``typing`` features
-as well as experimental types that will eventually be added to the ``typing``
-module, such as ``Protocol`` (see PEP 544 for details about protocols and
-static duck typing) or ``TypedDict`` (see PEP 589).
-
-Users of other Python versions should continue to install and use
-the ``typing`` module from PyPi instead of using this one unless
-specifically writing code that must be compatible with multiple Python
-versions or requires experimental types.
+The ``typing_extensions`` module serves two related purposes:
+
+- Enable use of new type system features on older Python versions. For example,
+  ``typing.TypeGuard`` is new in Python 3.10, but ``typing_extensions`` allows
+  users on Python 3.6 through 3.9 to use it too.
+- Enable experimentation with new type system PEPs before they are accepted and
+  added to the ``typing`` module.
+  
+New features may be added to ``typing_extensions`` as soon as they are specified
+in a PEP that has been added to the `python/peps <https://github.com/python/peps>`_
+repository. If the PEP is accepted, the feature will then be added to ``typing``
+for the next CPython release. No typing PEP has been rejected so far, so we
+haven't yet figured out how to deal with that possibility.
 
 Starting with version 4.0.0, ``typing_extensions`` uses
 `Semantic Versioning <https://semver.org/>`_. The
@@ -31,49 +35,62 @@ Included items
 
 This module currently contains the following:
 
-- ``Annotated``
-- ``AsyncContextManager``
-- ``AsyncGenerator``
-- ``AsyncIterable``
-- ``AsyncIterator``
-- ``Awaitable``
-- ``ChainMap``
-- ``ClassVar``
-- ``Concatenate``
-- ``ContextManager``
-- ``Coroutine``
-- ``Counter``
-- ``DefaultDict``
-- ``Deque``
-- ``final``
-- ``Final``
-- ``Literal``
-- ``NewType``
-- ``NoReturn``
-- ``NotRequired``
-- ``overload``
-- ``OrderedDict``
-- ``ParamSpec``
-- ``ParamSpecArgs``
-- ``ParamSpecKwargs``
-- ``Protocol``
-- ``Required``
-- ``runtime_checkable``
-- ``Self``
-- ``Text``
-- ``Type``
-- ``TypedDict``
-- ``TypeAlias``
-- ``TypeGuard``
-- ``TYPE_CHECKING``
-
-Python 3.7+
------------
-
-- ``get_origin``
-- ``get_args``
-- ``get_type_hints``
-
+- Experimental features
+
+  - ``NotRequired`` (see PEP 655)
+  - ``Required`` (see PEP 655)
+  - ``Self`` (see PEP 673)
+
+- In ``typing`` since Python 3.10
+  
+  - ``Concatenate`` (see PEP 612)
+  - ``ParamSpec`` (see PEP 612)
+  - ``ParamSpecArgs`` (see PEP 612)
+  - ``ParamSpecKwargs`` (see PEP 612)
+  - ``TypeAlias`` (see PEP 610)
+  - ``TypeGuard`` (see PEP 647)
+
+- In ``typing`` since Python 3.9
+
+  - ``Annotated`` (see PEP 593)
+
+- In ``typing`` since Python 3.8
+
+  - ``final`` (see PEP 591)
+  - ``Final`` (see PEP 591)
+  - ``Literal`` (see PEP 586)
+  - ``Protocol`` (see PEP 544)
+  - ``runtime_checkable`` (see PEP 544)
+  - ``TypedDict`` (see PEP 589)
+  - ``get_origin`` (``typing_extensions`` provides this function only in Python 3.7+)
+  - ``get_args`` (``typing_extensions`` provides this function only in Python 3.7+)
+
+- In ``typing`` since Python 3.7
+
+  - ``OrderedDict``
+
+- In ``typing`` since Python 3.5 or 3.6 (see `the typing documentation
+  <https://docs.python.org/3.10/library/typing.html>`_ for details)
+
+  - ``AsyncContextManager``
+  - ``AsyncGenerator``
+  - ``AsyncIterable``
+  - ``AsyncIterator``
+  - ``Awaitable``
+  - ``ChainMap``
+  - ``ClassVar`` (see PEP 526)
+  - ``ContextManager``
+  - ``Coroutine``
+  - ``Counter``
+  - ``DefaultDict``
+  - ``Deque``
+  - ``NewType``
+  - ``NoReturn``
+  - ``overload``
+  - ``Text``
+  - ``Type``
+  - ``TYPE_CHECKING``
+  - ``get_type_hints`` (``typing_extensions`` provides this function only in Python 3.7+)
 
 Other Notes and Limitations
 ===========================