Document generic parameters of generic classes

[JelleZijlstra]

Documentation

PEP-585 introduced native generic support several years ago by adding the __class_getitem__ method. But all docstrings for C-implemented __class_getitem__ methods are just "See PEP 585", and the online documentation has nothing to say about this.

When a class is generic, we should tell users what it is generic over, so that those who wish to use types can understand what type parameters to use.

In the online documentation, any generic class should have a note like "This class is generic [link to docs about generics] and takes N type parameters, representing respectively ...".

The docstring for the __class_getitem__ method should similarly outline what the type parameters are.

Linked PRs

• gh-150319: Replace all documentation which says "See PEP 585" #150325

[sirosen]

I started working on this, both to help out and deepen my knowledge.

Would it be best to formulate one PR for each module? There are 32 total cases of the exact text "See PEP 585" today, so that seems like too much documentation to review at once.
I'm starting with contextvars as an easy case, and can have a diff or PR ready shortly.

[sirosen]

On second thought, maybe it's not too much. I just did contextvars and it's 11 lines of change. Extrapolating out, that predicts a ~300 line documentation PR, which is still reviewable.

I'll do them all before submitting a PR, but for any early feedback, here's all I'm doing:

diff --git a/Doc/library/contextvars.rst b/Doc/library/contextvars.rst
index 93d0c0d34bf..c0006969673 100644
--- a/Doc/library/contextvars.rst
+++ b/Doc/library/contextvars.rst
@@ -42,6 +42,8 @@ Context Variables
    references to context variables which prevents context variables
    from being properly garbage collected.
 
+   Context Variables are :ref:`generic <generics>` over the type of their value.
+
    .. attribute:: ContextVar.name
 
       The name of the variable.  This is a read-only property.
@@ -130,6 +132,9 @@ Context Variables
    Tokens support the :ref:`context manager protocol <context-managers>`
    to automatically reset context variables. See :meth:`ContextVar.set`.
 
+   Tokens are :ref:`generic <generics>` over the same type as the
+   :class:`ContextVar` which created them.
+
    .. versionadded:: 3.14
 
       Added support for usage as a context manager.
diff --git a/Python/context.c b/Python/context.c
index 62b582f271f..e3e40d05856 100644
--- a/Python/context.c
+++ b/Python/context.c
@@ -1098,7 +1098,8 @@ static PyMethodDef PyContextVar_methods[] = {
     _CONTEXTVARS_CONTEXTVAR_SET_METHODDEF
     _CONTEXTVARS_CONTEXTVAR_RESET_METHODDEF
     {"__class_getitem__", Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("ContextVars are generic over the type of their value.")},
     {NULL, NULL}
 };
 
@@ -1264,7 +1265,8 @@ token_exit_impl(PyContextToken *self, PyObject *type, PyObject *val,
 
 static PyMethodDef PyContextTokenType_methods[] = {
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("Tokens are generic over the same type as the ContextVar which created them.")},
     TOKEN_ENTER_METHODDEF
     TOKEN_EXIT_METHODDEF
     {NULL}

[sirosen]

Doing all of these will also address:

• Clarify what memoryview is generic in #149488
• Links to PEP 585 in Generic types #140121

There might be others too, but these were two I found on an initial pass.

[JelleZijlstra]

Ah yeah, those issues are very similar. Feel free to make PRs but there may be more opinions on what the wording should be. Perhaps we should be more explicit about the type parameters ("X is generic and accepts a single type parameter, which represents Y."), especially when there are multiple.