[issue27624] unclear documentation on Queue.qsize()

R. David Murray added the comment: Doug: side note. Raymond teaches Python, and makes a study of what works and doesn't work in communicating it to students, so he isn't rejecting this lightly. -- ___ Python tracker

[issue27624] unclear documentation on Queue.qsize()

Raymond Hettinger added the comment: Sorry Doug, I don't find any of the suggestions to be an improvement and I concur with David Murray that the docstring for qsize() isn't the place for a tutorial on race conditions and LBYL vs EAPF which are general threading topics rather than a queue

[issue27624] unclear documentation on Queue.qsize()

Changes by Raymond Hettinger : -- assignee: docs@python -> rhettinger ___ Python tracker ___

[issue27624] unclear documentation on Queue.qsize()

Doug Hoskisson added the comment: My suggestion was not to delete the "approximate" entirely. Just move it out of the first sentence to make it more consistent with the other documentation. This is the model I'm seeing in empty() and full(): The first sentence is something simple and direct

[issue27624] unclear documentation on Queue.qsize()

R. David Murray added the comment: The subsequent text specifies the behavior. You *could* delete the 'approximately' from the qsize documentation to be parallel, but I think that would be a disservice to the reader. You could also use the phrase "at the moment of the call" in all three,

[issue27624] unclear documentation on Queue.qsize()

R. David Murray added the comment: The current wording is, IMO, better than the suggested wording, especially if you don't want to be "teaching stuff". The current wording is a specification of the method's behavior. I really don't know what you could replace "approximate" with that would

[issue27624] unclear documentation on Queue.qsize()

Doug Hoskisson added the comment: More explicit is ok, if that's what people want, but just not in the first sentence, because that stuff has nothing to do with what is being documented specifically (as evidenced by referencing a wikipedia article that doesn't even mention python). I don't

[issue27624] unclear documentation on Queue.qsize()

STINNER Victor added the comment: """ Return the number of items in the queue. Note, in multi-threading this mostly just serves as an approximation, and information from this doesn’t guarantee that a subsequent get() or put() will not block. """ I dislike this description. If I understand

[issue27624] unclear documentation on Queue.qsize()

Doug Hoskisson added the comment: My suggestion for this documentation: """ Return the number of items in the queue. Note, in multi-threading this mostly just serves as an approximation, and information from this doesn’t guarantee that a subsequent get() or put() will not block. """

[issue27624] unclear documentation on Queue.qsize()

Doug Hoskisson added the comment: One thing that is important to recognize in considering this, is which information is specific to what is being documented, and which information is more general. Some people may think that documentation should only give information specific to what is being

[issue27624] unclear documentation on Queue.qsize()

Doug Hoskisson added the comment: The way that this whole page of documentation is written does not suggest that this class is ONLY for use in a multi-threaded setting. This class can be used without multi-threading, right? Wouldn't it be useful to know whether this function does give the

[issue27624] unclear documentation on Queue.qsize()

R. David Murray added the comment: What if we just replaced the period with a colon? That is, the definition of "approximate" is the two rules in the second sentence. -- nosy: +rhettinger ___ Python tracker

[issue27624] unclear documentation on Queue.qsize()

Doug Hoskisson added the comment: Some strategies for approximating might report a size the the queue has never been and never will be. For example, a strategy could gather data and find the size is increasing at some rate, and approximate based on that rate, but then the rate of increase

[issue27624] unclear documentation on Queue.qsize()

R. David Murray added the comment: Since we're talking about multi-threaded operations, the concept of "exact size at an arbitrary time" isn't operationally different from "a strategy used for approximating". The subsequent text clarifies what "approximately" means operationally. Specifying

[issue27624] unclear documentation on Queue.qsize()

New submission from Doug Hoskisson: The documentation for Queue.qsize(): "Return the approximate size of the queue." "approximate" is unclear. It might suggest some strategy used for approximating, or it might be the exact size at an arbitrary time. It should be made more clear. --