gh-102983: queue.Queue - Adding Cancelling Support

[mementum]

Proposed draft PR for #102983

• Issue: queue.Queue - Adding Cancelling Support #102983

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[JosephSBoyle]

The pass is redundant and docstrings should be triple quoted:)

Suggested change

	class Cancelled(Exception):
	'Exception raised by Queue.get(block=True) when cancelled'
	class Cancelled(Exception):
	'''Exception raised by Queue.get(block=True) when cancelled'''

[mementum]

Indeed, I simply wanted to keep the same style with which the Full exception is written, just a couple of lines above.

cpython/Lib/queue.py

Lines 23 to 25 in f2e5a6e

	class Full(Exception):
	'Exception raised by Queue.put(block=0)/put_nowait().'
	pass

Question:

• Shall we add also the same changes to Full?

[CAM-Gerlach]

Suggested change

	class Cancelled(Exception):
	'Exception raised by Queue.get(block=True) when cancelled'
	class Cancelled(Exception):
	"""Exception raised by Queue.get(block=True) when cancelled."""

Furthermore, while we're at it, per PEP 257 (PEP-257) and widespread convention, docstrings must use triple double quotes and summary lines should be complete sentences that always end with a period.

[mementum]

This PR already "works" (see sample test script in #102983. Things which could be considered

• What happens if the user does cancel(n) where n > number of blocking get?

  If one looks at the implementation of the similar notify(n) in threading.Condition, the code would actually block waiting for new waiters on the Condition, so it would seem it is the programmer's responsibility to ensure that n <= number of blocking get to leave no pending cancellation.

• If one leaves pending cancellations in place, should they also be applied to incoming non-blocking calls of get?

  One could even call this ahead of time cancellations

To fully avoid having pending cancellations in any case, the current amount of (blocking) gets can be considered in cancel(n) to be the maximum to cancel.

def cancel(self, n=1):
    with self.not_empty:
        n = min(n, len(self.not_empty._waiters))
        self.cancelling.release(n=n)
        self.not_empty.notify(n=n)

It would then depart from the similar behavior of notify behavior but would ensure only the actual blocking get are cancelled.