Merge lp:~eday/burrow/doc-updates into lp:burrow

[Eric Day]

More docs for backend modules.

=== modified file 'burrow/backend/__init__.py'
--- burrow/backend/__init__.py	2011-08-19 00:07:39 +0000
+++ burrow/backend/__init__.py	2011-08-24 17:01:25 +0000
@@ -20,6 +20,9 @@
 
 import burrow.common
 
+# Since this is an interface, arguments are unused. Ignore warnings in pylint.
+# pylint: disable=W0613
+
 
 class Backend(burrow.common.Module):
     '''Interface that backend modules must implement.'''
@@ -34,48 +37,165 @@
         thread_pool.spawn_n(self._clean)
 
     def delete_accounts(self, filters=None):
-        '''Delete accounts, which includes all queues and messages
-        for the accounts. With no filters, this will delete all data
-        for the entire server, so it should be used with caution.
+        '''Delete accounts, which includes all queues and messages within
+        the accounts. With no filters, this will delete all data for the
+        entire server, so it should be used with caution.
 
         :param filters: Optional dict of filters for the request. Valid
-        filters are 'marker', 'limit', and 'detail'. Valid values
-        for 'detail' are 'none', 'id', and 'all'. Default value for
-        'detail' is 'none'.
-        :returns: Generator which will loop through all messages if
-        'detail' is not 'none'.
+            filters are 'marker', 'limit', and 'detail'. The 'marker'
+            value is the last seen account ID for use in pagination,
+            and only accounts after this ID will be affected. If the
+            'marker' value is not given or not found, it will start from
+            the beginning. The 'limit' value is the number of accounts
+            to delete for the request. If 'limit' is not given, it will
+            delete them all. Valid values for 'detail' are 'none', 'id',
+            and 'all'. Default value for 'detail' is 'none'.
+
+        :returns: Generator which will loop through all accounts if
+            'detail' is not 'none'. If 'detail' is 'none', the generator
+            will stop on the first iteration, but it still must be called
+            to finish the request.
         '''
         return []
 
     def get_accounts(self, filters=None):
+        '''Get a list of accounts, possibly filtered. This uses the same
+        parameters and return type as :func:`delete_accounts()`, except
+        the default value for 'detail' in 'filters' is 'id'.'''
         return []
 
     def delete_queues(self, account, filters=None):
+        '''Delete queues within an account, which includes all messages
+        within the queues. With no filters, this will delete all data
+        for the entire account, so it should be used with caution.
+
+        :param account: Account to delete the queues from.
+
+        :param filters: Optional dict of filters for the request. Valid
+            filters are 'marker', 'limit', and 'detail'. The 'marker'
+            value is the last seen queue ID for use in pagination, and
+            only queues after this ID will be affected. If the 'marker'
+            value is not given or not found, it will start from the
+            beginning. The 'limit' value is the number of queues to
+            delete for the request. If 'limit' is not given, it will
+            delete them all. Valid values for 'detail' are 'none', 'id',
+            and 'all'. Default value for 'detail' is 'none'.
+
+        :returns: Generator which will loop through all queues if 'detail'
+            is not 'none'. If 'detail' is 'none', the generator will stop
+            on the first iteration, but it still must be called to finish
+            the request.
+        '''
         return []
 
     def get_queues(self, account, filters=None):
+        '''Get a list of queues, possibly filtered. This uses the same
+        parameters and return type as :func:`delete_queues()`, except
+        the default value for 'detail' in 'filters' is 'id'.'''
         return []
 
     def delete_messages(self, account, queue, filters=None):
+        '''Delete messages within a queue. With no filters, this will
+        delete all messages in the queue, so it should be used with
+        caution.
+
+        :param account: Account to delete the messages from.
+
+        :param queue: Queue within the given account to delete the
+            messages from.
+
+        :param filters: Optional dict of filters for the request. Valid
+            filters are 'marker', 'limit', 'match_hidden', 'wait', and
+            'detail'. The 'marker' value is the last seen message ID for
+            use in pagination, and only messages after this ID will be
+            affected. If the 'marker' value is not given or not found,
+            it will start from the beginning. The 'limit' value is the
+            number of messages to delete for the request. If 'limit'
+            is not given, it will delete them all. If 'match_hidden'
+            is True, the request will match all messages, even if their
+            'hide' value is non-zero, otherwise messages with a 'hide'
+            value of non-zero are skipped. If 'wait' is given, this is the
+            number of seconds for the request to wait for a message if no
+            messages can be found. Valid values for 'detail' are 'none',
+            'id', 'attributes', 'body', and 'all'. Default value for
+            'detail' is 'none'.
+
+        :returns: Generator which will loop through all messages if 'detail'
+            is not 'none'. If 'detail' is 'none', the generator will stop
+            on the first iteration, but it still must be called to finish
+            the request.
+        '''
         return []
 
     def get_messages(self, account, queue, filters=None):
+        '''Get a list of messages, possibly filtered. This uses the same
+        parameters and return type as :func:`delete_messages()`, except
+        the default value for 'detail' in 'filters' is 'all'.'''
         return []
 
     def update_messages(self, account, queue, attributes, filters=None):
+        '''Update a list of messages, possibly filtered. In addition to
+        the parameters and return type used in :func:`delete_messages()`,
+        this also requires:
+
+        :param attributes: Attributes to set as described in
+            :func:`create_message()`
+        '''
         return []
 
     def create_message(self, account, queue, message, body, attributes=None):
+        '''Create a new message in the given account and queue.
+
+        :param account: Account to create the messages in.
+
+        :param queue: Queue within the given account to create the
+            messages in.
+
+        :param message: Message ID to use within the queue, which is
+            always unique. When a message of the same ID already exists,
+            the old message is overwritten with this new one.
+
+        :param body: Body of the message.
+
+        :param attributes: A dict of initial attributes to set. Valid
+            attributes are 'ttl' and 'hide'. The value of 'ttl' is the
+            number of seconds from when the request is made for the message
+            to be removed automatically by the server. The value of 'hide'
+            is the number of seconds from when the request is made for
+            the message to stay hidden from requests that do not have the
+            'match_hidden' filter given as True.
+
+        :returns: True if the message was created, False if a message
+            with the same ID existed and was replaced.
+        '''
         return True
 
     def delete_message(self, account, queue, message, filters=None):
+        '''Same as :func:`delete_messages()`, except only delete the
+        given message ID.
+
+        :returns: The message detail according to 'detail' in 'filters,
+            or None if 'detail' is 'none'.
+        '''
         return None
 
     def get_message(self, account, queue, message, filters=None):
+        '''Same as :func:`get_messages()`, except only get the given
+        message ID.
+
+        :returns: The message detail according to 'detail' in 'filters,
+            or None if 'detail' is 'none'.
+        '''
         return None
 
     def update_message(self, account, queue, message, attributes,
         filters=None):
+        '''Same as :func:`update_messages()`, except only update the
+        given message ID.
+
+        :returns: The message detail according to 'detail' in 'filters,
+            or None if 'detail' is 'none'.
+        '''
         return None
 
     def clean(self):
@@ -91,6 +211,7 @@
             eventlet.sleep(1)
 
     def _get_attributes(self, attributes, ttl=None, hide=None):
+        '''Helper method to parse attributes for implementations to use.'''
         if attributes is not None:
             ttl = attributes.get('ttl', ttl)
             hide = attributes.get('hide', hide)
@@ -101,6 +222,8 @@
         return ttl, hide
 
     def _get_detail(self, filters, default=None):
+        '''Helper method to parse account and queue detail for
+        implementations to use.'''
         detail = default if filters is None else filters.get('detail', default)
         if detail == 'none':
             detail = None
@@ -109,6 +232,8 @@
         return detail
 
     def _get_message_detail(self, filters, default=None):
+        '''Helper method to parse message detail for implementations
+        to use.'''
         detail = default if filters is None else filters.get('detail', default)
         options = ['id', 'attributes', 'body', 'all']
         if detail == 'none':
@@ -122,7 +247,7 @@
         a visible message.'''
         queue = '%s/%s' % (account, queue)
         if queue in self.queues:
