Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9c9f673

Browse files
serhiy-storchakaserhiy-storchaka
committed
Merge remote-tracking branch 'upstream/main' into gh-61290-default-namespace-attrs
# Conflicts: # Lib/test/test_xml_etree.py
2 parents c250651 + ad447fa commit 9c9f673

469 files changed

Lines changed: 13697 additions & 4043 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../AGENTS.md

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -630,7 +630,7 @@ Lib/test/test_unittest/testmock/ @cjw296
630630
Doc/library/zlib.rst @StanFromIreland
631631
Lib/compression/zlib.py @StanFromIreland
632632
Lib/test/test_zlib.py @StanFromIreland
633-
Modules/_zlibmodule.c @StanFromIreland
633+
Modules/zlibmodule.c @StanFromIreland
634634

635635
# Zipfile.Path
636636
Lib/test/test_zipfile/_path/ @jaraco

‎.github/workflows/reusable-docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,9 @@ jobs:
8686
--fail-if-regression \
8787
--fail-if-improved \
8888
--fail-if-new-news-nit
89+
- name: 'Build list of changes'
90+
run: |
91+
make -C Doc/ PYTHON=../python changes
8992
- name: 'Collect HTML IDs'
9093
if: github.event_name == 'pull_request'
9194
run: python Doc/tools/check-html-ids.py collect Doc/build/html -o Doc/build/html-ids-head.json.gz

‎.gitignore‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,8 +178,12 @@ Python/frozen_modules/MANIFEST
178178
/python
179179
!/Python/
180180

181-
# People's custom https://docs.anthropic.com/en/docs/claude-code/memory configs.
182-
/.claude/
181+
# Local AI agent scratch state (per-PR and per-branch notebooks, sandbox
182+
# experiments) and personal agent overrides, none of which are committed.
183+
/.claude/pr-*
184+
/.claude/branch-*
185+
/.claude/sandbox/
186+
AGENTS.local.md
183187
CLAUDE.local.md
184188

185189
#### main branch only stuff below this line, things to backport go above. ####

