gh-150319: Replace all documentation which says "See PEP 585" (#150325)
* Replace all documentation which says "See PEP 585"
The following classes in the stdlib get simple updates:
- array.array
- asyncio.Future
- asyncio.Task
- collections.defaultdict
- collections.deque
- contextvars.ContextVar
- contextvars.Token
- ctypes.Array
- os.DirEntry
- re.Match
- re.Pattern
- string.templatelib.Interpolation
- string.templatelib.Template
- types.MappingProxyType
- queue.SimpleQueue
- weakref.ref
The following classes are documented publicly as functions, and are
therefore updated internally (`__class_getitem__.__doc__`) but not in the
public docs:
- functools.partial
- itertools.chain
The following builtin types have updates to `__class_getitem__.__doc__`
but not to any documentation pages:
- BaseExceptionGroup
- coroutines (from generators)
- dict
- enumerate
- frozendict
- frozenset
- generators (and async generators)
- list
- memoryview
- set
- slice
- tuple
Special cases:
- union objects are now documented as "supporting class-level []",
rather than anything to do with generics.
- Templates might be generic over a single type (union, in theory) or
over a TypeVarTuple. As this is not currently fully settled, it is
marked with a comment and a mild hint that it is a single type is used
(namely, "type" is singular rather than "types", plural)
* Apply suggestions from code review
* Correct several class getitem docs
And expand the text for tuples.
* Add notes on generic typing of builtins
* Fix typo in tuple.__class_getitem__ docstring
* Typo fix: malformed refs
Fix `generic` links which weren't marked as `:ref:`.
* Strike unnecessary docs on generic-ness
* Apply suggestions from code review
These are applied at both the originally indicated locations and in the
corresponding docstring definitions.
* Update Doc/library/re.rst
* Update Objects/enumobject.c
* Remove tuple generic doc in 'stdtypes' page
This is covered in more detail in the cross-linked typing documentation.
The other copy of this documentation -- in the docstring for
`tuple.__class_getitem__` -- is left in place.
* Fix whitespace around new doc of generics
Per review, do not introduce or remove whitespace such that section
breaks are altered by the introduction of doc on various generic types.
In most cases, this is a removal of an extra line.
In one case (Arrays), it is the reintroduction of a line.
Additionally, two other minor fixes are included:
- incorrect indent on 'defaultdicts'
- make `mappingproxy.__class_getitem__.__doc__` consistent with other
mapping type generic docs
* Move placement of memoryview generic note
Previous placement was at the end of the main docstring, which is
consistent with other types but places it after a section on various
methods (which makes it read somewhat inconsistently). Moving it up
helps resolve.
* Ensure sphinxdoc does not start sentences lowercase
Lowercase class names at the start of sentences are marked out with the
`class` role. In the case of `deque`, documentation already refers to
these as `Deques`, so this form is preferred.
* Apply suggestions from code review
* Fix line endings and wrap more tightly
Line endings fixed by pre-commit ; also re-wrapped the MappingProxyType
text which was too long.
* Use 'ContextVars' style in sphinx doc
---------
Co-authored-by: Stephen Rosen <sirosen@globus.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
docs: Clarify docs for error case of `PyDict_GetItemRef` (GH-149506)
(cherry picked from commit 3565d31690)
Co-authored-by: Nathan Goldbaum <nathan.goldbaum@gmail.com>
gh-144693: Clarify that `PyFrame_GetBack` does not raise exceptions (GH-144824)
(cherry picked from commit 8775f90017)
Co-authored-by: Taegyun Kim <k.taegyun@gmail.com>
Co-authored-by: Sergey Miryanov <sergey.miryanov@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* gh-144748: Document 3.12 and 3.14 changes to `PyErr_CheckSignals` (GH-144982)
(cherry picked from commit 06292614ff)
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
gh-141004: Mark up constants for `PyOS_double_to_string` (GH-143867)
This ensures they show up as C macros in search and the Sphinx inventory.
(cherry picked from commit fb690c38ca)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
gh-141004: Mark up docs of old PyMem macros (GH-143783)
These had a docs-only deprecation notice since the first version of the docs in this repo. Nowadays we call things “soft deprecated” if there's just a note in the docs.
The deprecated directive needs a version, I went with the first one that had the notice (2.0; it's not in 1.6):
- https://docs.python.org/release/2.0/api/memoryInterface.html
- https://docs.python.org/release/1.6/api/memoryInterface.html
Since PEP 445, they are now direct aliases; there are no (additional) binary compatibility concerns over the preferred names.
(cherry picked from commit a009e78b79)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
For vectorcall API, the underscore-prefixed provisional names
continue to be available per PEP 590:
https://peps.python.org/pep-0590/#finalizing-the-api
Use `versionadded`, `versionchanged`, and `:no-typesetting:`
to mark this up.
For PyCode API, use `:no-typesetting:` rather than `index::` so that
these are semantically documented as C functions.
(cherry picked from commit 7e8a1b5061)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
gh-141004: Document descriptor and dict proxy type objects (GH-141803)
(cherry picked from commit 52f9b5f580)
Co-authored-by: Yashraj <yashrajpala8@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
gh-141004: Document stack effect C APIs (GH-141843)
(cherry picked from commit e1f1df4082)
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
gh-141004: Document `Py_LOCAL` and `Py_LOCAL_INLINE` (GH-141725)
(cherry picked from commit 3149d64c93)
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
(cherry picked from commit 630cd37bfa)
Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
gh-141004: Document the `PyPickleBuffer_*` C API (GH-141630)
(cherry picked from commit e33afa7ddb)
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
gh-141004: Document C APIs for dictionary keys, values, and items (GH-141009)
(cherry picked from commit f72768f30e)
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
gh-141004: Document `PyFile_OpenCode` and `PyFile_OpenCodeObject` (GH-141413)
(cherry picked from commit 2befce86e6)
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