-            for count in xrange(0, self.queues[queue].getting()):
+            for _count in xrange(0, self.queues[queue].getting()):
                 self.queues[queue].put(0)
 
     def wait(self, account, queue, seconds):
@@ -139,17 +264,21 @@
 
 
 def wait_without_attributes(method):
-    def wrapper(self, account, queue, filters=None):
+    '''Decorator that will wait for messages with the method does not
+    take attributes.'''
+    def __wrapper__(self, account, queue, filters=None):
         original = lambda: method(self, account, queue, filters)
         return wait(self, account, queue, filters, original)
-    return wrapper
+    return __wrapper__
 
 
 def wait_with_attributes(method):
-    def wrapper(self, account, queue, attributes, filters=None):
+    '''Decorator that will wait for messages with the method takes
+    attributes.'''
+    def __wrapper__(self, account, queue, attributes, filters=None):
         original = lambda: method(self, account, queue, attributes, filters)
         return wait(self, account, queue, filters, original)
-    return wrapper
+    return __wrapper__
 
 
 def wait(self, account, queue, filters, method):
@@ -173,8 +302,11 @@
 
 
 class NotFound(Exception):
+    '''Raised when an account, queue, or message can not be found.'''
     pass
 
 
 class InvalidArguments(Exception):
+    '''Raised when the given arguments are invalid, usually from attributes
+    or filters.'''
     pass

