* [3.13] Docs: split builtins to their own page from library (GH-156682)
* Docs: split builtins to their own page from library
* review feedback
* addressed Hugo's feedback
* update the What's Next page
* one more wording tweak
* move builtins to their own directory. fix the reference name
* moved pages need to be noted in tools/removed-ids.txt
* add Python to the builtins reference title
* add sphinxext-rediraffe for the library->builtins split
* update check-html-ids to handle rediraffe redirects
* now we don't need (page missing) for the redirected pages
* update other references to moved pages
* A seealso from builtins to library
* make a nice section for rediraffe settings
* move the builtins note to the end, as a seealso
* address merwok's comments
* cache looking for ids in files
* simplify the intro paragraphs
(cherry picked from commit 59c4bddb1762b4706c942d6403fb8df470f37e05)
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
* remove references to non-existent pages
(cherry picked from commit 856049a9d99119ad74cd991fa8f8a72ebc909122)
Co-authored-by: Jonathan Dung <jonathandung@yahoo.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
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>
Link to existing rules in compound_stmts.rst (GH-149811)
In gh-138418, `!` was added to links to rules that don't exist in
the docs, in order to silence broken link warnings.
However, productionlist doesn't parse the `!`, which ends up in
the rendered documentation. (It's possible that gh-127835 broke
the `!` support.)
Replace the names with ones that appear in docs:
- `star_named_expression` in the grammar corresponds to
`flexible_expression` in the docs
- `star_named_expressions` in the grammar corresponds to
`flexible_expression_list` in the docs
- `named_expression` in the grammar corresponds to
`assignment_expression` in the docs
Having two sets of names isn't great of course. Consolidating them
is tracked in (subissues of) gh-127833.
(cherry picked from commit c37529293d1e05081cb4e8668162c76583b88007)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
It is not always in the local namespace.
(cherry picked from commit b8ebd078f90007d48fcab85effadb33769cd080c)
Co-authored-by: Kit Dallege <xaum.io@gmail.com>
* gh-135944: Add a "Runtime Components" Section to the Execution Model Docs (gh-135945)
The section provides a brief overview of the Python runtime's execution environment. It is meant to be implementation agnostic,
(cherry picked from commit 46a1f0a9ff6e7cbea111dcb35e7aced1a7a3f3dc)
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
* concurrent.interpreters was added to Python 3.14
---------
Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
Co-authored-by: T. Wouters <thomas@python.org>
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Victor Stinner <vstinner@python.org>
They use special method lookup for special methods.
(cherry picked from commit 9e8fa2d4d1ec263bdc6945237b0e0517f07a3474)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
gh-69686: Remove untrue part of `__import__` replacement docs (GH-143261)
Remove untrue part of `__import__` replacement docs
The original statement effectively says that replacing `__import__` at global scope affects import statements, and not only that, but only import statements within the rest of the executing module. None of that has been true since at least Python 2.7, I think.
This was likely missed in python/cpython#69686.
(cherry picked from commit 79c03ac0015ccf1cbb759f870e2af9d68f60fe3a)
Co-authored-by: Thanos <111999343+Sachaa-Thanasius@users.noreply.github.com>
(cherry picked from commit 9f05f98730bbc36f4ad173845458827c4df879f6)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
gh-135629: rewrite language reference section on except* to improve clarity (GH-136150)
(cherry picked from commit a651ec95241c25161d525499a739f01bfe527895)
Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
Co-authored-by: James Parrott <80779630+JamesParrott@users.noreply.github.com>
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
gh-135110: Fix misleading `generator.close()` documentation (GH-135152)
The documentation incorrectly stated that generator.close() 'raises' a
GeneratorExit exception. This was misleading because the method doesn't
raise the exception to the caller - it sends the exception internally
to the generator and returns None.
(cherry picked from commit 0d76dccc3b4376ba075a1737f58809e3d83aaaa3)
Co-authored-by: Connor Denihan <188690869+cdenihan@users.noreply.github.com>
Docs: Add cross-reference for `positional_item` in the `calls` productionlist (GH-129977)
Add missing hyperlink for `positional_item`
(cherry picked from commit d2154912b3b10823c138e904e74f2a1e7e7ca96c)
Co-authored-by: HarryLHW <123lhw321@gmail.com>
gh-135171: Update documentation for the generator expression (GH-135351)
* gh-135171: Update documentation for the generator expression
Document that the iterator for the leftmost "for" clause is created
immediately.
* Update Doc/reference/expressions.rst
---------
(cherry picked from commit 8979d3afe376c67931665070a79f6939ebcd940b)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Brian Skinn <brian.skinn@gmail.com>
gh-127833: lexical analysis: Add backticks to BOM example (GH-132407)
(cherry picked from commit 0552ce0fb24d33b51fdd02a589ede95aabc0d8b5)
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
gh-116666: Add "token" glossary term (GH-130888)
Add glossary entry for `token`, and link to it.
Avoid talking about tokens in the SyntaxError intro (errors.rst); at this point
tokenization is too much of a technical detail. (Even to an advanced reader,
the fact that a *single* token is highlighted isn't too relevant. Also, we don't
need to guarantee that it's a single token.)
(cherry picked from commit 30d52058493e07fd1d3efea960482f4001bd2f86)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
gh-122845: fix parameter_list_starargs in function definition pseudo-grammar (GH-122847)
Thanks to Artur Chakhvadze for bugfix.
(cherry picked from commit 610584639003317193cdcfe38bbdc8268b612828)
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
gh-126664: revert: Use `else` instead of `finally` in docs explaining "with" (GH-128169)
Revert "gh-126664: Use `else` instead of `finally` in "The with statement" documentation. (GH-126665)"
This reverts commit 25257d61cfccc3b4189f96390a5c4db73fd5302c.
(cherry picked from commit 228f275737615cc9be713a8c3f9325b359bf8aec)
Co-authored-by: Gregory P. Smith <greg@krypto.org>
Docs: Miscellaneous corrections to simple statements in the language reference (GH-126720)
* Replace: The :keyword:`global` -> The :keyword:`global` statement
Add :keyword: when it's needed
* Replace repeated links with duoble backticks
(cherry picked from commit 94a7a4e22fb8f567090514785c69e65298acca42)
Co-authored-by: Beomsoo Kim <beoms424@gmail.com>
Document that return-less user-defined functions return None (GH-126769)
(cherry picked from commit e0692f11650acb6c2eed940eb94650b4703c072e)
Co-authored-by: John Marshall <jmarshall@hey.com>
Co-authored-by: Andrew Svetlov <andrew.svetlov@gmail.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
gh-126664: Use `else` instead of `finally` in "The with statement" documentation. (GH-126665)
(cherry picked from commit 25257d61cfccc3b4189f96390a5c4db73fd5302c)
Co-authored-by: vivodi <103735539+vivodi@users.noreply.github.com>
Postpone `module.__loader__` deprecation to Python 3.16 (#126482)
(cherry picked from commit 450db61a78989c5a1f1106be01e071798c783cf9)
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
