~hudson-openstack/burrow/trunk

« back to all changes in this revision

Viewing changes to burrow/backend/__init__.py

  • Committer: Tarmac
  • Author(s): Eric Day
  • Date: 2011-08-24 17:08:00 UTC
  • mfrom: (33.1.4 doc-updates)
  • Revision ID: tarmac-20110824170800-1acaswi4cs9svbu0
More docs for backend modules.

Show diffs side-by-side

added added

removed removed

Lines of Context:
20
20
 
21
21
import burrow.common
22
22
 
 
23
# Since this is an interface, arguments are unused. Ignore warnings in pylint.
 
24
# pylint: disable=W0613
 
25
 
23
26
 
24
27
class Backend(burrow.common.Module):
25
28
    '''Interface that backend modules must implement.'''
34
37
        thread_pool.spawn_n(self._clean)
35
38
 
36
39
    def delete_accounts(self, filters=None):
37
 
        '''Delete accounts, which includes all queues and messages
38
 
        for the accounts. With no filters, this will delete all data
39
 
        for the entire server, so it should be used with caution.
 
40
        '''Delete accounts, which includes all queues and messages within
 
41
        the accounts. With no filters, this will delete all data for the
 
42
        entire server, so it should be used with caution.
40
43
 
41
44
        :param filters: Optional dict of filters for the request. Valid
42
 
        filters are 'marker', 'limit', and 'detail'. Valid values
43
 
        for 'detail' are 'none', 'id', and 'all'. Default value for
44
 
        'detail' is 'none'.
45
 
        :returns: Generator which will loop through all messages if
46
 
        'detail' is not 'none'.
 
45
            filters are 'marker', 'limit', and 'detail'. The 'marker'
 
46
            value is the last seen account ID for use in pagination,
 
47
            and only accounts after this ID will be affected. If the
 
48
            'marker' value is not given or not found, it will start from
 
49
            the beginning. The 'limit' value is the number of accounts
 
50
            to delete for the request. If 'limit' is not given, it will
 
51
            delete them all. Valid values for 'detail' are 'none', 'id',
 
52
            and 'all'. Default value for 'detail' is 'none'.
 
53
 
 
54
        :returns: Generator which will loop through all accounts if
 
55
            'detail' is not 'none'. If 'detail' is 'none', the generator
 
56
            will stop on the first iteration, but it still must be called
 
57
            to finish the request.
47
58
        '''
48
59
        return []
49
60
 
50
61
    def get_accounts(self, filters=None):
 
62
        '''Get a list of accounts, possibly filtered. This uses the same
 
63
        parameters and return type as :func:`delete_accounts()`, except
 
64
        the default value for 'detail' in 'filters' is 'id'.'''
51
65
        return []
52
66
 
53
67
    def delete_queues(self, account, filters=None):
 
68
        '''Delete queues within an account, which includes all messages
 
69
        within the queues. With no filters, this will delete all data
 
70
        for the entire account, so it should be used with caution.
 
71
 
 
72
        :param account: Account to delete the queues from.
 
73
 
 
74
        :param filters: Optional dict of filters for the request. Valid
 
75
            filters are 'marker', 'limit', and 'detail'. The 'marker'
 
76
            value is the last seen queue ID for use in pagination, and
 
77
            only queues after this ID will be affected. If the 'marker'
 
78
            value is not given or not found, it will start from the
 
79
            beginning. The 'limit' value is the number of queues to
 
80
            delete for the request. If 'limit' is not given, it will
 
81
            delete them all. Valid values for 'detail' are 'none', 'id',
 
82
            and 'all'. Default value for 'detail' is 'none'.
 
83
 
 
84
        :returns: Generator which will loop through all queues if 'detail'
 
85
            is not 'none'. If 'detail' is 'none', the generator will stop
 
86
            on the first iteration, but it still must be called to finish
 
87
            the request.
 
88
        '''
54
89
        return []
55
90
 
56
91
    def get_queues(self, account, filters=None):
 
92
        '''Get a list of queues, possibly filtered. This uses the same
 
93
        parameters and return type as :func:`delete_queues()`, except
 
94
        the default value for 'detail' in 'filters' is 'id'.'''
57
95
        return []
58
96
 
59
97
    def delete_messages(self, account, queue, filters=None):
 
98
        '''Delete messages within a queue. With no filters, this will
 
99
        delete all messages in the queue, so it should be used with
 
100
        caution.
 
101
 
 
102
        :param account: Account to delete the messages from.
 
103
 
 
104
        :param queue: Queue within the given account to delete the
 
105
            messages from.
 
106
 
 
107
        :param filters: Optional dict of filters for the request. Valid
 
108
            filters are 'marker', 'limit', 'match_hidden', 'wait', and
 
109
            'detail'. The 'marker' value is the last seen message ID for
 
110
            use in pagination, and only messages after this ID will be
 
111
            affected. If the 'marker' value is not given or not found,
 
112
            it will start from the beginning. The 'limit' value is the
 
113
            number of messages to delete for the request. If 'limit'
 
114
            is not given, it will delete them all. If 'match_hidden'
 
115
            is True, the request will match all messages, even if their
 
116
            'hide' value is non-zero, otherwise messages with a 'hide'
 
117
            value of non-zero are skipped. If 'wait' is given, this is the
 
118
            number of seconds for the request to wait for a message if no
 
119
            messages can be found. Valid values for 'detail' are 'none',
 
120
            'id', 'attributes', 'body', and 'all'. Default value for
 
121
            'detail' is 'none'.
 
122
 
 
123
        :returns: Generator which will loop through all messages if 'detail'
 
124
            is not 'none'. If 'detail' is 'none', the generator will stop
 
125
            on the first iteration, but it still must be called to finish
 
126
            the request.
 
