8000 Merge branch 'main' of https://github.com/python/cpython into fix-asy… · python/cpython@6afa6df · GitHub
[go: up one dir, main page]
Skip to content

Commit 6afa6df

Browse files
kumaraditya303kumaraditya303
authored
Merge branch 'main' of https://github.com/python/cpython into fix-asyncio-subprocess
2 parents 2bd08cf + 850687d commit 6afa6df

File tree

85 files changed

+3525
-25752
lines changed

Some content is hidden

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

85 files changed

+3525
-25752
lines changed

‎.github/ISSUE_TEMPLATE/config.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: ⚠ GitHub Issues Migration in progress ⚠
4+
url: https://discuss.python.org/t/github-issues-migration-status-update/14573
5+
about: Check status updates on the migration

‎.github/workflows/posix-deps-apt.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ apt-get -yq install \
77
ccache \
88
gdb \
99
lcov \
10+
libb2-dev \
1011
libbz2-dev \
1112
libffi-dev \
1213
libgdbm-dev \

‎Doc/c-api/frame.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,17 @@ See also :ref:`Reflection <reflection>`.
4141
.. versionadded:: 3.9
4242
4343
44+
.. c:function:: PyObject* PyFrame_GetLocals(PyFrameObject *frame)
45+
46+
Get the *frame*'s ``f_locals`` attribute (:class:`dict`).
47+
48+
Return a :term:`strong reference`.
49+
50+
*frame* must not be ``NULL``.
51+
52+
.. versionadded:: 3.11
53+
54+
4455
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
4556
4657
Return the line number that *frame* is currently executing.

‎Doc/library/asyncio-api-index.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,11 +186,16 @@ Threading-like synchronization primitives that can be used in Tasks.
186186
* - :class:`BoundedSemaphore`
187187
- A bounded semaphore.
188188

189+
* - :class:`Barrier`
190+
- A barrier object.
191+
189192

190193
.. rubric:: Examples
191194

192195
* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
193196

197+
* :ref:`Using asyncio.Barrier <asyncio_example_barrier>`.
198+
194199
* See also the documentation of asyncio
195200
:ref:`synchronization primitives <asyncio-sync>`.
196201

@@ -206,6 +211,9 @@ Exceptions
206211
* - :exc:`asyncio.CancelledError`
207212
- Raised when a Task is cancelled. See also :meth:`Task.cancel`.
208213

214+
* - :exc:`asyncio.BrokenBarrierError`
215+
- Raised when a Barrier is broken. See also :meth:`Barrier.wait`.
216+
209217

210218
.. rubric:: Examples
211219

‎Doc/library/asyncio-runner.rst

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
.. currentmodule:: asyncio
2+
3+
4+
=======
5+
Runners
6+
=======
7+
8+
**Source code:** :source:`Lib/asyncio/runners.py`
9+
10+
11+
This section outlines high-level asyncio primitives to run asyncio code.
12+
13+
They are built on top of an :ref:`event loop <asyncio-event-loop>` with the aim
14+
to simplify async code usage for common wide-spread scenarios.
15+
16+
.. contents::
17+
:depth: 1
18+
:local:
19+
20+
21+
22+
Running an asyncio Program
23+
==========================
24+
25+
.. function:: run(coro, *, debug=None)
26+
27+
Execute the :term:`coroutine` *coro* and return the result.
28+
29+
This function runs the passed coroutine, taking care of
30+
managing the asyncio event loop, *finalizing asynchronous
31+
generators*, and closing the threadpool.
32+
33+
This function cannot be called when another asyncio event loop is
34+
running in the same thread.
35+
36+
If *debug* is ``True``, the event loop will be run in debug mode. ``False`` disables
37+
debug mode explicitly. ``None`` is used to respect the global
38+
:ref:`asyncio-debug-mode` settings.
39+
40+
This function always creates a new event loop and closes it at
41+
the end. It should be used as a main entry point for asyncio
42+
programs, and should ideally only be called once.
43+
44+
Example::
45+
46+
async def main():
47+
await asyncio.sleep(1)
48+
print('hello')
49+
50+
asyncio.run(main())
51+
52+
.. versionadded:: 3.7
53+
54+
.. versionchanged:: 3.9
55+
Updated to use :meth:`loop.shutdown_default_executor`.
56+
57+
.. versionchanged:: 3.10
58+
59+
*debug* is ``None`` by default to respect the global debug mode settings.
60+
61+
62+
Runner context manager
63+
======================
64+
65+
.. class:: Runner(*, debug=None, loop_factory=None)
66+
67+
A context manager that simplifies *multiple* async function calls in the same
68+
context.
69+
70+
Sometimes several top-level async functions should be called in the same :ref:`event
71+
loop <asyncio-event-loop>` and :class:`contextvars.Context`.
72+
73+
If *debug* is ``True``, the event loop will be run in debug mode. ``False`` disables
74+
debug mode explicitly. ``None`` is used to respect the global
75+
:ref:`asyncio-debug-mode` settings.
76+
77+
*loop_factory* could be used for overriding the loop creation.
78+
:func:`asyncio.new_event_loop` is used if ``None``.
79+
80+
Basically, :func:`asyncio.run()` example can be rewritten with the runner usage::
81+
82+
async def main():
83+
await asyncio.sleep(1)
84+
print('hello')
85+
86+
with asyncio.Runner() as runner:
87+
runner.run(main())
88+
89+
.. versionadded:: 3.11
90+
91+
.. method:: run(coro, *, context=None)
92+
93+
Run a :term:`coroutine <coroutine>` *coro* in the embedded loop.
94+
95+
Return the coroutine's result or raise its exception.
96+
97+
An optional keyword-only *context* argument allows specifying a
98+
custom :class:`contextvars.Context` for the *coro* to run in.
99+
The runner's default context is used if ``None``.
100+
101+
This function cannot be called when another asyncio event loop is
102+
running in the same thread.
103+
104+
.. method:: close()
105+
106+
Close the runner.
107+
108+
Finalize asynchronous generators, shutdown default executor, close the event loop
109+
and release embedded :class:`contextvars.Context`.
110+
111+
.. method:: get_loop()
112+
113+
Return the event loop associated with the runner instance.
114+
115+
.. note::
116+
117+
:class:`Runner` uses the lazy initialization strategy, its constructor doesn't
118+
initialize underlying low-level structures.
119+
120+
Embedded *loop* and *context* are created at the :keyword:`with` body entering
121+
or the first call of :meth:`run` or :meth:`get_loop`.