‎AGENTS.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# AI agent guidance
2+
3+
CPython has a [policy on the use of AI tools](https://devguide.python.org/getting-started/ai-tools/).
4+
All use of AI tools and agents when working on or interacting with CPython
5+
must follow it.
6+
7+
> [!important]
8+
> **Primary directive**: Read the policy before making or proposing any changes.
9+
10+
When acting on this repository, apply the policy's core principles:
11+
12+
- Consider whether the change is necessary.
13+
- Make minimal, focused changes.
14+
- Follow existing coding style and patterns.
15+
- Write tests that exercise the change.
16+
- Keep backwards compatibility with prior releases in mind.

Doc/library/constants.rst renamed to Doc/builtins/constants.rst

File renamed without changes.

Doc/library/exceptions.rst renamed to Doc/builtins/exceptions.rst

File renamed without changes.

Doc/library/functions.rst renamed to Doc/builtins/functions.rst

Lines changed: 78 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -65,14 +65,54 @@ are always available. They are listed here in alphabetical order.
6565

6666

6767
.. function:: aiter(async_iterable, /)
68+
aiter(callable, /, stop_value, *, stop_exception=StopAsyncIteration)
69+
aiter(callable, /, *, stop_exception)
70+
71+
Return an :term:`asynchronous iterator` object.
72+
The first argument is interpreted very differently
73+
depending on the presence of the other arguments.
74+
Without other arguments,
75+
the single argument must be an :term:`asynchronous iterable`,
76+
and the result is equivalent to calling ``x.__aiter__()``.
77+
78+
If *stop_value* or *stop_exception* is given,
79+
then the first argument must be a callable object.
80+
The asynchronous iterator created in this case
81+
calls *callable* with no arguments and awaits the result
82+
for each call to its :meth:`~object.__anext__` method;
83+
if the awaited value is equal to *stop_value*,
84+
or if the call raises an exception matching *stop_exception*,
85+
:exc:`StopAsyncIteration` will be raised,
86+
otherwise the value will be returned.
87+
The callable is only called when the result of :meth:`~object.__anext__`
88+
is awaited.
89+
90+
*stop_exception* is an exception class or a tuple of exception classes.
91+
If *stop_value* is not specified,
92+
the iteration stops only when the callable raises an exception.
93+
If the callable raises :exc:`StopAsyncIteration`
94+
which does not match *stop_exception*,
95+
it is replaced with a :exc:`RuntimeError`,
96+
as for asynchronous generators (see :pep:`525`).
97+
98+
For example, reading fixed-size chunks from an asynchronous stream
99+
until the end of file is reached::
68100

69-
Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
70-
Equivalent to calling ``x.__aiter__()``.
101+
from functools import partial
102+
async for chunk in aiter(partial(reader.read, 1024), b''):
103+
process_chunk(chunk)
104+
105+
Or consuming an :class:`asyncio.Queue` until it is shut down::
71106

72-
Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.
107+
from asyncio import QueueShutDown
108+
async for item in aiter(queue.get, stop_exception=QueueShutDown):
109+
process_item(item)
73110

74111
.. versionadded:: 3.10
75112

113+
.. versionchanged:: next
114+
Added the *stop_value* and *stop_exception* parameters.
115+
76116
.. function:: all(iterable, /)
77117

78118
Return ``True`` if all elements of the *iterable* are true (or if the iterable
@@ -89,7 +129,7 @@ are always available. They are listed here in alphabetical order.
89129
anext(async_iterator, default, /)
90130

91131
When awaited, return the next item from the given :term:`asynchronous
92-
iterator`, or *default* if given and the iterator is exhausted.
132+
iterator`, or *default* if given and the iterator is :term:`exhausted`.
93133

94134
This is the async variant of the :func:`next` builtin, and behaves
95135
similarly.
@@ -1143,22 +1183,34 @@ are always available. They are listed here in alphabetical order.
11431183

11441184

11451185
.. function:: iter(iterable, /)
1146-
iter(callable, sentinel, /)
1186+
iter(callable, /, stop_value, *, stop_exception=StopIteration)
1187+
iter(callable, /, *, stop_exception)
11471188
11481189
Return an :term:`iterator` object. The first argument is interpreted very
1149-
differently depending on the presence of the second argument. Without a
1150-
second argument, the single argument must be a collection object which supports the
1190+
differently depending on the presence of the other arguments. Without other
1191+
arguments, the single argument must be a collection object which supports the
11511192
:term:`iterable` protocol (the :meth:`~object.__iter__` method),
11521193
or it must support
11531194
the sequence protocol (the :meth:`~object.__getitem__` method with integer arguments
11541195
starting at ``0``). If it does not support either of those protocols,
1155-
:exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
1196+
:exc:`TypeError` is raised.
1197+
1198+
If *stop_value* or *stop_exception* is given,
11561199
then the first argument must be a callable object. The iterator created in this case
11571200
will call *callable* with no arguments for each call to its
11581201
:meth:`~iterator.__next__` method; if the value returned is equal to
1159-
*sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
1202+
*stop_value*, or if the call raises an exception matching *stop_exception*,
1203+
:exc:`StopIteration` will be raised, otherwise the value will
11601204
be returned.
11611205

1206+
*stop_exception* is an exception class or a tuple of exception classes.
1207+
If *stop_value* is not specified,
1208+
the iteration stops only when the callable raises an exception.
1209+
If the callable raises :exc:`StopIteration`
1210+
which does not match *stop_exception*,
1211+
it is replaced with a :exc:`RuntimeError`,
1212+
as for generators (see :pep:`479`).
1213+
11621214
See also :ref:`typeiter`.
11631215

11641216
One useful application of the second form of :func:`iter` is to build a
@@ -1170,6 +1222,19 @@ are always available. They are listed here in alphabetical order.
11701222
for block in iter(partial(f.read, 64), b''):
11711223
process_block(block)
11721224

1225+
*stop_exception* is useful for callables
1226+
which report :term:`exhaustion <exhausted>` by raising an exception
1227+
instead of returning a special value.
1228+
For example, draining a queue::
1229+
1230+
import queue
1231+
for item in iter(input_queue.get_nowait, stop_exception=queue.Empty):
1232+
process_item(item)
1233+
1234+
.. versionchanged:: next
1235+
Added the *stop_exception* parameter
1236+
and allowed passing *stop_value* by keyword.
1237+
11731238

11741239
.. function:: len(object, /)
11751240

@@ -1250,7 +1315,7 @@ are always available. They are listed here in alphabetical order.
12501315
yielding the results. If additional *iterables* arguments are passed,
12511316
*function* must take that many arguments and is applied to the items from all
12521317
iterables in parallel. With multiple iterables, the iterator stops when the
1253-
shortest iterable is exhausted. If *strict* is ``True`` and one of the
1318+
shortest iterable is :term:`exhausted`. If *strict* is ``True`` and one of the
12541319
iterables is exhausted before the others, a :exc:`ValueError` is raised. For
12551320
cases where the function inputs are already arranged into argument tuples,
12561321
see :func:`itertools.starmap`.
@@ -1332,7 +1397,7 @@ are always available. They are listed here in alphabetical order.
13321397

13331398
Retrieve the next item from the :term:`iterator` by calling its
13341399
:meth:`~iterator.__next__` method. If *default* is given, it is returned
1335-
if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
1400+
if the iterator is :term:`exhausted`, otherwise :exc:`StopIteration` is raised.
13361401

13371402

13381403
.. class:: object()
@@ -2247,7 +2312,7 @@ are always available. They are listed here in alphabetical order.
22472312
the code that prepared these iterables. Python offers three different
22482313
approaches to dealing with this issue:
22492314

2250-
* By default, :func:`zip` stops when the shortest iterable is exhausted.
2315+
* By default, :func:`zip` stops when the shortest iterable is :term:`exhausted`.
22512316
It will ignore the remaining items in the longer iterables, cutting off
22522317
the result to the length of the shortest iterable::
22532318

@@ -2262,7 +2327,7 @@ are always available. They are listed here in alphabetical order.
22622327
[('a', 1), ('b', 2), ('c', 3)]
22632328

22642329
Unlike the default behavior, it raises a :exc:`ValueError` if one iterable
2265-
is exhausted before the others:
2330+
is :term:`exhausted` before the others:
22662331

22672332
>>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True): # doctest: +SKIP
22682333
... print(item)

‎Doc/builtins/index.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _builtins-index:
2+
3+
##############################
4+
Python built-ins reference
5+
##############################
6+
7+
Python comes with a number of built-in functions and classes.
8+
9+
The built-in classes include data types that would normally be considered part
10+
of the "core" of a language, such as numbers and lists. For these types, the
11+
Python language core defines the form of literals and places some constraints
12+
on their semantics, but does not fully define the semantics.
13+
14+
The built-ins also include functions and exceptions --- objects that can
15+
be used by all Python code without the need of an :keyword:`import` statement.
16+
Some of these are defined by the core language, but many are not essential for
17+
the core semantics and are only described here.
18+
19+
.. seealso::
20+
21+
In addition to the built-ins, Python provides an extensive importable
22+
standard library, see :ref:`library-index`.
23+
24+
.. We don't use :numbered: option for the TOC below as it enforces
25+
numbered sections for the entire builtin docs. If desired,
26+
:numbered: can be enabled on a per-page basis.
27+
.. toctree::
28+
:maxdepth: 2
29+
30+
stdtypes.rst
31+
constants.rst
32+
functions.rst
33+
exceptions.rst
34+
threadsafety.rst
35+
time-complexity.rst

0 commit comments

Comments
 (0)