(Queue.Empty): When class based exceptions are in force, derive this

class from the standard base exception Exception.  Otherwise define
Queue.Empty as a string exception.

(Queue): 8-space to 4-space indentation conversion.  Also, basically
recast all method comments into docstrings.

diff --git a/Lib/Queue.py b/Lib/Queue.py
index 5125fd5dd2c0b262d708d53b3027b228c5628313..1cec4e30af21f609beb7f9fab3c591c8b9b418fe 100644 (file)
--- a/Lib/Queue.py
+++ b/Lib/Queue.py
@@ -1,121 +1,135 @@
 # A multi-producer, multi-consumer queue.
 
-Empty = 'Queue.Empty' # Exception raised by get_nowait()
+# define this exception to be compatible with Python 1.5's class
+# exceptions, but also when -X option is used.
+try:
+    class Empty(Exception):
+       pass
+except TypeError:
+    # string based exceptions
+    Empty = 'Queue.Empty'              # Exception raised by get_nowait()
 
 class Queue:
-
-       # Initialize a queue object with a given maximum size
-       # (If maxsize is <= 0, the maximum size is infinite)
-       def __init__(self, maxsize):
-               import thread
-               self._init(maxsize)
-               self.mutex = thread.allocate_lock()
-               self.esema = thread.allocate_lock()
-               self.esema.acquire_lock()
-               self.fsema = thread.allocate_lock()
-
-       # Get an approximation of the queue size (not reliable!)
-       def qsize(self):
-               self.mutex.acquire_lock()
-               n = self._qsize()
-               self.mutex.release_lock()
-               return n
-
-       # Check if the queue is empty (not reliable!)
-       def empty(self):
-               self.mutex.acquire_lock()
-               n = self._empty()
-               self.mutex.release_lock()
-               return n
-
-       # Check if the queue is full (not reliable!)
-       def full(self):
-               self.mutex.acquire_lock()
-               n = self._full()
-               self.mutex.release_lock()
-               return n
-
-       # Put a new item into the queue
-       def put(self, item):
-               self.fsema.acquire_lock()
-               self.mutex.acquire_lock()
-               was_empty = self._empty()
-               self._put(item)
-               if was_empty:
-                       self.esema.release_lock()
-               if not self._full():
-                       self.fsema.release_lock()
-               self.mutex.release_lock()
-
-       # Get an item from the queue,
-       # blocking if necessary until one is available
-       def get(self):
-               self.esema.acquire_lock()
-               self.mutex.acquire_lock()
-               was_full = self._full()
-               item = self._get()
-               if was_full:
-                       self.fsema.release_lock()
-               if not self._empty():
-                       self.esema.release_lock()
-               self.mutex.release_lock()
-               return item
-
-       # Get an item from the queue if one is immediately available,
-       # raise Empty if the queue is empty or temporarily unavailable
-       def get_nowait(self):
-               locked = self.esema.acquire_lock(0)
-               self.mutex.acquire_lock()
-               if self._empty():
-                       # The queue is empyt -- we can't have esema
-                       self.mutex.release_lock()
-                       raise Empty
-               if not locked:
-                       locked = self.esema.acquire_lock(0)
-                       if not locked:
-                               # Somebody else has esema
-                               # but we have mutex --
-                               # go out of their way
-                               self.mutex.release_lock()
-                               raise Empty
-               was_full = self._full()
-               item = self._get()
-               if was_full:
-                       self.fsema.release_lock()
-               if not self._empty():
-                       self.esema.release_lock()
+    def __init__(self, maxsize):
+       """Initialize a queue object with a given maximum size.
+
+       If maxsize is <= 0, the queue size is infinite.
+       """
+       import thread
+       self._init(maxsize)
+       self.mutex = thread.allocate_lock()
+       self.esema = thread.allocate_lock()
+       self.esema.acquire_lock()
+       self.fsema = thread.allocate_lock()
+
+    def qsize(self):
+       """Returns the approximate size of the queue (not reliable!)."""
+       self.mutex.acquire_lock()
+       n = self._qsize()
+       self.mutex.release_lock()
+       return n
+
+    def empty(self):
+       """Returns 1 if the queue is empty, 0 otherwise (not reliable!)."""
+       self.mutex.acquire_lock()
+       n = self._empty()
+       self.mutex.release_lock()
+       return n
+
+    def full(self):
+       """Returns 1 if the queue is full, 0 otherwise (not reliable!)."""
+       self.mutex.acquire_lock()
+       n = self._full()
+       self.mutex.release_lock()
+       return n
+
+    def put(self, item):
+       """Put an item into the queue."""
+       self.fsema.acquire_lock()
+       self.mutex.acquire_lock()
+       was_empty = self._empty()
+       self._put(item)
+       if was_empty:
+           self.esema.release_lock()
+       if not self._full():
+           self.fsema.release_lock()
+       self.mutex.release_lock()
+
+    def get(self):
+       """Gets and returns an item from the queue.
+       This method blocks if necessary until an item is available.
+       """
+       self.esema.acquire_lock()
+       self.mutex.acquire_lock()
+       was_full = self._full()
+       item = self._get()
+       if was_full:
+           self.fsema.release_lock()
+       if not self._empty():
+           self.esema.release_lock()
+       self.mutex.release_lock()
+       return item
+
+    # Get an item from the queue if one is immediately available,
+    # raise Empty if the queue is empty or temporarily unavailable
+    def get_nowait(self):
+       """Gets and returns an item from the queue.
+       Only gets an item if one is immediately available, Otherwise
+       this raises the Empty exception if the queue is empty or
+       temporarily unavailable.
+       """
+       locked = self.esema.acquire_lock(0)
+       self.mutex.acquire_lock()
+       if self._empty():
+           # The queue is empty -- we can't have esema
+           self.mutex.release_lock()
+           raise Empty
+       if not locked:
+           locked = self.esema.acquire_lock(0)
+           if not locked:
+               # Somebody else has esema
+               # but we have mutex --
+               # go out of their way
                self.mutex.release_lock()
