https://github.com/python/cpython/commit/fd671619e7054706fd62c187749c806f18f068e1 commit: fd671619e7054706fd62c187749c806f18f068e1 branch: main author: An Long <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-10-12T14:38:41-04:00 summary:
gh-136563: Update `concurrent.interpreters` module documentation (GH-139358) Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/concurrent.interpreters.rst M Doc/tools/removed-ids.txt diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 2c509ab13a6acfd..05bf497b68a2082 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -224,11 +224,15 @@ This module defines the following functions: Initialize a new (idle) Python interpreter and return a :class:`Interpreter` object for it. -.. function:: create_queue() +.. function:: create_queue(maxsize=0) Initialize a new cross-interpreter queue and return a :class:`Queue` object for it. + *maxsize* is an integer that sets the upperbound limit on the number of + items that can be placed in the queue. Insertion will be blocked once this + size has been reached, until queue items are consumed. If *maxsize* is + less than or equal to zero, the queue size is infinite. Interpreter objects ^^^^^^^^^^^^^^^^^^^ @@ -268,7 +272,7 @@ Interpreter objects Some objects are actually shared and some are copied efficiently, but most are copied via :mod:`pickle`. See :ref:`interp-object-sharing`. - .. method:: exec(code, /, dedent=True) + .. method:: exec(code, /) Run the given source code in the interpreter (in the current thread). @@ -319,7 +323,9 @@ Communicating Between Interpreters .. class:: Queue(id) A wrapper around a low-level, cross-interpreter queue, which - implements the :class:`queue.Queue` interface. The underlying queue + implements all the methods of :class:`queue.Queue` except for + :meth:`~queue.Queue.task_done`, :meth:`~queue.Queue.join` + and :meth:`~queue.Queue.shutdown`. The underlying queue can only be created through :func:`create_queue`. Some objects are actually shared and some are copied efficiently, @@ -331,17 +337,59 @@ Communicating Between Interpreters The queue's ID. + .. method:: qsize() -.. exception:: QueueEmptyError + Return the number of items in the queue. + + .. method:: empty() + + Return ``True`` if the queue is empty, ``False`` otherwise. + + .. method:: full() + + Return ``True`` if the queue is full, ``False`` otherwise. + + .. method:: put(obj, block=True, timeout=None) + + Put *obj* into the queue. If optional args *block* is true and + *timeout* is ``None`` (the default), block if necessary until a free + slot is available. If *timeout* is a positive number, it blocks at + most *timeout* seconds and raises the :exc:`QueueFull` exception if + no free slot was available within that time. Otherwise (*block* is + false), put an object on the queue if a free slot is immediately + available, else raise the :exc:`QueueFull` exception (*timeout* is + ignored in that case). + + .. method:: put_nowait(obj) + + Equivalent to ``put(obj, block=False)``. + + .. method:: get(block=True, timeout=None) + + Remove and return an object from the queue. If optional args *block* + is true and *timeout* is ``None`` (the default), block if necessary + until an object is available. If *timeout* is a positive number, it + blocks at most *timeout* seconds and raises the :exc:`QueueEmpty` + exception if no object was available within that time. Otherwise + (*block* is false), return an object if one is immediately available, + else raise the :exc:`QueueEmpty` exception (*timeout* is ignored in + that case). + + .. method:: get_nowait() + + Equivalent to ``get(block=False)``. + + +.. exception:: QueueEmpty This exception, a subclass of :exc:`queue.Empty`, is raised from - :meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the queue + :meth:`Queue.get` and :meth:`Queue.get_nowait` when the queue is empty. -.. exception:: QueueFullError +.. exception:: QueueFull This exception, a subclass of :exc:`queue.Full`, is raised from - :meth:`!Queue.put` and :meth:`!Queue.put_nowait` when the queue + :meth:`Queue.put` and :meth:`Queue.put_nowait` when the queue is full. @@ -382,3 +430,17 @@ Creating an interpreter and running code in it:: t = interp.call_in_thread(run) t.join() + +Communicating between interpreters with a queue:: + + from concurrent import interpreters + + interp = interpreters.create() + queue = interpreters.create_queue() + + def worker(queue): + queue.put('spam!') + + t = interp.call_in_thread(worker, queue) + print(queue.get()) + t.join() diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt index 325cf006d0507e4..0d7d121198d9d27 100644 --- a/Doc/tools/removed-ids.txt +++ b/Doc/tools/removed-ids.txt @@ -114,3 +114,7 @@ library/turtle.html: changes-since-python-3-0 # 'turtle' documentation reorganisation (gh-157847) library/turtle.html: note library/turtle.html: introduction + +# Wrong exception names in 'concurrent.interpreters' docs (gh-136563) +library/concurrent.interpreters.html: concurrent.interpreters.QueueEmptyError +library/concurrent.interpreters.html: concurrent.interpreters.QueueFullError _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
