[Python-Dev] Making Queue.Queue easier to use

[Guido van Rossum]

On 10/11/05, Nick Coghlan <ncoghlan at iinet.net.au> wrote:
> The multi-processing discussion reminded me that I have a few problems I run
> into every time I try to use Queue objects.
>
> My first problem is finding it:
>
> Py> from threading import Queue # Nope
> Traceback (most recent call last):
>    File "<stdin>", line 1, in ?
> ImportError: cannot import name Queue
> Py> from Queue import Queue # Ah, there it is

I don't think that's a reason to move it.

>>> from sys import Queue
ImportError: cannon import name Queue
>>> from os import Queue
ImportError: cannot import name Queue
>>> # Well where the heck is it?!

> What do people think of the idea of adding an alias to Queue into the
> threading module so that:
>     a) the first line above works; and

I see no need. Code that *doesn't* need Queue but does use threading
shouldn't have to pay for loading Queue.py.

>     b) Queue can be documented with all of the other threading primitives,
>        rather than being off somewhere else in its own top-level section.

Do top-level sections have to limit themselves to a single module?

Even if they do, I think it's fine to plant a prominent link to the
Queue module. You can't really expect people to learn how to use
threads wisely from reading the library reference anyway.

> My second problem is with the current signatures of the put() and get()
> methods. Specifically, the following code blocks forever instead of raising an
> Empty exception after 500 milliseconds as one might expect:
>    from Queue import Queue
>    x = Queue()
>    x.get(0.5)

I'm not sure if I have much sympathy with a bug due to refusing to
read the docs... :)

> I assume the current signature is there for backward compatibility with the
> original version that didn't support timeouts (considering the difficulty of
> telling the difference between "x.get(1)" and "True = 1; x.get(True)" from
> inside the get() method)

Huh? What a bizarre idea. Why would you do that? I gues I don't
understand where you're coming from.

> However, the need to write "x.get(True, 0.5)" seems seriously redundant, given
> that a single paramater can actually handle all the options (as is currently
> the case with Condition.wait()).

So write x.get(timeout=0.5). That's clear and unambiguous.

> The "put_nowait" and "get_nowait" functions are fine, because they serve a
> useful documentation purpose at the calling point (particularly given the
> current clumsy timeout signature).
>
> What do people think of the idea of adding "put_wait" and "get_wait" methods
> with the signatures:
>    put_wait(item,[timeout=None)
>    get_wait([timeout=None])

-1. I'd rather not tweak the current Queue module at all until Python
3000. Then we could force people to use keyword args.

> Optionally, the existing "put" and "get" methods could be deprecated, with the
> goal of eventually changing their signature to match the put_wait and get_wait
> methods above.

Apart from trying to guess the API without reading the docs (:-), what
are the use cases for using put/get with a timeout? I have a feeling
it's not that common.

--
--Guido van Rossum (home page: http://www.python.org/~guido/)