=== modified file 'burrow/backend/http.py'
--- burrow/backend/http.py	2011-08-19 00:07:39 +0000
+++ burrow/backend/http.py	2011-08-24 17:01:25 +0000
@@ -109,6 +109,7 @@
         pass
 
     def _add_parameters(self, url, attributes=None, filters=None):
+        '''Add attributes and filters on to the URL as query parameters.'''
         separator = '?'
         if attributes is not None:
             parameters = ['ttl', 'hide']
@@ -127,6 +128,7 @@
         return url
 
     def _request(self, method, url, *args, **kwargs):
+        '''Perform the request and handle the response.'''
         connection = httplib.HTTPConnection(*self.server)
         connection.request(method, '/v1.0' + url, *args, **kwargs)
         response = connection.getresponse()

=== modified file 'burrow/backend/memory.py'
--- burrow/backend/memory.py	2011-08-19 00:07:39 +0000
+++ burrow/backend/memory.py	2011-08-24 17:01:25 +0000
@@ -175,6 +175,7 @@
         self.prev = None
 
     def detail(self, detail):
+        '''Format detail response for this item.'''
         if detail == 'id':
             return self.id
         elif detail == 'all':
@@ -193,6 +194,7 @@
         self.index = {}
 
     def add(self, item):
+        '''Add a new item to the list.'''
         if self.first is None:
             self.first = item
         if self.last is not None:
@@ -203,9 +205,11 @@
         return item
 
     def count(self):
+        '''Return a count of the number of items in the list.'''
         return len(self.index)
 
     def delete(self, id):
+        '''Delete an item from the list by id.'''
         item = self.index.pop(id)
         if item.next is not None:
             item.next.prev = item.prev
@@ -217,6 +221,7 @@
             self.last = item.prev
 
     def get(self, id, create=False):
+        '''Get an item from the list by id.'''
         if id in self.index:
             return self.index[id]
         elif create:
@@ -224,6 +229,7 @@
         raise burrow.backend.NotFound()
 
     def iter(self, filters=None):
+        '''Iterate through all items in the list, possibly filtered.'''
         if filters is None:
             marker = None
             limit = None
@@ -245,6 +251,7 @@
             item = item.next
 
     def reset(self):
+        '''Remove all items in the list.'''
         if self.count() == 0:
             raise burrow.backend.NotFound()
         self.first = None
@@ -253,6 +260,7 @@
 
 
 class Account(Item):
+    '''A type of item representing an account.'''
 
     def __init__(self, id=None):
         super(Account, self).__init__(id)
@@ -260,10 +268,12 @@
 
 
 class Accounts(IndexedList):
+    '''A type of list representing an account list.'''
 
     item_class = Account
 
     def delete_queue(self, account, queue):
+        '''Delete a queue within the given account.'''
         account = self.get(account)
         if account is not None:
             account.queues.delete(queue)
@@ -271,6 +281,7 @@
                 self.delete(account.id)
 
     def get_queue(self, account, queue, create=False):
+        '''Get a queue within the given the account.'''
         if account in self.index:
             account = self.index[account]
         elif create:
@@ -281,6 +292,7 @@
 
 
 class Queue(Item):
+    '''A type of item representing a queue.'''
 
     def __init__(self, id=None):
         super(Queue, self).__init__(id)
@@ -288,11 +300,13 @@
 
 
 class Queues(IndexedList):
+    '''A type of list representing a queue list.'''
 
     item_class = Queue
 
 
 class Message(Item):
+    '''A type of item representing a message.'''
 
     def __init__(self, id=None):
         super(Message, self).__init__(id)
@@ -319,6 +333,7 @@
 
 
 class Messages(IndexedList):
+    '''A type of list representing a message list.'''
 
     item_class = Message
 

=== modified file 'burrow/backend/sqlite.py'
--- burrow/backend/sqlite.py	2011-08-19 00:07:39 +0000
+++ burrow/backend/sqlite.py	2011-08-24 17:01:25 +0000
@@ -30,6 +30,8 @@
 
 
 class Backend(burrow.backend.Backend):
+    '''Backend implemention that uses SQLite to store the account, queue,
+    and message data.'''
 
     def __init__(self, config):
         super(Backend, self).__init__(config)
