gh-142918: Fix Context.items/keys/values docstrings (return iterators, not lists)

[hyongtao-code]

_contextvars.Context.items(), .keys(), and .values() return iterator objects, but their docstrings incorrectly claim they return lists.

Taking items() as an example, its call chain is _contextvars_Context_items_impl() → _PyHamt_NewIterItems().
The comment on _contextvars_Context_items_impl states that it returns a list, but the comment on _PyHamt_NewIterItems indicates that it returns an iterator.

Update the Argument Clinic docstrings in Python/context.c and regenerate Python/clinic/context.c.h. No behavior change.

📚 Documentation preview 📚: https://cpython-previews--142919.org.readthedocs.build/en/142919/library/contextvars.html?readthedocs-diff=true&readthedocs-diff-chunk=1

Script to reproduce

import contextvars

ctx = contextvars.copy_context()

print("items() type:", type(ctx.items()))
print("keys()  type:", type(ctx.keys()))
print("values() type:", type(ctx.values()))

print("items() is list?", isinstance(ctx.items(), list))
print("keys()  is list?", isinstance(ctx.keys(), list))
print("values() is list?", isinstance(ctx.values(), list))

print("\nDocstrings say 'list'?")
print("items doc contains 'list':", "list" in (ctx.items.__doc__ or ""))
print("keys  doc contains 'list':", "list" in (ctx.keys.__doc__ or ""))
print("values doc contains 'list':", "list" in (ctx.values.__doc__ or ""))

Result without the patch

d:\MyCode\cpython\PCbuild\amd64>python_d.exe py_context.py
items() type: <class 'items'>
keys()  type: <class 'keys'>
values() type: <class 'values'>
items() is list? False
keys()  is list? False
values() is list? False

Docstrings say 'list'?
items doc contains 'list': True
keys  doc contains 'list': True
values doc contains 'list': True

Result with the patch

d:\MyCode\cpython\PCbuild\amd64>python_d.exe py_context.py
items() type: <class 'items'>
keys()  type: <class 'keys'>
values() type: <class 'values'>
items() is list? False
keys()  is list? False
values() is list? False

Docstrings say 'list'?
items doc contains 'list': False  <-- !!!! here
keys  doc contains 'list': False
values doc contains 'list': False

Signed-off-by: Yongtao Huang yongtaoh2022@gmail.com

• Issue: Context.items/keys/values docstrings claim lists but return iterators #142918

[StanFromIreland]

The docs also use "a list," it should be fixed too.

[hyongtao-code]

Thanks for the reminder — the corresponding docs have been updated.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.