summaryrefslogtreecommitdiffstats
path: root/Doc/reference
Commit message (Collapse)AuthorAgeFilesLines
* [3.14] gh-135110: Fix misleading `generator.close()` documentation ↵Miss Islington (bot)2025-06-261-2/+4
| | | | | | | | | | | | | (GH-135152) (GH-135985) 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>
* [3.14] Docs: Add cross-reference for `positional_item` in the `calls` ↵Miss Islington (bot)2025-06-251-1/+1
| | | | | | | | | | productionlist (GH-129977) (GH-135940) 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>
* [3.14] gh-135676: lexical analysis: Improve section on Numeric literals ↵Miss Islington (bot)2025-06-183-55/+168
| | | | | | | | (GH-134850) (GH-135677) gh-135676: lexical analysis: Improve section on Numeric literals (GH-134850) (cherry picked from commit 21f3d15534c08d9a49d5c119a0e690855173fde4) Co-authored-by: Petr Viktorin <encukou@gmail.com>
* [3.14] gh-135171: Update documentation for the generator expression ↵Miss Islington (bot)2025-06-151-2/+3
| | | | | | | | | | | | | | | | | | | | (GH-135351) (#135524) 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>
* [3.14] gh-127833: Reword and expand the Notation section (GH-134443) (GH-135301)Miss Islington (bot)2025-06-092-50/+128
| | | | | | | | | | | | | | | | | Prepare the docs for using the notation used in the `python.gram` file. If we want to sync the two, the meta-syntax should be the same. Link the Full Grammar docs here; keep only a few extras. Also, remove the distinction between lexical and syntactic rules, except for whitespace handling. With f- and t-strings, the line between the two is blurry. (cherry picked from commit 28d91d06f13ceda3df0cefacec497c370eff4802) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com> Co-authored-by: Colin Marquardt <cmarqu42@gmail.com>
* [3.14] gh-134675: Add t-string prefixes to tokenizer module, lexical ↵Miss Islington (bot)2025-05-261-1/+2
| | | | | | | | | | | | analysis doc, and add a test to make sure we catch this error in the future. (GH-134734) (#134739) gh-134675: Add t-string prefixes to tokenizer module, lexical analysis doc, and add a test to make sure we catch this error in the future. (GH-134734) * Add t-string prefixes to _all_string_prefixes, and add a test to make sure we catch this error in the future. * Update lexical analysis docs for t-string prefixes. (cherry picked from commit 08c78e02fab4a1c9c075637422d621f9c740959a) Co-authored-by: Eric V. Smith <ericvsmith@users.noreply.github.com>
* [3.14] gh-119180: Updates to PEP 649/749 docs (GH-134640) (#134731)Miss Islington (bot)2025-05-261-1/+13
| | | | | | | | | | | | | | | | gh-119180: Updates to PEP 649/749 docs (GH-134640) - 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. (cherry picked from commit 7291eaba8b20b19e7971d43d88286d5820e5eb56) Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Emma Smith <emma@emmatyping.dev> Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* [3.14] gh-127833: lexical analysis: Improve section on Names (GH-131474) ↵Miss Islington (bot)2025-05-261-52/+76
| | | | | | | | (#134423) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Blaise Pabon <blaise@gmail.com>
* [3.14] gh-134026: Fix grammar description of for statement (GH-134034) ↵Miss Islington (bot)2025-05-212-8/+8
| | | | | | | | (GH-134424) gh-134026: Fix grammar description of for statement (GH-134034) (cherry picked from commit 4eacf3883dd041c31133ea407204b797a17559b1) Co-authored-by: Yash Vijay <yash_vijay@outlook.com>
* [3.14] gh-119180: More documentation for PEP 649/749 (GH-133552) (#133902)Miss Islington (bot)2025-05-111-1/+7
| | | | | | | | | gh-119180: More documentation for PEP 649/749 (GH-133552) The SC asked that the Appendix in PEP-749 be added to the docs. (cherry picked from commit 3396df56d0849e5154cb7d7d1c525df834bbe15e) Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* [3.14] gh-127833: Add links to token types to the lexical analysis intro ↵Miss Islington (bot)2025-05-081-23/+39
| | | | | | | | | (GH-131468) (#133652) gh-127833: Add links to token types to the lexical analysis intro (GH-131468) (cherry picked from commit 45bb5ba61a8d6dcaa44312b67fe6bade5e2ad992) Co-authored-by: Petr Viktorin <encukou@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* [3.14] gh-127833: lexical analysis: Add backticks to BOM example (GH-132407) ↵Miss Islington (bot)2025-05-081-1/+1
| | | | | | | | (#133632) 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>
* Python 3.14.0b1v3.14.0b1Hugo van Kemenade2025-05-061-1/+1
|
* gh-132426: Add get_annotate_from_class_namespace replacing ↵Jelle Zijlstra2025-05-041-16/+3
| | | | | | | | | | get_annotate_function (#132490) 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.
* doc: update co_flags reference (#132300)Inada Naoki2025-04-241-5/+4
| | | | Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* gh-130104: Call __rpow__ in ternary pow() if necessary (GH-130251)Serhiy Storchaka2025-04-161-4/+9
| | | | | Previously it was only called in binary pow() and the binary power operator.
* Python 3.14.0a7v3.14.0a7Hugo van Kemenade2025-04-081-2/+2
|
* gh-131831: Implement PEP 758 – Allow except and except* expressions ↵Pablo Galindo Salgado2025-04-011-1/+4
| | | | without parentheses (#131833)
* gh-131457: Fix typo in BNF description of function signatures (#131460)Srinivas Reddy Thatiparthy (తాటిపర్తి శ్రీనివాస్ రెడ్డి)2025-03-221-1/+1
|
* gh-130587: Add hand-written docs for non-OP tokens (GH-130588)Petr Viktorin2025-03-191-4/+6
| | | | | Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Lysandros Nikolaou <lisandrosnik@gmail.com>
* gh-130080: implement PEP 765 (#130087)Irit Katriel2025-03-171-18/+22
|
* gh-116666: Add "token" glossary term (GH-130888)Petr Viktorin2025-03-171-2/+3
| | | | | | | | | 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.) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
* gh-121970: Replace `.. coroutine{method,function}` with `:async:` (#130448)sobolevn2025-02-221-5/+9
| | | Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
* Doc: update term "namespace package" (#129251)Inada Naoki2025-02-141-0/+2
|
* gh-127833: Docs: Add a `grammar-snippet` directive & replace ↵Petr Viktorin2025-02-051-2/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | `productionlist` (GH-127835) As a first step toward aligning the grammar documentation with Python's actual grammar, this overrides the ReST `productionlist` directive to: - use `:` instead of the `::=` symbol - add syntax highlighting for strings (using a Pygments highlighting class) All links and link targets should be preserved. (Unfortunately, this reaches into some Sphinx internals; I don't see a better way to do exactly what Sphinx does.) This also adds a new directive, `grammar-snippet`, which formats the snippet almost exactly like what's in the source, modulo syntax highlighting and keeping the backtick character to mark links to other rules. This will allow formatting the snippets as in the grammar file (file:///home/encukou/dev/cpython/Doc/build/html/reference/grammar.html). The new directive is applied to two simple rules in toplevel_components.rst --------- Co-authored-by: Blaise Pabon <blaise@gmail.com> Co-authored-by: William Ferreira <wqferr@gmail.com> Co-authored-by: bswck <bartoszpiotrslawecki@gmail.com> Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
* gh-115911: Ignore PermissionError during import from cwd (#116131)Alex Willmer2025-01-261-4/+4
| | | | | | | | | | | | | | | | Ignore PermissionError when checking cwd during import On macOS `getcwd(3)` can return EACCES if a path component isn't readable, resulting in PermissionError. `PathFinder.find_spec()` now catches these and ignores them - the same treatment as a missing/deleted cwd. Introduces `test.support.os_helper.save_mode(path, ...)`, a context manager that restores the mode of a path on exit. This is allows finer control of exception handling and robust environment restoration across platforms in `FinderTests.test_permission_error_cwd()`. Co-authored-by: Jason R. Coombs <jaraco@jaraco.com> Co-authored-by: Brett Cannon <brett@python.org>
* gh-122845: fix parameter_list_starargs in function definition pseudo-grammar ↵Sergey B Kirpichev2025-01-211-2/+4
| | | | | | (#122847) Thanks to Artur Chakhvadze for bugfix.
* gh-126664: revert: Use `else` instead of `finally` in docs explaining "with" ↵Gregory P. Smith2024-12-221-2/+5
| | | | | | | (#128169) Revert "gh-126664: Use `else` instead of `finally` in "The with statement" documentation. (GH-126665)" This reverts commit 25257d61cfccc3b4189f96390a5c4db73fd5302c.
* gh-69639: Add mixed-mode rules for complex arithmetic (C-like) (GH-124829)Sergey B Kirpichev2024-11-261-7/+18
| | | | | | | | | | | | | | | "Generally, mixed-mode arithmetic combining real and complex variables should be performed directly, not by first coercing the real to complex, lest the sign of zero be rendered uninformative; the same goes for combinations of pure imaginary quantities with complex variables." (c) Kahan, W: Branch cuts for complex elementary functions. This patch implements mixed-mode arithmetic rules, combining real and complex variables as specified by C standards since C99 (in particular, there is no special version for the true division with real lhs operand). Most C compilers implementing C99+ Annex G have only these special rules (without support for imaginary type, which is going to be deprecated in C2y).
* Docs: Miscellaneous corrections to simple statements in the language ↵Beomsoo Kim2024-11-151-8/+8
| | | | | | | | reference (GH-126720) * Replace: The :keyword:`global` -> The :keyword:`global` statement Add :keyword: when it's needed * Replace repeated links with duoble backticks
* Document that return-less user-defined functions return None (#126769)John Marshall2024-11-141-1/+2
| | | | Co-authored-by: Andrew Svetlov <andrew.svetlov@gmail.com> Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* gh-58749: Remove incorrect language spec claims about the global statement ↵Beomsoo Kim2024-11-121-16/+5
| | | | | | | | (GH-126523) * Removes erroneous explanation of the `global` statement restrictions; a name declared as global can be subsequently bound using any kind of name binding operation. * Updates `test_global.py` to also test various name-binding scenarios for global variables to ensure correct behavior
* gh-126664: Use `else` instead of `finally` in "The with statement" ↵vivodi2024-11-111-5/+2
| | | | documentation. (GH-126665)
* Postpone `module.__loader__` deprecation to Python 3.16 (#126482)Hugo van Kemenade2024-11-101-2/+2
|
* gh-101865: Docs: Keep co_lnotab deprecation for at least 3.14 (#126392)Hugo van Kemenade2024-11-041-1/+1
|
* gh-60712: Include the "object" type in the lists of documented types (GH-103036)Furkan Onder2024-10-301-15/+37
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * 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>
* gh-126072: do not add `None` to `co_consts` if there is no docstring (GH-126101)Xuanteng Huang2024-10-301-3/+3
|
* bpo-41793: Fix an inaccuracy about reflected methods in datamodel docs ↵Wim Jeantine-Glenn2024-10-291-11/+14
| | | | | | | (GH-22257) * 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>
* gh-125461: Remove Python 2 from identifiers in doc (GH-125462)Paul Hoffman2024-10-141-3/+2
| | | Remove Python 2 from identifiers in doc
* gh-101100: Consolidate documentation on `ModuleType` attributes (#124709)Alex Waygood2024-10-092-177/+248
| | | | | | 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>
* gh-70870: Clarify dual usage of 'free variable' (#122545)Alyssa Coghlan2024-10-082-5/+13
| | | | | | | | | | | | | | 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>
* gh-125072: Add label for assignment expressions; update tracked section for ↵Emily Morehouse2024-10-071-0/+2
| | | | assignment expression topic (#125074)
* gh-123339: Fix cases of inconsistency of __module__ and __firstlineno__ in ↵Serhiy Storchaka2024-09-281-1/+4
| | | | | | | | | | | | | classes (GH-123613) * 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.
* gh-81263: Add assignment expressions to `help` (#124641)Emily Morehouse2024-09-271-0/+1
| | | | | * Add assignment expression (:=) to `help` * Update index for Assignment Expressions to include pair of `assignment; expression`
* gh-115528: Update language reference for PEP 646 (#121181)Matthew Rahtz2024-09-262-17/+32
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | To recap: the objective is to make starred expressions valid in `subscription`, which is used for generics: `Generic[...]`, `list[...]`, etc. What _is_ gramatically valid in such contexts? Seemingly any of the following. (At least, none of the following throw `SyntaxError` in a 3.12.3 REPL.) Generic[x] Generic[*x] Generic[*x, y] Generic[y, *x] Generic[x := 1] Generic[x := 1, y := 2] So introducting flexible_expression: expression | assignment_expression | starred_item end then switching `subscription` to use `flexible_expression` sorts that. But then we need to field `yield` - for which any of the following are apparently valid: yield x yield x, yield x, y yield *x, yield *x, *y Introducing a separate `yield_list` is the simplest way I've been figure out to do this - separating out the special case of `starred_item ,`. Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* gh-101100: Make __subclasses__ doctest stable (#124577)Jelle Zijlstra2024-09-261-2/+4
| | | | | 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.
* gh-123242: Note that type.__annotations__ may not exist (#124557)Jelle Zijlstra2024-09-251-1/+2
| | | | | 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 (#124371)Sam Gross2024-09-251-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * 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>
* gh-101100: Add a table of class attributes to the "Custom classes" section ↵Alex Waygood2024-09-254-66/+129
| | | | of the data model docs (#124480)
* import: permit __name__ for use in __name__ = "__main__": (#124381)Thomas Grainger2024-09-251-1/+1
| | | permit __name__ for use in __name__ = "__main__":
generated by cgit v0.12 at 2026-01-14 19:46:58 (GMT)