127
        '''
60
128
        return []
61
129
 
62
130
    def get_messages(self, account, queue, filters=None):
 
131
        '''Get a list of messages, possibly filtered. This uses the same
 
132
        parameters and return type as :func:`delete_messages()`, except
 
133
        the default value for 'detail' in 'filters' is 'all'.'''
63
134
        return []
64
135
 
65
136
    def update_messages(self, account, queue, attributes, filters=None):
 
137
        '''Update a list of messages, possibly filtered. In addition to
 
138
        the parameters and return type used in :func:`delete_messages()`,
 
139
        this also requires:
 
140
 
 
141
        :param attributes: Attributes to set as described in
 
142
            :func:`create_message()`
 
143
        '''
66
144
        return []
67
145
 
68
146
    def create_message(self, account, queue, message, body, attributes=None):
 
147
        '''Create a new message in the given account and queue.
 
148
 
 
149
        :param account: Account to create the messages in.
 
150
 
 
151
        :param queue: Queue within the given account to create the
 
152
            messages in.
 
153
 
 
154
        :param message: Message ID to use within the queue, which is
 
155
            always unique. When a message of the same ID already exists,
 
156
            the old message is overwritten with this new one.
 
157
 
 
158
        :param body: Body of the message.
 
159
 
 
160
        :param attributes: A dict of initial attributes to set. Valid
 
161
            attributes are 'ttl' and 'hide'. The value of 'ttl' is the
 
162
            number of seconds from when the request is made for the message
 
163
            to be removed automatically by the server. The value of 'hide'
 
164
            is the number of seconds from when the request is made for
 
165
            the message to stay hidden from requests that do not have the
 
166
            'match_hidden' filter given as True.
 
167
 
 
168
        :returns: True if the message was created, False if a message
 
169
            with the same ID existed and was replaced.
 
170
        '''
69
171
        return True
70
172
 
71
173
    def delete_message(self, account, queue, message, filters=None):
 
174
        '''Same as :func:`delete_messages()`, except only delete the
 
175
        given message ID.
 
176
 
 
177
        :returns: The message detail according to 'detail' in 'filters,
 
178
            or None if 'detail' is 'none'.
 
179
        '''
72
180
        return None
73
181
 
74
182
    def get_message(self, account, queue, message, filters=None):
 
183
        '''Same as :func:`get_messages()`, except only get the given
 
184
        message ID.
 
185
 
 
186
        :returns: The message detail according to 'detail' in 'filters,
 
187
            or None if 'detail' is 'none'.
 
188
        '''
75
189
        return None
76
190
 
77
191
    def update_message(self, account, queue, message, attributes,
78
192
        filters=None):
 
193
        '''Same as :func:`update_messages()`, except only update the
 
194
        given message ID.
 
195
 
 
196
        :returns: The message detail according to 'detail' in 'filters,
 
197
            or None if 'detail' is 'none'.
 
198
        '''
79
199
        return None
80
200
 
81
201
    def clean(self):
91
211
            eventlet.sleep(1)
92
212
 
93
213
    def _get_attributes(self, attributes, ttl=None, hide=None):
 
214
        '''Helper method to parse attributes for implementations to use.'''
94
215
        if attributes is not None:
95
216
            ttl = attributes.get('ttl', ttl)
96
217
            hide = attributes.get('hide', hide)
101
222
        return ttl, hide
102
223
 
103
224
    def _get_detail(self, filters, default=None):
 
225
        '''Helper method to parse account and queue detail for
 
226
        implementations to use.'''
104
227
        detail = default if filters is None else filters.get('detail', default)
105
228
        if detail == 'none':
106
229
            detail = None
109
232
        return detail
110
233
 
111
234
    def _get_message_detail(self, filters, default=None):
 
235
        '''Helper method to parse message detail for implementations
 
236
        to use.'''
112
237
        detail = default if filters is None else filters.get('detail', default)
113
238
        options = ['id', 'attributes', 'body', 'all']
114
239
        if detail == 'none':
122
247
        a visible message.'''
123
248
        queue = '%s/%s' % (account, queue)
124
249
        if queue in self.queues:
125
 
            for count in xrange(0, self.queues[queue].getting()):
 
250
            for _count in xrange(0, self.queues[queue].getting()):
126
251
                self.queues[queue].put(0)
127
252
 
128
253
    def wait(self, account, queue, seconds):
139
264
 
140
265
 
141
266
def wait_without_attributes(method):
142
 
    def wrapper(self, account, queue, filters=None):
 
267
    '''Decorator that will wait for messages with the method does not
 
268
    take attributes.'''
 
269
    def __wrapper__(self, account, queue, filters=None):
143
270
        original = lambda: method(self, account, queue, filters)
144
271
        return wait(self, account, queue, filters, original)
145
 
    return wrapper
 
272
    return __wrapper__
146
273
 
147
274
 
148
275
def wait_with_attributes(method):
149
 
    def wrapper(self, account, queue, attributes, filters=None):
 
276
    '''Decorator that will wait for messages with the method takes
 
277
    attributes.'''
 
278
    def __wrapper__(self, account, queue, attributes, filters=None):
150
279
        original = lambda: method(self, account, queue, attributes, filters)
151
280
        return wait(self, account, queue, filters, original)
152
 
    return wrapper
 
281
    return __wrapper__
153
282
 
154
283
 
155
284
def wait(self, account, queue, filters, method):
173
302
 
174
303
 
175
304
class NotFound(Exception):
 
305
    '''Raised when an account, queue, or message can not be found.'''
176
306
    pass
177
307
 
178
308
 
179
309
class InvalidArguments(Exception):
 
310
    '''Raised when the given arguments are invalid, usually from attributes
 
311
    or filters.'''
180
312
    pass