@@ -83,6 +85,8 @@
             self._delete_accounts(ids)
 
     def _delete_accounts(self, ids):
+        '''Delete all accounts with the given row IDs, which includes
+        cascading deletes for all queues and messages as well.'''
         ids = tuple(ids)
         query_values = '(?' + (',?' * (len(ids) - 1)) + ')'
         queue_ids = []
@@ -103,6 +107,7 @@
         self.db.execute(query + query_values, ids)
 
     def _detail(self, row, detail):
+        '''Format the account or queue detail from the given row.'''
         if detail == 'id':
             return row[0]
         elif detail == 'all':
@@ -117,6 +122,8 @@
                 yield self._detail(row, detail)
 
     def _get_accounts(self, query, filters):
+        '''Build the SQL query to get accounts and check for empty
+        responses.'''
         values = tuple()
         if filters is None:
             marker = None
@@ -142,6 +149,7 @@
             raise burrow.backend.NotFound()
 
     def _get_account(self, account):
+        '''Get the rowid for a given account ID.'''
         query = 'SELECT rowid FROM accounts WHERE account=?'
         rows = self.db.execute(query, (account,)).fetchall()
         if len(rows) == 0:
@@ -165,6 +173,8 @@
         self._check_empty_account(account_rowid)
 
     def _delete_queues(self, ids):
+        '''Delete all queues with the given row IDs, which includes
+        cascading deletes for all messages as well.'''
         ids = tuple(ids)
         query_values = '(?' + (',?' * (len(ids) - 1)) + ')'
         query = 'DELETE FROM messages WHERE queue IN '
@@ -173,6 +183,7 @@
         self.db.execute(query + query_values, ids)
 
     def _check_empty_account(self, account_rowid):
+        '''Check to see if an account is empty, and if so, remove it.'''
         query = 'SELECT rowid FROM queues WHERE account=? LIMIT 1'
         if len(self.db.execute(query, (account_rowid,)).fetchall()) == 0:
             query = 'DELETE FROM accounts WHERE rowid=?'
@@ -187,6 +198,8 @@
                 yield self._detail(row, detail)
 
     def _get_queues(self, query, account_rowid, filters):
+        '''Build the SQL query to get queues and check for empty
+        responses.'''
         query += ' WHERE account=?'
         values = (account_rowid,)
         if filters is None:
@@ -213,6 +226,7 @@
             raise burrow.backend.NotFound()
 
     def _get_queue(self, account_rowid, queue):
+        '''Get the rowid for a given queue ID.'''
         query = 'SELECT rowid FROM queues WHERE account=? AND queue=?'
         rows = self.db.execute(query, (account_rowid, queue)).fetchall()
         if len(rows) == 0:
@@ -238,18 +252,21 @@
         self._check_empty_queue(account_rowid, queue_rowid)
 
     def _delete_messages(self, ids):
+        '''Delete all messages with the given row IDs.'''
         ids = tuple(ids)
         query_values = '(?' + (',?' * (len(ids) - 1)) + ')'
         query = 'DELETE FROM messages WHERE rowid IN '
         self.db.execute(query + query_values, ids)
 
     def _check_empty_queue(self, account_rowid, queue_rowid):
+        '''Check to see if a queue is empty, and if so, remove it.'''
         query = 'SELECT rowid FROM messages WHERE queue=? LIMIT 1'
         if len(self.db.execute(query, (queue_rowid,)).fetchall()) == 0:
             self.db.execute('DELETE FROM queues WHERE rowid=?', (queue_rowid,))
             self._check_empty_account(account_rowid)
 
     def _message_detail(self, row, detail):
+        '''Format the message detail from the given row.'''
         if detail == 'id':
             return row[0]
         elif detail == 'body':
@@ -277,6 +294,8 @@
                 yield self._message_detail(row, detail)
 
     def _get_messages(self, query, queue_rowid, filters):
+        '''Build the SQL query to get messages and check for empty
+        responses.'''
         query += ' WHERE queue=?'
         values = (queue_rowid,)
         if filters is None:
@@ -307,6 +326,7 @@
             raise burrow.backend.NotFound()
 
     def _get_message(self, queue_rowid, message, full=False):
+        '''Get the rowid for a given message ID.'''
         if full:
             query = 'SELECT rowid,message,ttl,hide,body'
         else:
@@ -348,6 +368,7 @@
             self.notify(account, queue)
 
     def _update_messages(self, ttl, hide, ids):
+        '''Build the SQL query to update messages.'''
         query = 'UPDATE messages SET '
         query_values = ' WHERE rowid IN (?' + (',?' * (len(ids) - 1)) + ')'
         values = []