‎Doc/library/asyncio-sync.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ asyncio has the following basic synchronization primitives:
2828
* :class:`Condition`
2929
* :class:`Semaphore`
3030
* :class:`BoundedSemaphore`
31+
* :class:`Barrier`
3132

3233

3334
---------
@@ -340,6 +341,115 @@ BoundedSemaphore
340341
.. versionchanged:: 3.10
341342
Removed the *loop* parameter.
342343

344+
345+
Barrier
346+
=======
347+
348+
.. class:: Barrier(parties, action=None)
349+
350+
A barrier object. Not thread-safe.
351+
352+
A barrier is a simple synchronization primitive that allows to block until
353+
*parties* number of tasks are waiting on it.
354+
Tasks can wait on the :meth:`~Barrier.wait` method and would be blocked until
355+
the specified number of tasks end up waiting on :meth:`~Barrier.wait`.
356+
At that point all of the waiting tasks would unblock simultaneously.
357+
358+
:keyword:`async with` can be used as an alternative to awaiting on
359+
:meth:`~Barrier.wait`.
360+
361+
The barrier can be reused any number of times.
362+
363+
.. _asyncio_example_barrier:
364+
365+
Example::
366+
367+
async def example_barrier():
368+
# barrier with 3 parties
369+
b = asyncio.Barrier(3)
370+
371+
# create 2 new waiting tasks
372+
asyncio.create_task(b.wait())
373+
asyncio.create_task(b.wait())
374+
375+
await asyncio.sleep(0)
376+
print(b)
377+
378+
# The third .wait() call passes the barrier
379+
await b.wait()
380+
print(b)
381+
print("barrier passed")
382+
383+
await asyncio.sleep(0)
384+
print(b)
385+
386+
asyncio.run(example_barrier())
387+
388+
Result of this example is::
389+
390+
<asyncio.locks.Barrier object at 0x... [filling, waiters:2/3]>
391+
<asyncio.locks.Barrier object at 0x... [draining, waiters:0/3]>
392+
barrier passed
393+
<asyncio.locks.Barrier object at 0x... [filling, waiters:0/3]>
394+
395+
.. versionadded:: 3.11
396+
397+
.. coroutinemethod:: wait()
398+
399+
Pass the barrier. When all the tasks party to the barrier have called
400+
this function, they are all unblocked simultaneously.
401+
402+
When a waiting or blocked task in the barrier is cancelled,
403+
this task exits the barrier which stays in the same state.
404+
If the state of the barrier is "filling", the number of waiting task
405+
decreases by 1.
406+
407+
The return value is an integer in the range of 0 to ``parties-1``, different
408+
for each task. This can be used to select a task to do some special
409+
housekeeping, e.g.::
410+
411+
...
412+
async with barrier as position:
413+
if position == 0:
414+
# Only one task print this
415+
print('End of *draining phasis*')
416+
417+
This method may raise a :class:`BrokenBarrierError` exception if the
418+
barrier is broken or reset while a task is waiting.
419+
It could raise a :exc:`CancelledError` if a task is cancelled.
420+
421+
.. coroutinemethod:: reset()
422+
423+
Return the barrier to the default, empty state. Any tasks waiting on it
424+
will receive the :class:`BrokenBarrierError` exception.
425+
426+
If a barrier is broken it may be better to just leave it and create a new one.
427+
428+
.. coroutinemethod:: abort()
429+
430+
Put the barrier into a broken state. This causes any active or future
431+
calls to :meth:`wait` to fail with the :class:`BrokenBarrierError`.
432+
Use this for example if one of the taks needs to abort, to avoid infinite
433+
waiting tasks.
434+
435+
.. attribute:: parties
436+
437+
The number of tasks required to pass the barrier.
438+
439+
.. attribute:: n_waiting
440+
441+
The number of tasks currently waiting in the barrier while filling.
442+
443+
.. attribute:: broken
444+
445+
A boolean that is ``True`` if the barrier is in the broken state.
446+
447+
448+
.. exception:: BrokenBarrierError
449+
450+
This exception, a subclass of :exc:`RuntimeError`, is raised when the
451+
:class:`Barrier` object is reset or broken.
452+
343453
---------
344454

