gh-150319: Replace all documentation which says "See PEP 585" (GH-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
---------
(cherry picked from commit 50fe49c879)
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: Alex Waygood <66076021+AlexWaygood@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
- Mention (again) that `type.__annotations__` is unsafe. It is now safe
when using only classes defined under PEP 649 semantics, but not with
classes defined using `from __future__ import annotations`.
- Mention that annotations on instances no longer work. There was already
an issue about this.
- Mention the general changes in the "Porting to Python 3.14" section.
- `annotationlib` was proposed by PEP-749, not PEP-649.
Co-authored-by: Emma Smith <emma@emmatyping.dev>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
As noted on the issue, making get_annotate_function() support both types and
mappings is problematic because one object may be both. So let's add a new one
that works with any mapping.
This leaves get_annotate_function() not very useful, so remove it.
* add test for the predefined object's attributes
* Include the "object" type in the lists of documented types
* remove 'or' from augment tuple
* 📜🤖 Added by blurb_it.
* Add cross-reference to news
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* Fix format for the function parameter
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* Add space
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* add reference for the 'object'
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* add reference for NotImplemented
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* Change ref:`string <textseq>` as class:`str`
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* remove hyphen from `newly-created`
* Update Doc/reference/datamodel.rst
'dictionaries' to 'dict'
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
* Update predefined attribute types in testPredefinedAttrs
* Change `universal type` as `top type`
* Don't mention about the top type
* Update the description of richcmpfuncs
* Update Doc/library/stdtypes.rst
Co-authored-by: Éric <merwok@netwok.org>
* Revert: Hierarchy Section in Data Model Documentation
* Revert to original explanations of __new__ and __init__ methods in datamodel.rst for improved clarity.
* Update Doc/reference/datamodel.rst
Co-authored-by: Éric <merwok@netwok.org>
* Remove blank line
Co-authored-by: Éric <merwok@netwok.org>
* Use ref:`str <textseq>` instead of :class:`str
Co-authored-by: Éric <merwok@netwok.org>
* Revert changes the description of Other Built-in Types in stdtypes.rst
* Update Doc/reference/datamodel.rst
Co-authored-by: Éric <merwok@netwok.org>
---------
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* Qualifying that the right operand's type must be a *strict* subclass for the reflected method to take precedence avoids an edge case / counter-example when the types are actually equal.
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Barry Warsaw <barry@python.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
The term "free variable" has unfortunately become genuinely
ambiguous over the years (presumably due to the names of
some relevant code object instance attributes).
While we can't eliminate that ambiguity at this late date, we can
at least alert people to the potential ambiguity by describing
both the formal meaning of the term and the common
alternative use as a direct synonym for "closure variable".
---------
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* Setting the __module__ attribute for a class now removes the
__firstlineno__ item from the type's dict.
* The _collections_abc and _pydecimal modules now completely replace the
collections.abc and decimal modules after importing them. This
allows to get the source of classes and functions defined in these
modules.
* inspect.findsource() now checks whether the first line number for a
class is out of bound.
Using a standard library class makes this test difficult to maintain
as other tests and other parts of the stdlib may create subclasses,
which may still be alive when this test runs depending on GC timing.
Closes#123242. The real criterion is that the attribute does not
exist on heap types, but I don't think we should discuss heap vs.
static types in the language reference.
* gh-124370: Add "howto" for free-threaded Python
This is a guide aimed at people writing Python code, as oppposed to the
existing guide for C API extension authors.
* Add missing new line
* Update Doc/howto/free-threading-python.rst
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* interned -> immortalized
* Apply suggestions from code review
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* Update Doc/howto/free-threading-python.rst
Co-authored-by: mpage <mpage@cs.stanford.edu>
* Update docs
* Apply suggestions from code review
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* A few more updates
* Additional comment on immortal objects
* Mention specializing adaptive interpreter
* Remove trailing whitespace
* Remove mention of C macro
---------
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: mpage <mpage@cs.stanford.edu>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
