From 4bcaca5bcada64bc57f9f5b1ab7d4c1b87b1c8cb Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 26 Sep 2025 22:59:50 +0900 Subject: [PATCH 01/12] Fix names for some error types --- Doc/library/concurrent.interpreters.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 41ea6af3b226e98..21197a0d2c3ef0a 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -335,13 +335,13 @@ Communicating Between Interpreters The queue's ID. -.. exception:: QueueEmptyError +.. exception:: QueueEmpty This exception, a subclass of :exc:`queue.Empty`, is raised from :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 From e8c5e51af202a875900992c539ed206884ccf954 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 26 Sep 2025 23:11:39 +0900 Subject: [PATCH 02/12] Remove dedent parameter for create method --- Doc/library/concurrent.interpreters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 21197a0d2c3ef0a..cb95c2e6a08bbd3 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -271,7 +271,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). From 40ad3489dd24cd14711ca86fe30013cb80059f07 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 26 Sep 2025 23:16:53 +0900 Subject: [PATCH 03/12] Update document of create_queue --- Doc/library/concurrent.interpreters.rst | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index cb95c2e6a08bbd3..d9b45cf31316714 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -227,11 +227,26 @@ 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, *, unbounditems=UNBOUND) 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 block 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. + + *unbounditems* controls the behavior when the interpreter that put an + item into the queue is destroyed. It can be one of: + + * :const:`UNBOUND_ERROR` - raise :exc:`ItemInterpreterDestroyed` when + getting an item from a destroyed interpreter + * :const:`UNBOUND_REMOVE` - automatically remove items when their + original interpreter is destroyed + * :const:`UNBOUND` - return :const:`UNBOUND` in place of the original + item (default) + Interpreter objects ^^^^^^^^^^^^^^^^^^^ @@ -348,6 +363,14 @@ Communicating Between Interpreters is full. +.. exception:: ItemInterpreterDestroyed + + This exception, a subclass of :exc:`QueueError`, is raised from + :meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the original + interpreter that put an item into the queue has been destroyed and + the queue was created with ``unbounditems=UNBOUND_ERROR``. + + Basic usage ----------- From 654ef89ed6f25df5b5430a0e6cff1b8ea7b59e90 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 26 Sep 2025 23:30:01 +0900 Subject: [PATCH 04/12] Add put / put_nowait function document --- Doc/library/concurrent.interpreters.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index d9b45cf31316714..2e0ac686c752f18 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -350,6 +350,24 @@ Communicating Between Interpreters The queue's ID. + .. method:: put(obj, block=True, timeout=None, *, unbounditems=None) + + Add the object to the queue. + + This method behaves like :meth:`queue.Queue.put`, with the additional + *unbounditems* parameter. See :func:`create_queue` for details on + the *unbounditems* parameter and its behavior. + + + .. method:: put_nowait(obj, *, unbounditems=None) + + Add the object to the queue without blocking. + + This method behaves like :meth:`queue.Queue.put_nowait`, with the + additional *unbounditems* parameter. See :func:`create_queue` for + details on the *unbounditems* parameter and its behavior. + + .. exception:: QueueEmpty This exception, a subclass of :exc:`queue.Empty`, is raised from From 5e9f649fae39bbdbf865cb0f3c2564a56147b453 Mon Sep 17 00:00:00 2001 From: AN Long Date: Sat, 27 Sep 2025 00:05:17 +0900 Subject: [PATCH 05/12] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/concurrent.interpreters.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 2e0ac686c752f18..7b41ea09d8fabf3 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -233,7 +233,7 @@ This module defines the following functions: 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 block once this + 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. @@ -352,7 +352,7 @@ Communicating Between Interpreters .. method:: put(obj, block=True, timeout=None, *, unbounditems=None) - Add the object to the queue. + Add the object *obj* to the queue. This method behaves like :meth:`queue.Queue.put`, with the additional *unbounditems* parameter. See :func:`create_queue` for details on @@ -361,7 +361,7 @@ Communicating Between Interpreters .. method:: put_nowait(obj, *, unbounditems=None) - Add the object to the queue without blocking. + Add the object *obj* to the queue without blocking. This method behaves like :meth:`queue.Queue.put_nowait`, with the additional *unbounditems* parameter. See :func:`create_queue` for @@ -383,7 +383,7 @@ Communicating Between Interpreters .. exception:: ItemInterpreterDestroyed - This exception, a subclass of :exc:`QueueError`, is raised from + This exception, a subclass of :exc:`QueueError`, is raised by :meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the original interpreter that put an item into the queue has been destroyed and the queue was created with ``unbounditems=UNBOUND_ERROR``. From 5768d081c34f9e4cb283694ddbc1d8640bef8b5b Mon Sep 17 00:00:00 2001 From: AN Long Date: Sat, 27 Sep 2025 00:14:51 +0900 Subject: [PATCH 06/12] Fix rst error --- Doc/library/concurrent.interpreters.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 7b41ea09d8fabf3..c435001cd734a6f 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -383,10 +383,9 @@ Communicating Between Interpreters .. exception:: ItemInterpreterDestroyed - This exception, a subclass of :exc:`QueueError`, is raised by - :meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the original - interpreter that put an item into the queue has been destroyed and - the queue was created with ``unbounditems=UNBOUND_ERROR``. + This exception is raised by :meth:`!Queue.get` and :meth:`!Queue.get_nowait` + when the original interpreter that put an item into the queue has been + destroyed and the queue was created with ``unbounditems=UNBOUND_ERROR``. Basic usage From 4e4c314dab6c30f9202bf527317e0e77115c27fd Mon Sep 17 00:00:00 2001 From: AN Long Date: Sun, 28 Sep 2025 20:13:08 +0900 Subject: [PATCH 07/12] Revert some queues related docs since we should doc them in queues in the future --- Doc/library/concurrent.interpreters.rst | 38 +------------------------ 1 file changed, 1 insertion(+), 37 deletions(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index c435001cd734a6f..00c3e9e595130e4 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -227,7 +227,7 @@ This module defines the following functions: Initialize a new (idle) Python interpreter and return a :class:`Interpreter` object for it. -.. function:: create_queue(maxsize=0, *, unbounditems=UNBOUND) +.. function:: create_queue(maxsize=0) Initialize a new cross-interpreter queue and return a :class:`Queue` object for it. @@ -237,17 +237,6 @@ This module defines the following functions: size has been reached, until queue items are consumed. If *maxsize* is less than or equal to zero, the queue size is infinite. - *unbounditems* controls the behavior when the interpreter that put an - item into the queue is destroyed. It can be one of: - - * :const:`UNBOUND_ERROR` - raise :exc:`ItemInterpreterDestroyed` when - getting an item from a destroyed interpreter - * :const:`UNBOUND_REMOVE` - automatically remove items when their - original interpreter is destroyed - * :const:`UNBOUND` - return :const:`UNBOUND` in place of the original - item (default) - - Interpreter objects ^^^^^^^^^^^^^^^^^^^ @@ -350,24 +339,6 @@ Communicating Between Interpreters The queue's ID. - .. method:: put(obj, block=True, timeout=None, *, unbounditems=None) - - Add the object *obj* to the queue. - - This method behaves like :meth:`queue.Queue.put`, with the additional - *unbounditems* parameter. See :func:`create_queue` for details on - the *unbounditems* parameter and its behavior. - - - .. method:: put_nowait(obj, *, unbounditems=None) - - Add the object *obj* to the queue without blocking. - - This method behaves like :meth:`queue.Queue.put_nowait`, with the - additional *unbounditems* parameter. See :func:`create_queue` for - details on the *unbounditems* parameter and its behavior. - - .. exception:: QueueEmpty This exception, a subclass of :exc:`queue.Empty`, is raised from @@ -381,13 +352,6 @@ Communicating Between Interpreters is full. -.. exception:: ItemInterpreterDestroyed - - This exception is raised by :meth:`!Queue.get` and :meth:`!Queue.get_nowait` - when the original interpreter that put an item into the queue has been - destroyed and the queue was created with ``unbounditems=UNBOUND_ERROR``. - - Basic usage ----------- From 24f11c75f87e92b6f1a8f8ce62c3eacfb4bdd903 Mon Sep 17 00:00:00 2001 From: An Long Date: Tue, 13 Oct 2026 01:55:07 +0900 Subject: [PATCH 08/12] Add qsize / empty / full document --- Doc/library/concurrent.interpreters.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index aa7f311789582e9..95058dd11c0b302 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -335,6 +335,18 @@ Communicating Between Interpreters The queue's ID. + .. method:: qsize() + + 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. + .. exception:: QueueEmpty From 612d8ac91a0c7dbc0a25f69bbed6320fa50f8a98 Mon Sep 17 00:00:00 2001 From: An Long Date: Tue, 13 Oct 2026 01:58:29 +0900 Subject: [PATCH 09/12] Update Queue description --- Doc/library/concurrent.interpreters.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 95058dd11c0b302..6217cd37690dae4 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -323,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, From c2c7fee140c43402f74f8753d248f74a3b84d03f Mon Sep 17 00:00:00 2001 From: An Long Date: Tue, 13 Oct 2026 02:02:56 +0900 Subject: [PATCH 10/12] Add put / get document --- Doc/library/concurrent.interpreters.rst | 34 +++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 6217cd37690dae4..ca367087b666b48 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -349,17 +349,47 @@ Communicating Between Interpreters 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:: 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. From 14c83046d67de0b3856f88402aa3840fddad40f6 Mon Sep 17 00:00:00 2001 From: An Long Date: Tue, 13 Oct 2026 02:06:47 +0900 Subject: [PATCH 11/12] Add queue example --- Doc/library/concurrent.interpreters.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index ca367087b666b48..05bf497b68a2082 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -430,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() From ea5ad1d5e2580301dcf8b4a04c8a2a0eadacf839 Mon Sep 17 00:00:00 2001 From: An Long Date: Tue, 13 Oct 2026 02:21:03 +0900 Subject: [PATCH 12/12] Add removed ids --- Doc/tools/removed-ids.txt | 4 ++++ 1 file changed, 4 insertions(+) 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