345455

‎Doc/library/asyncio-task.rst

Lines changed: 0 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -204,43 +204,6 @@ A good example of a low-level function that returns a Future object
204204
is :meth:`loop.run_in_executor`.
205205

206206

207-
Running an asyncio Program
208-
==========================
209-
210-
.. function:: run(coro, *, debug=False)
211-
212-
Execute the :term:`coroutine` *coro* and return the result.
213-
214-
This function runs the passed coroutine, taking care of
215-
managing the asyncio event loop, *finalizing asynchronous
216-
generators*, and closing the threadpool.
217-
218-
This function cannot be called when another asyncio event loop is
219-
running in the same thread.
220-
221-
If *debug* is ``True``, the event loop will be run in debug mode.
222-
223-
This function always creates a new event loop and closes it at
224-
the end. It should be used as a main entry point for asyncio
225-
programs, and should ideally only be called once.
226-
227-
Example::
228-
229-
async def main():
230-
await asyncio.sleep(1)
231-
print('hello')
232-
233-
asyncio.run(main())
234-
235-
.. versionadded:: 3.7
236-
237-
.. versionchanged:: 3.9
238-
Updated to use :meth:`loop.shutdown_default_executor`.
239-
240-
.. note::
241-
The source code for ``asyncio.run()`` can be found in
242-
:source:`Lib/asyncio/runners.py`.
243-
244207
Creating Tasks
245208
==============
246209

‎Doc/library/asyncio.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ Additionally, there are **low-level** APIs for
6767
:caption: High-level APIs
6868
:maxdepth: 1
6969

70+
asyncio-runner.rst
7071
asyncio-task.rst
7172
asyncio-stream.rst
7273
asyncio-sync.rst

‎Doc/library/contextlib.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -502,6 +502,9 @@ Functions and classes provided:
502502
# the with statement, even if attempts to open files later
503503
# in the list raise an exception
504504

505+
The :meth:`__enter__` method returns the :class:`ExitStack` instance, and
506+
performs no additional operations.
507+
505508
Each instance maintains a stack of registered callbacks that are called in
506509
reverse order when the instance is closed (either explicitly or implicitly
507510
at the end of a :keyword:`with` statement). Note that callbacks are *not*

‎Doc/library/ctypes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2512,7 +2512,7 @@ Arrays and pointers
25122512
Abstract base class for arrays.
25132513

25142514
The recommended way to create concrete array types is by multiplying any
2515-
:mod:`ctypes` data type with a positive integer. Alternatively, you can subclass
2515+
:mod:`ctypes` data type with a non-negative integer. Alternatively, you can subclass
25162516
this type and define :attr:`_length_` and :attr:`_type_` class variables.
25172517
Array elements can be read and written using standard
25182518
subscript and slice accesses; for slice reads, the resulting object is

‎Doc/library/grp.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Unix versions.
1212

1313
Group database entries are reported as a tuple-like object, whose attributes
1414
correspond to the members of the ``group`` structure (Attribute field below, see
15-
``<pwd.h>``):
15+
``<grp.h>``):
1616

1717
+-------+-----------+---------------------------------+
1818
| Index | Attribute | Meaning |

‎Doc/library/random.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@ Functions for sequences
257257
.. versionchanged:: 3.11
258258

259259
The *population* must be a sequence. Automatic conversion of sets
260-
to lists is longer supported.
260+
to lists is no longer supported.
261261

262262

263263
.. _real-valued-distributions:

0 commit comments

Comments
 (0)
0