-               return item
-
-       # XXX Need to define put_nowait() as well.
-               
-
-       # Override these methods to implement other queue organizations
-       # (e.g. stack or priority queue).
-       # These will only be called with appropriate locks held
-
-       # Initialize the queue representation
-       def _init(self, maxsize):
-               self.maxsize = maxsize
-               self.queue = []
-
-       def _qsize(self):
-               return len(self.queue)
-
-       # Check wheter the queue is empty
-       def _empty(self):
-               return not self.queue
-
-       # Check whether the queue is full
-       def _full(self):
-               return self.maxsize > 0 and len(self.queue) == self.maxsize
-
-       # Put a new item in the queue
-       def _put(self, item):
-               self.queue.append(item)
-
-       # Get an item from the queue
-       def _get(self):
-               item = self.queue[0]
-               del self.queue[0]
-               return item
+               raise Empty
+       was_full = self._full()
+       item = self._get()
+       if was_full:
+           self.fsema.release_lock()
+       if not self._empty():
+           self.esema.release_lock()
+       self.mutex.release_lock()
+       return item
+
+    # XXX Need to define put_nowait() as well.
+
+
+    # Override these methods to implement other queue organizations
+    # (e.g. stack or priority queue).
+    # These will only be called with appropriate locks held
+
+    # Initialize the queue representation
+    def _init(self, maxsize):
+       self.maxsize = maxsize
+       self.queue = []
+
+    def _qsize(self):
+       return len(self.queue)
+
+    # Check wheter the queue is empty
+    def _empty(self):
+       return not self.queue
+
+    # Check whether the queue is full
+    def _full(self):
+       return self.maxsize > 0 and len(self.queue) == self.maxsize
+
+    # Put a new item in the queue
+    def _put(self, item):
+       self.queue.append(item)
+
+    # Get an item from the queue
+    def _get(self):
+       item = self.queue[0]
+       del self.queue[0]
+       return item