GH-137630: Convert _interpqueues to use Argument Clinic

[AA-Turner]

Note, we use a custom converter qidarg_converter here. I have changed the qidarg_converter() function to simplify the return -- we only ever use qidarg.id.

pydoc diff:

--- pydoc-interpqueues-HEAD.txt	2025-08-12 19:29:03.554066000 +0100
+++ pydoc-interpqueues-AC.txt	2025-08-12 19:26:19.952112000 +0100
@@ -130,70 +130,52 @@
      |  args
 
 FUNCTIONS
-    bind(...)
-        bind(qid)
-
+    bind(qid)
         Take a reference to the identified queue.
-        The queue is not destroyed until there are no references left.
 
-    create(...)
-        create(maxsize, unboundop, fallback) -> qid
+        The queue is not destroyed until there are no references left.
 
+    create(maxsize, unboundop=-1, fallback=-1)
         Create a new cross-interpreter queue and return its unique generated ID.
-        It is a new reference as though bind() had been called on the queue.
 
+        It is a new reference as though bind() had been called on the queue.
         The caller is responsible for calling destroy() for the new queue
         before the runtime is finalized.
 
-    destroy(...)
-        destroy(qid)
+    destroy(qid)
+        Clear and destroy the queue.
 
-        Clear and destroy the queue.  Afterward attempts to use the queue
-        will behave as though it never existed.
-
-    get(...)
-        get(qid) -> (obj, unboundop)
+        Afterward attempts to use the queue will behave as though it never existed.
 
+    get(qid)
         Return a new object from the data at the front of the queue.
-        The unbound op is also returned.
 
+        The unbound op is also returned.
         If there is nothing to receive then raise QueueEmpty.
 
-    get_count(...)
-        get_count(qid)
-
+    get_count(qid)
         Return the number of items in the queue.
 
-    get_maxsize(...)
-        get_maxsize(qid)
-
+    get_maxsize(qid)
         Return the maximum number of items in the queue.
 
-    get_queue_defaults(...)
-        get_queue_defaults(qid)
-
+    get_queue_defaults(qid)
         Return the queue's default values, set when it was created.
 
-    is_full(...)
-        is_full(qid)
-
+    is_full(qid)
         Return true if the queue has a maxsize and has reached it.
 
     list_all()
-        list_all() -> [(qid, unboundop, fallback)]
-
         Return the list of IDs for all queues.
-        Each corresponding default unbound op and fallback is also included.
 
-    put(...)
-        put(qid, obj)
+        Each corresponding default unbound op and fallback is also included.
 
+    put(qid, obj, unboundop=-1, fallback=-1)
         Add the object's data to the queue.
 
-    release(...)
-        release(qid)
-
+    release(qid)
         Release a reference to the queue.
+
         The queue is destroyed once there are no references left.
 
 FILE

A

• Issue: Convert _interpreters to Argument Clinic #137630

[serhiy-storchaka]

There is a bug in the current code which should be fixed in 3.14 too. The rest LGTM. But I would like to get @ericsnowcurrently's approve.

[serhiy-storchaka]

I also add that after removing the return pseudo-annotation, some docstrings look more self-contadicting.

something(qid)
    Return bla-bla X.

    Ah, forget it, also return Y and Z.

It was in the old docstrings, but with -> (X, Y, Z) you at least could suspect that "return X" was not the whole truth.

[serhiy-storchaka]

Technically LGTM, but what would @ericsnowcurrently say?

It is sad that this cannot be backported to 3.14, so there will be such large difference between 3.14 and 3.15.

[ericsnowcurrently]

Considering everything stays the same functionally (per all the passing tests), I don't really have any meaningful objections, especially since this is an internal module where I do not expect anyone to ever look at the docstrings. In fact, we could probably change all the docstrings to comments.

FWIW, my review comments are mostly me fussing about argument clinic, which is probably way too late to be relevant. :)

[AA-Turner]

Thanks both for the reviews!

A