mirror of https://github.com/python/cpython
Make the docstring style consistent.
This commit is contained in:
parent
61bd72924e
commit
0c5e52f0bd
47
Lib/queue.py
47
Lib/queue.py
|
@ -1,4 +1,4 @@
|
||||||
"""A multi-producer, multi-consumer queue."""
|
'''A multi-producer, multi-consumer queue.'''
|
||||||
|
|
||||||
try:
|
try:
|
||||||
import threading
|
import threading
|
||||||
|
@ -11,18 +11,19 @@ from time import time
|
||||||
__all__ = ['Empty', 'Full', 'Queue', 'PriorityQueue', 'LifoQueue']
|
__all__ = ['Empty', 'Full', 'Queue', 'PriorityQueue', 'LifoQueue']
|
||||||
|
|
||||||
class Empty(Exception):
|
class Empty(Exception):
|
||||||
"Exception raised by Queue.get(block=0)/get_nowait()."
|
'Exception raised by Queue.get(block=0)/get_nowait().'
|
||||||
pass
|
pass
|
||||||
|
|
||||||
class Full(Exception):
|
class Full(Exception):
|
||||||
"Exception raised by Queue.put(block=0)/put_nowait()."
|
'Exception raised by Queue.put(block=0)/put_nowait().'
|
||||||
pass
|
pass
|
||||||
|
|
||||||
class Queue:
|
class Queue:
|
||||||
"""Create a queue object with a given maximum size.
|
'''Create a queue object with a given maximum size.
|
||||||
|
|
||||||
If maxsize is <= 0, the queue size is infinite.
|
If maxsize is <= 0, the queue size is infinite.
|
||||||
"""
|
'''
|
||||||
|
|
||||||
def __init__(self, maxsize=0):
|
def __init__(self, maxsize=0):
|
||||||
self.maxsize = maxsize
|
self.maxsize = maxsize
|
||||||
self._init(maxsize)
|
self._init(maxsize)
|
||||||
|
@ -47,7 +48,7 @@ class Queue:
|
||||||
self.unfinished_tasks = 0
|
self.unfinished_tasks = 0
|
||||||
|
|
||||||
def task_done(self):
|
def task_done(self):
|
||||||
"""Indicate that a formerly enqueued task is complete.
|
'''Indicate that a formerly enqueued task is complete.
|
||||||
|
|
||||||
Used by Queue consumer threads. For each get() used to fetch a task,
|
Used by Queue consumer threads. For each get() used to fetch a task,
|
||||||
a subsequent call to task_done() tells the queue that the processing
|
a subsequent call to task_done() tells the queue that the processing
|
||||||
|
@ -59,7 +60,7 @@ class Queue:
|
||||||
|
|
||||||
Raises a ValueError if called more times than there were items
|
Raises a ValueError if called more times than there were items
|
||||||
placed in the queue.
|
placed in the queue.
|
||||||
"""
|
'''
|
||||||
with self.all_tasks_done:
|
with self.all_tasks_done:
|
||||||
unfinished = self.unfinished_tasks - 1
|
unfinished = self.unfinished_tasks - 1
|
||||||
if unfinished <= 0:
|
if unfinished <= 0:
|
||||||
|
@ -69,25 +70,25 @@ class Queue:
|
||||||
self.unfinished_tasks = unfinished
|
self.unfinished_tasks = unfinished
|
||||||
|
|
||||||
def join(self):
|
def join(self):
|
||||||
"""Blocks until all items in the Queue have been gotten and processed.
|
'''Blocks until all items in the Queue have been gotten and processed.
|
||||||
|
|
||||||
The count of unfinished tasks goes up whenever an item is added to the
|
The count of unfinished tasks goes up whenever an item is added to the
|
||||||
queue. The count goes down whenever a consumer thread calls task_done()
|
queue. The count goes down whenever a consumer thread calls task_done()
|
||||||
to indicate the item was retrieved and all work on it is complete.
|
to indicate the item was retrieved and all work on it is complete.
|
||||||
|
|
||||||
When the count of unfinished tasks drops to zero, join() unblocks.
|
When the count of unfinished tasks drops to zero, join() unblocks.
|
||||||
"""
|
'''
|
||||||
with self.all_tasks_done:
|
with self.all_tasks_done:
|
||||||
while self.unfinished_tasks:
|
while self.unfinished_tasks:
|
||||||
self.all_tasks_done.wait()
|
self.all_tasks_done.wait()
|
||||||
|
|
||||||
def qsize(self):
|
def qsize(self):
|
||||||
"""Return the approximate size of the queue (not reliable!)."""
|
'''Return the approximate size of the queue (not reliable!).'''
|
||||||
with self.mutex:
|
with self.mutex:
|
||||||
return self._qsize()
|
return self._qsize()
|
||||||
|
|
||||||
def empty(self):
|
def empty(self):
|
||||||
"""Return True if the queue is empty, False otherwise (not reliable!).
|
'''Return True if the queue is empty, False otherwise (not reliable!).
|
||||||
|
|
||||||
This method is likely to be removed at some point. Use qsize() == 0
|
This method is likely to be removed at some point. Use qsize() == 0
|
||||||
as a direct substitute, but be aware that either approach risks a race
|
as a direct substitute, but be aware that either approach risks a race
|
||||||
|
@ -96,25 +97,23 @@ class Queue:
|
||||||
|
|
||||||
To create code that needs to wait for all queued tasks to be
|
To create code that needs to wait for all queued tasks to be
|
||||||
completed, the preferred technique is to use the join() method.
|
completed, the preferred technique is to use the join() method.
|
||||||
|
'''
|
||||||
"""
|
|
||||||
with self.mutex:
|
with self.mutex:
|
||||||
return not self._qsize()
|
return not self._qsize()
|
||||||
|
|
||||||
def full(self):
|
def full(self):
|
||||||
"""Return True if the queue is full, False otherwise (not reliable!).
|
'''Return True if the queue is full, False otherwise (not reliable!).
|
||||||
|
|
||||||
This method is likely to be removed at some point. Use qsize() >= n
|
This method is likely to be removed at some point. Use qsize() >= n
|
||||||
as a direct substitute, but be aware that either approach risks a race
|
as a direct substitute, but be aware that either approach risks a race
|
||||||
condition where a queue can shrink before the result of full() or
|
condition where a queue can shrink before the result of full() or
|
||||||
qsize() can be used.
|
qsize() can be used.
|
||||||
|
'''
|
||||||
"""
|
|
||||||
with self.mutex:
|
with self.mutex:
|
||||||
return 0 < self.maxsize <= self._qsize()
|
return 0 < self.maxsize <= self._qsize()
|
||||||
|
|
||||||
def put(self, item, block=True, timeout=None):
|
def put(self, item, block=True, timeout=None):
|
||||||
"""Put an item into the queue.
|
'''Put an item into the queue.
|
||||||
|
|
||||||
If optional args 'block' is true and 'timeout' is None (the default),
|
If optional args 'block' is true and 'timeout' is None (the default),
|
||||||
block if necessary until a free slot is available. If 'timeout' is
|
block if necessary until a free slot is available. If 'timeout' is
|
||||||
|
@ -123,7 +122,7 @@ class Queue:
|
||||||
Otherwise ('block' is false), put an item on the queue if a free slot
|
Otherwise ('block' is false), put an item on the queue if a free slot
|
||||||
is immediately available, else raise the Full exception ('timeout'
|
is immediately available, else raise the Full exception ('timeout'
|
||||||
is ignored in that case).
|
is ignored in that case).
|
||||||
"""
|
'''
|
||||||
with self.not_full:
|
with self.not_full:
|
||||||
if self.maxsize > 0:
|
if self.maxsize > 0:
|
||||||
if not block:
|
if not block:
|
||||||
|
@ -146,7 +145,7 @@ class Queue:
|
||||||
self.not_empty.notify()
|
self.not_empty.notify()
|
||||||
|
|
||||||
def get(self, block=True, timeout=None):
|
def get(self, block=True, timeout=None):
|
||||||
"""Remove and return an item from the queue.
|
'''Remove and return an item from the queue.
|
||||||
|
|
||||||
If optional args 'block' is true and 'timeout' is None (the default),
|
If optional args 'block' is true and 'timeout' is None (the default),
|
||||||
block if necessary until an item is available. If 'timeout' is
|
block if necessary until an item is available. If 'timeout' is
|
||||||
|
@ -155,7 +154,7 @@ class Queue:
|
||||||
Otherwise ('block' is false), return an item if one is immediately
|
Otherwise ('block' is false), return an item if one is immediately
|
||||||
available, else raise the Empty exception ('timeout' is ignored
|
available, else raise the Empty exception ('timeout' is ignored
|
||||||
in that case).
|
in that case).
|
||||||
"""
|
'''
|
||||||
with self.not_empty:
|
with self.not_empty:
|
||||||
if not block:
|
if not block:
|
||||||
if not self._qsize():
|
if not self._qsize():
|
||||||
|
@ -177,19 +176,19 @@ class Queue:
|
||||||
return item
|
return item
|
||||||
|
|
||||||
def put_nowait(self, item):
|
def put_nowait(self, item):
|
||||||
"""Put an item into the queue without blocking.
|
'''Put an item into the queue without blocking.
|
||||||
|
|
||||||
Only enqueue the item if a free slot is immediately available.
|
Only enqueue the item if a free slot is immediately available.
|
||||||
Otherwise raise the Full exception.
|
Otherwise raise the Full exception.
|
||||||
"""
|
'''
|
||||||
return self.put(item, block=False)
|
return self.put(item, block=False)
|
||||||
|
|
||||||
def get_nowait(self):
|
def get_nowait(self):
|
||||||
"""Remove and return an item from the queue without blocking.
|
'''Remove and return an item from the queue without blocking.
|
||||||
|
|
||||||
Only get an item if one is immediately available. Otherwise
|
Only get an item if one is immediately available. Otherwise
|
||||||
raise the Empty exception.
|
raise the Empty exception.
|
||||||
"""
|
'''
|
||||||
return self.get(block=False)
|
return self.get(block=False)
|
||||||
|
|
||||||
# Override these methods to implement other queue organizations
|
# Override these methods to implement other queue organizations
|
||||||
|
|
Loading…
Reference in New Issue