Repository navigation
Document generic parameters of generic classes #150319
Description
Activity
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.Reacted by Alex WaygoodOn second thought, maybe it's not too much. I just did
contextvarsand 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}
Doing all of these will also address:
There might be others too, but these were two I found on an initial pass.
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.
Reacted by Stephen Rosen- added 5 commits that reference this issue
on Jun 2, 2026 Looks completed, please re-open if there's more to do.
Reacted by Stephen Rosen
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