Skip to content

Commit af27f19

Browse files
pydoc-zh-tw[bot]pydoc-zh-tw[bot]
committed
Deploy preview for PR 1123 🛫
1 parent c52589e commit af27f19

File tree

556 files changed

+4730
-4662
lines changed

Some content is hidden

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

556 files changed

+4730
-4662
lines changed

‎pr-preview/pr-1123/_sources/library/asyncio-queue.rst.txt

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -102,17 +102,33 @@ Queue
102102

103103
.. method:: shutdown(immediate=False)
104104

105-
Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
105+
Put a :class:`Queue` instance into a shutdown mode.
106+
107+
The queue can no longer grow.
108+
Future calls to :meth:`~Queue.put` raise :exc:`QueueShutDown`.
109+
Currently blocked callers of :meth:`~Queue.put` will be unblocked
110+
and will raise :exc:`QueueShutDown` in the formerly blocked thread.
111+
112+
If *immediate* is false (the default), the queue can be wound
113+
down normally with :meth:`~Queue.get` calls to extract tasks
114+
that have already been loaded.
115+
116+
And if :meth:`~Queue.task_done` is called for each remaining task, a
117+
pending :meth:`~Queue.join` will be unblocked normally.
118+
119+
Once the queue is empty, future calls to :meth:`~Queue.get` will
106120
raise :exc:`QueueShutDown`.
107121

108-
By default, :meth:`~Queue.get` on a shut down queue will only
109-
raise once the queue is empty. Set *immediate* to true to make
110-
:meth:`~Queue.get` raise immediately instead.
122+
If *immediate* is true, the queue is terminated immediately.
123+
The queue is drained to be completely empty. All callers of
124+
:meth:`~Queue.join` are unblocked regardless of the number
125+
of unfinished tasks. Blocked callers of :meth:`~Queue.get`
126+
are unblocked and will raise :exc:`QueueShutDown` because the
127+
queue is empty.
111128

112-
All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
113-
will be unblocked. If *immediate* is true, a task will be marked
114-
as done for each remaining item in the queue, which may unblock
115-
callers of :meth:`~Queue.join`.
129+
Use caution when using :meth:`~Queue.join` with *immediate* set
130+
to true. This unblocks the join even when no work has been done
131+
on the tasks, violating the usual invariant for joining a queue.
116132

117133
.. versionadded:: 3.13
118134

@@ -129,9 +145,6 @@ Queue
129145
call was received for every item that had been :meth:`~Queue.put`
130146
into the queue).
131147

132-
``shutdown(immediate=True)`` calls :meth:`task_done` for each
133-
remaining item in the queue.
134-
135148
Raises :exc:`ValueError` if called more times than there were
136149
items placed in the queue.
137150

‎pr-preview/pr-1123/_sources/library/importlib.resources.rst.txt

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,12 @@ within *packages*.
1616
"Resources" are file-like resources associated with a module or package in
1717
Python. The resources may be contained directly in a package, within a
1818
subdirectory contained in that package, or adjacent to modules outside a
19-
package. Resources may be text or binary. As a result, Python module sources
20-
(.py) of a package and compilation artifacts (pycache) are technically
21-
de-facto resources of that package. In practice, however, resources are
22-
primarily those non-Python artifacts exposed specifically by the package
23-
author.
19+
package. Resources may be text or binary. As a result, a package's Python
20+
module sources (.py), compilation artifacts (pycache), and installation
21+
artifacts (like :func:`reserved filenames <os.path.isreserved>`
22+
in directories) are technically de-facto resources of that package.
23+
In practice, however, resources are primarily those non-Python artifacts
24+
exposed specifically by the package author.
2425

2526
Resources can be opened or read in either binary or text mode.
2627

‎pr-preview/pr-1123/_sources/library/queue.rst.txt

Lines changed: 30 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -187,9 +187,6 @@ fully processed by daemon consumer threads.
187187
processed (meaning that a :meth:`task_done` call was received for every item
188188
that had been :meth:`put` into the queue).
189189

190-
``shutdown(immediate=True)`` calls :meth:`task_done` for each remaining item
191-
in the queue.
192-
193190
Raises a :exc:`ValueError` if called more times than there were items placed in
194191
the queue.
195192

@@ -204,6 +201,9 @@ fully processed by daemon consumer threads.
204201
count of unfinished tasks drops to zero, :meth:`join` unblocks.
205202

206203

204+
Waiting for task completion
205+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
206+
207207
Example of how to wait for enqueued tasks to be completed::
208208

209209
import threading
@@ -233,22 +233,38 @@ Example of how to wait for enqueued tasks to be completed::
233233
Terminating queues
234234
^^^^^^^^^^^^^^^^^^
235235

236-
:class:`Queue` objects can be made to prevent further interaction by shutting
237-
them down.
236+
When no longer needed, :class:`Queue` objects can be wound down
237+
until empty or terminated immediately with a hard shutdown.
238238

239239
.. method:: Queue.shutdown(immediate=False)
240240

