Debian Codegraph @

zaqarclient/queues/v2/queues.py

raw
1 # Copyright (c) 2013 Red Hat, Inc.
2 #
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
6 #
7 # http://www.apache.org/licenses/LICENSE-2.0
8 #
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12 # implied.
13 # See the License for the specific language governing permissions and
14 # limitations under the License.
15
16 import re
17
18 from zaqarclient._i18n import _ # noqa
19 from zaqarclient.queues.v2 import claim as claim_api
20 from zaqarclient.queues.v2 import core
21 from zaqarclient.queues.v2 import iterator
22 from zaqarclient.queues.v2 import message
23
24 # NOTE(wanghao): This is copied from Zaqar server side, so if server have
25 # updated it someday, we should update it here to keep consistent.
26 QUEUE_NAME_REGEX = re.compile(r'^[a-zA-Z0-9_\-]+$')
27
28
29 class Queue:
30
31 message_module = message
32
33 def __init__(self, client, name, href=None, metadata=None,
34 auto_create=True, force_create=False):
35 """Initialize queue object
36
37 :param client: The client object of Zaqar.
38 :type client: `object`
39 :param name: Name of the queue.
40 :type name: str
41 :param href : Hypertext Reference.
42 :type href: str
43 :param metadata : A metadata object of the queue.
44 :type metadata: `dict`
45 :param auto_create: If create the queue automatically in database.
46 :type auto_create: `boolean`
47 :param force_create: If create the queue and skip the API version
48 check, which is useful for command line interface.
49 :type force_create: `boolean`
50 :returns: The queue object.
51 """
52 self.client = client
53
54 if name == "":
55 raise ValueError(_('Queue name does not have a value'))
56
57 if not QUEUE_NAME_REGEX.match(str(name)):
58 raise ValueError(_('The queue name may only contain ASCII '
59 'letters, digits, underscores and dashes.'))
60
61 # NOTE(flaper87) Queue Info
62 self._name = name
63 self._metadata = metadata
64 self._href = href
65
66 # NOTE(flwang): If force_create is True, then even though auto_create
67 # is not True, the queue should be created anyway.
68 if auto_create or force_create:
69 self.ensure_exists(force_create=force_create)
70
71 @property
72 def name(self):
73 return self._name
74
75 @property
76 def href(self):
77 return self._href
78
79 @property
80 def metadata_dict(self):
81 return dict(self.metadata())
82
83 def exists(self):
84 """Checks if the queue exists."""
85 req, trans = self.client._request_and_transport()
86 return core.queue_exists(trans, req, self._name)
87
88 def ensure_exists(self, force_create=False):
89 """Ensures a queue exists
90
91 This method is not race safe,
92 the queue could've been deleted
93 right after it was called.
94 """
95 req, trans = self.client._request_and_transport()
96 if force_create:
97 core.queue_create(trans, req, self._name)
98
99 def metadata(self, new_meta=None, force_reload=False):
100 """Get metadata and return it
101
102 :param new_meta: A dictionary containing
103 an updated metadata object. If present
104 the queue metadata will be updated in
105 remote server. If the new_meta is empty,
106 the metadata object will be cleared.
107 :type new_meta: `dict`
108 :param force_reload: Whether to ignored the
109 cached metadata and reload it from the
110 server.
111 :type force_reload: `bool`
112
113 :returns: The queue metadata.
114 """
115 req, trans = self.client._request_and_transport()
116
117 # TODO(flaper87): Cache with timeout
118 if new_meta is None and self._metadata and not force_reload:
119 return self._metadata
120 else:
121 self._metadata = core.queue_get(trans, req, self._name)
122
123 if new_meta is not None:
124 temp_metadata = self._metadata.copy()
125 changes = []
126 for key, value in new_meta.items():
127 # If key exists, replace it's value.
128 if self._metadata.get(key, None) is not None:
129 changes.append({'op': 'replace',
130 'path': '/metadata/%s' % key,
131 'value': value})
132 temp_metadata.pop(key)
133 # If not, add the new key.
134 else:
135 changes.append({'op': 'add',
136 'path': '/metadata/%s' % key,
137 'value': value})
138 # For the keys which are not included in the new metadata, remove
139 # them.
140 for key, value in temp_metadata.items():
141 changes.append({'op': 'remove',
142 'path': '/metadata/%s' % key})
143
144 self._metadata = core.queue_update(trans, req, self._name,
145 metadata=changes)
146
147 return self._metadata
148
149 @property
150 def stats(self):
151 req, trans = self.client._request_and_transport()
152 return core.queue_get_stats(trans, req, self._name)
153
154 def delete(self):
155 req, trans = self.client._request_and_transport()
156 core.queue_delete(trans, req, self._name)
157
158 # Messages API
159
160 def post(self, messages):
161 """Posts one or more messages to this queue
162
163 :param messages: One or more messages to post
164 :type messages: `list` or `dict`
165
166 :returns: A dict with the result of this operation.
167 :rtype: `dict`
168 """
169 if not isinstance(messages, list):
170 messages = [messages]
171
172 messages = {'messages': messages}
173
174 req, trans = self.client._request_and_transport()
175
176 # TODO(flaper87): Return a list of messages
177 return core.message_post(trans, req,
178 self._name, messages)
179
180 def message(self, message_id):
181 """Gets a message by id
182
183 :param message_id: Message's reference
184 :type message_id: str
185
186 :returns: A message
187 :rtype: `dict`
188 """
189 req, trans = self.client._request_and_transport()
190 msg = core.message_get(trans, req, self._name,
191 message_id)
192 return self.message_module.Message(self, **msg)
193
194 def messages(self, *messages, **params):
195 """Gets a list of messages from the server
196
197 This method returns a list of messages, it can be
198 used to retrieve a set of messages by id or to
199 walk through the active messages by using the
200 collection endpoint.
201
202 The `messages` and `params` params are mutually exclusive
203 and the former has the priority.
204
205 :param messages: List of messages' ids to retrieve.
206 :type messages: *args of str
207
208 :param params: Filters to use for getting messages
209 :type params: **kwargs dict.
210
211 :returns: List of messages
212 :rtype: `list`
213 """
214 req, trans = self.client._request_and_transport()
215
216 # TODO(flaper87): Return a MessageIterator.
217 # This iterator should handle limits, pagination
218 # and messages deserialization.
219
220 if messages:
221 msgs = core.message_get_many(trans, req,
222 self._name, messages)
223 else:
224 # NOTE(flaper87): It's safe to access messages
225 # directly. If something wrong happens, the core
226 # API will raise the right exceptions.
227 msgs = core.message_list(trans, req,
228 self._name,
229 **params)
230
231 return iterator._Iterator(self.client,
232 msgs,
233 'messages',
234 self.message_module.create_object(self))
235
236 def delete_messages(self, *messages):
237 """Deletes a set of messages from the server
238
239 :param messages: List of messages' ids to delete.
240 :type messages: *args of str
241 """
242
243 req, trans = self.client._request_and_transport()
244 return core.message_delete_many(trans, req, self._name,
245 set(messages))
246
247 def pop(self, count=1):
248 """Pop `count` messages from the server
249
250 :param count: Number of messages to pop.
251 :type count: int
252
253 :returns: List of messages
254 :rtype: `list`
255 """
256
257 req, trans = self.client._request_and_transport()
258 msgs = core.message_pop(trans, req, self._name, count=count)
259 return iterator._Iterator(self.client,
260 msgs,
261 'messages',
262 self.message_module.create_object(self))
263
264 def signed_url(self, paths=None, ttl_seconds=None, methods=None):
265 req, trans = self.client._request_and_transport()
266 return core.signed_url_create(trans, req, self._name, paths=paths,
267 ttl_seconds=ttl_seconds, methods=methods)
268
269 def subscriptions(self, detailed=False, marker=None, limit=20):
270 return self.client.subscriptions(queue_name=self._name,
271 detailed=detailed,
272 marker=marker,
273 limit=limit)
274
275 def purge(self, resource_types=None):
276 req, trans = self.client._request_and_transport()
277 core.queue_purge(trans, req, self._name,
278 resource_types=resource_types)
279
280 def claim(self, id=None, ttl=None, grace=None,
281 limit=None):
282 return claim_api.Claim(self, id=id, ttl=ttl, grace=grace, limit=limit)
283
284
285 def create_object(parent):
286 return lambda args: Queue(parent, args["name"], href=args.get("href"),
287 metadata=args.get("metadata"), auto_create=False)