241-
Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put` raise
242-
:exc:`ShutDown`.
241+
Put a :class:`Queue` instance into a shutdown mode.
242+
243+
The queue can no longer grow.
244+
Future calls to :meth:`~Queue.put` raise :exc:`ShutDown`.
245+
Currently blocked callers of :meth:`~Queue.put` will be unblocked
246+
and will raise :exc:`ShutDown` in the formerly blocked thread.
247+
248+
If *immediate* is false (the default), the queue can be wound
249+
down normally with :meth:`~Queue.get` calls to extract tasks
250+
that have already been loaded.
251+
252+
And if :meth:`~Queue.task_done` is called for each remaining task, a
253+
pending :meth:`~Queue.join` will be unblocked normally.
254+
255+
Once the queue is empty, future calls to :meth:`~Queue.get` will
256+
raise :exc:`ShutDown`.
243257

244-
By default, :meth:`~Queue.get` on a shut down queue will only raise once the
245-
queue is empty. Set *immediate* to true to make :meth:`~Queue.get` raise
246-
immediately instead.
258+
If *immediate* is true, the queue is terminated immediately.
259+
The queue is drained to be completely empty. All callers of
260+
:meth:`~Queue.join` are unblocked regardless of the number
261+
of unfinished tasks. Blocked callers of :meth:`~Queue.get`
262+
are unblocked and will raise :exc:`ShutDown` because the
263+
queue is empty.
247264

248-
All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get` will be
249-
unblocked. If *immediate* is true, a task will be marked as done for each
250-
remaining item in the queue, which may unblock callers of
251-
:meth:`~Queue.join`.
265+
Use caution when using :meth:`~Queue.join` with *immediate* set
266+
to true. This unblocks the join even when no work has been done
267+
on the tasks, violating the usual invariant for joining a queue.
252268

253269
.. versionadded:: 3.13
254270

‎pr-preview/pr-1123/about.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ <h3>瀏覽</h3>
320320
<a href="https://www.python.org/psf/donations/">Please donate.</a>
321321
<br>
322322
<br>
323-
最後更新於 7月 24, 2025 (00:21 UTC)。
323+
最後更新於 7月 25, 2025 (00:21 UTC)。
324324

325325
<a href="/bugs.html">Found a bug</a>?
326326

‎pr-preview/pr-1123/bugs.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ <h3>瀏覽</h3>
359359
<a href="https://www.python.org/psf/donations/">Please donate.</a>
360360
<br>
361361
<br>
362-
最後更新於 7月 24, 2025 (00:21 UTC)。
362+
最後更新於 7月 25, 2025 (00:21 UTC)。
363363

364364
<a href="/bugs.html">Found a bug</a>?
365365

‎pr-preview/pr-1123/c-api/abstract.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,7 @@ <h3>瀏覽</h3>
329329
<a href="https://www.python.org/psf/donations/">Please donate.</a>
330330
<br>
331331
<br>
332-
最後更新於 7月 24, 2025 (00:21 UTC)。
332+
最後更新於 7月 25, 2025 (00:21 UTC)。
333333

334334
<a href="/bugs.html">Found a bug</a>?
335335

‎pr-preview/pr-1123/c-api/allocation.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -346,7 +346,7 @@ <h3>瀏覽</h3>
346346
<a href="https://www.python.org/psf/donations/">Please donate.</a>
347347
<br>
348348
<br>
349-
最後更新於 7月 24, 2025 (00:21 UTC)。
349+
最後更新於 7月 25, 2025 (00:21 UTC)。
350350

351351
<a href="/bugs.html">Found a bug</a>?
352352

‎pr-preview/pr-1123/c-api/apiabiversion.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -376,7 +376,7 @@ <h3>瀏覽</h3>
376376
<a href="https://www.python.org/psf/donations/">Please donate.</a>
377377
<br>
378378
<br>
379-
最後更新於 7月 24, 2025 (00:21 UTC)。
379+
最後更新於 7月 25, 2025 (00:21 UTC)。
380380

381381
<a href="/bugs.html">Found a bug</a>?
382382

‎pr-preview/pr-1123/c-api/arg.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -931,7 +931,7 @@ <h3>瀏覽</h3>
931931
<a href="https://www.python.org/psf/donations/">Please donate.</a>
932932
<br>
933933
<br>
934-
最後更新於 7月 24, 2025 (00:21 UTC)。
934+
最後更新於 7月 25, 2025 (00:21 UTC)。
935935

936936
<a href="/bugs.html">Found a bug</a>?
937937

‎pr-preview/pr-1123/c-api/bool.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -340,7 +340,7 @@ <h3>瀏覽</h3>
340340
<a href="https://www.python.org/psf/donations/">Please donate.</a>
341341
<br>
342342
<br>
343-
最後更新於 7月 24, 2025 (00:21 UTC)。
343+
最後更新於 7月 25, 2025 (00:21 UTC)。
344344

345345
<a href="/bugs.html">Found a bug</a>?
346346

0 commit comments

Comments
 (0)