Debian Codegraph @

troveclient/apiclient/base.py

raw
1 # Copyright 2010 Jacob Kaplan-Moss
2 # Copyright 2011 OpenStack Foundation
3 # Copyright 2012 Grid Dynamics
4 # Copyright 2013 OpenStack Foundation
5 # All Rights Reserved.
6 #
7 # Licensed under the Apache License, Version 2.0 (the "License"); you may
8 # not use this file except in compliance with the License. You may obtain
9 # a copy of the License at
10 #
11 # http://www.apache.org/licenses/LICENSE-2.0
12 #
13 # Unless required by applicable law or agreed to in writing, software
14 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
16 # License for the specific language governing permissions and limitations
17 # under the License.
18
19 """
20 Base utilities to build API operation managers and objects on top of.
21 """
22
23 # E1102: %s is not callable
24 # pylint: disable=E1102
25
26 import abc
27 import copy
28
29 from oslo_utils import reflection
30 from oslo_utils import strutils
31 from urllib import parse
32
33 from troveclient.apiclient import exceptions
34
35
36 def getid(obj):
37 """Return id if argument is a Resource.
38
39 Abstracts the common pattern of allowing both an object or an object's ID
40 (UUID) as a parameter when dealing with relationships.
41 """
42 try:
43 if obj.uuid:
44 return obj.uuid
45 except AttributeError:
46 pass
47 try:
48 return obj.id
49 except AttributeError:
50 return obj
51
52
53 # TODO(aababilov): call run_hooks() in HookableMixin's child classes
54 class HookableMixin(object):
55 """Mixin so classes can register and run hooks."""
56 _hooks_map = {}
57
58 @classmethod
59 def add_hook(cls, hook_type, hook_func):
60 """Add a new hook of specified type.
61
62 :param cls: class that registers hooks
63 :param hook_type: hook type, e.g., '__pre_parse_args__'
64 :param hook_func: hook function
65 """
66 if hook_type not in cls._hooks_map:
67 cls._hooks_map[hook_type] = []
68
69 cls._hooks_map[hook_type].append(hook_func)
70
71 @classmethod
72 def run_hooks(cls, hook_type, *args, **kwargs):
73 """Run all hooks of specified type.
74
75 :param cls: class that registers hooks
76 :param hook_type: hook type, e.g., '__pre_parse_args__'
77 :param args: args to be passed to every hook function
78 :param kwargs: kwargs to be passed to every hook function
79 """
80 hook_funcs = cls._hooks_map.get(hook_type) or []
81 for hook_func in hook_funcs:
82 hook_func(*args, **kwargs)
83
84
85 class BaseManager(HookableMixin):
86 """Basic manager type providing common operations.
87
88 Managers interact with a particular type of API (servers, flavors, images,
89 etc.) and provide CRUD operations for them.
90 """
91 resource_class = None
92
93 def __init__(self, client):
94 """Initializes BaseManager with `client`.
95
96 :param client: instance of BaseClient descendant for HTTP requests
97 """
98 super(BaseManager, self).__init__()
99 self.client = client
100
101 def _list(self, url, response_key, obj_class=None, json=None):
102 """List the collection.
103
104 :param url: a partial URL, e.g., '/servers'
105 :param response_key: the key to be looked up in response dictionary,
106 e.g., 'servers'
107 :param obj_class: class for constructing the returned objects
108 (self.resource_class will be used by default)
109 :param json: data that will be encoded as JSON and passed in POST
110 request (GET will be sent by default)
111 """
112 if json:
113 body = self.client.post(url, json=json).json()
114 else:
115 body = self.client.get(url).json()
116
117 if obj_class is None:
118 obj_class = self.resource_class
119
120 data = body[response_key]
121 # NOTE(ja): keystone returns values as list as {'values': [ ... ]}
122 # unlike other services which just return the list...
123 try:
124 data = data['values']
125 except (KeyError, TypeError):
126 pass
127
128 return [obj_class(self, res, loaded=True) for res in data if res]
129
130 def _get(self, url, response_key):
131 """Get an object from collection.
132
133 :param url: a partial URL, e.g., '/servers'
134 :param response_key: the key to be looked up in response dictionary,
135 e.g., 'server'
136 """
137 body = self.client.get(url).json()
138 return self.resource_class(self, body[response_key], loaded=True)
139
140 def _head(self, url):
141 """Retrieve request headers for an object.
142
143 :param url: a partial URL, e.g., '/servers'
144 """
145 resp = self.client.head(url)
146 return resp.status_code == 204
147
148 def _post(self, url, json, response_key, return_raw=False):
149 """Create an object.
150
151 :param url: a partial URL, e.g., '/servers'
152 :param json: data that will be encoded as JSON and passed in POST
153 request (GET will be sent by default)
154 :param response_key: the key to be looked up in response dictionary,
155 e.g., 'servers'
156 :param return_raw: flag to force returning raw JSON instead of
157 Python object of self.resource_class
158 """
159 body = self.client.post(url, json=json).json()
160 if return_raw:
161 return body[response_key]
162 return self.resource_class(self, body[response_key])
163
164 def _put(self, url, json=None, response_key=None):
165 """Update an object with PUT method.
166
167 :param url: a partial URL, e.g., '/servers'
168 :param json: data that will be encoded as JSON and passed in POST
169 request (GET will be sent by default)
170 :param response_key: the key to be looked up in response dictionary,
171 e.g., 'servers'
172 """
173 resp = self.client.put(url, json=json)
174 # PUT requests may not return a body
175 if resp.content:
176 body = resp.json()
177 if response_key is not None:
178 return self.resource_class(self, body[response_key])
179 else:
180 return self.resource_class(self, body)
181
182 def _patch(self, url, json=None, response_key=None):
183 """Update an object with PATCH method.
184
185 :param url: a partial URL, e.g., '/servers'
186 :param json: data that will be encoded as JSON and passed in POST
187 request (GET will be sent by default)
188 :param response_key: the key to be looked up in response dictionary,
189 e.g., 'servers'
190 """
191 body = self.client.patch(url, json=json).json()
192 if response_key is not None:
193 return self.resource_class(self, body[response_key])
194 else:
195 return self.resource_class(self, body)
196
197 def _delete(self, url):
198 """Delete an object.
199
200 :param url: a partial URL, e.g., '/servers/my-server'
201 """
202 return self.client.delete(url)
203
204
205 class ManagerWithFind(BaseManager, metaclass=abc.ABCMeta):
206 """Manager with additional `find()`/`findall()` methods."""
207
208 @abc.abstractmethod
209 def list(self):
210 pass
211
212 def find(self, **kwargs):
213 """Find a single item with attributes matching ``**kwargs``.
214
215 This isn't very efficient: it loads the entire list then filters on
216 the Python side.
217 """
218 matches = self.findall(**kwargs)
219 num_matches = len(matches)
220 if num_matches == 0:
221 msg = "No %s matching %s." % (self.resource_class.__name__, kwargs)
222 raise exceptions.NotFound(msg)
223 elif num_matches > 1:
224 raise exceptions.NoUniqueMatch()
225 else:
226 return matches[0]
227
228 def findall(self, **kwargs):
229 """Find all items with attributes matching ``**kwargs``.
230
231 This isn't very efficient: it loads the entire list then filters on
232 the Python side.
233 """
234 found = []
235 searches = kwargs.items()
236
237 for obj in self.list():
238 try:
239 if all(getattr(obj, attr) == value
240 for (attr, value) in searches):
241 found.append(obj)
242 except AttributeError:
243 continue
244
245 return found
246
247
248 class CrudManager(BaseManager):
249 """Base manager class for manipulating entities.
250
251 Children of this class are expected to define a `collection_key` and `key`.
252
253 - `collection_key`: Usually a plural noun by convention (e.g. `entities`);
254 used to refer collections in both URL's (e.g. `/v3/entities`) and JSON
255 objects containing a list of member resources (e.g. `{'entities': [{},
256 {}, {}]}`).
257 - `key`: Usually a singular noun by convention (e.g. `entity`); used to
258 refer to an individual member of the collection.
259
260 """
261 collection_key = None
262 key = None
263
264 def build_url(self, base_url=None, **kwargs):
265 """Builds a resource URL for the given kwargs.
266
267 Given an example collection where `collection_key = 'entities'` and
268 `key = 'entity'`, the following URL's could be generated.
269
270 By default, the URL will represent a collection of entities, e.g.::
271
272 /entities
273
274 If kwargs contains an `entity_id`, then the URL will represent a
275 specific member, e.g.::
276
277 /entities/{entity_id}
278
279 :param base_url: if provided, the generated URL will be appended to it
280 """
281 url = base_url if base_url is not None else ''
282
283 url += '/%s' % self.collection_key
284
285 # do we have a specific entity?
286 entity_id = kwargs.get('%s_id' % self.key)
287 if entity_id is not None:
288 url += '/%s' % entity_id
289
290 return url
291
292 def _filter_kwargs(self, kwargs):
293 """Drop null values and handle ids."""
294 for key, ref in kwargs.copy().items():
295 if ref is None:
296 kwargs.pop(key)
297 else:
298 if isinstance(ref, Resource):
299 kwargs.pop(key)
300 kwargs['%s_id' % key] = getid(ref)
301 return kwargs
302
303 def create(self, **kwargs):
304 kwargs = self._filter_kwargs(kwargs)
305 return self._post(
306 self.build_url(**kwargs),
307 {self.key: kwargs},
308 self.key)
309
310 def get(self, **kwargs):
311 kwargs = self._filter_kwargs(kwargs)
312 return self._get(
313 self.build_url(**kwargs),
314 self.key)
315
316 def head(self, **kwargs):
317 kwargs = self._filter_kwargs(kwargs)
318 return self._head(self.build_url(**kwargs))
319
320 def list(self, base_url=None, **kwargs):
321 """List the collection.
322
323 :param base_url: if provided, the generated URL will be appended to it
324 """
325 kwargs = self._filter_kwargs(kwargs)
326
327 return self._list(
328 '%(base_url)s%(query)s' % {
329 'base_url': self.build_url(base_url=base_url, **kwargs),
330 'query': '?%s' % parse.urlencode(kwargs) if kwargs else '',
331 },
332 self.collection_key)
333
334 def put(self, base_url=None, **kwargs):
335 """Update an element.
336
337 :param base_url: if provided, the generated URL will be appended to it
338 """
339 kwargs = self._filter_kwargs(kwargs)
340
341 return self._put(self.build_url(base_url=base_url, **kwargs))
342
343 def update(self, **kwargs):
344 kwargs = self._filter_kwargs(kwargs)
345 params = kwargs.copy()
346 params.pop('%s_id' % self.key)
347
348 return self._patch(
349 self.build_url(**kwargs),
350 {self.key: params},
351 self.key)
352
353 def delete(self, **kwargs):
354 kwargs = self._filter_kwargs(kwargs)
355
356 return self._delete(
357 self.build_url(**kwargs))
358
359 def find(self, base_url=None, **kwargs):
360 """Find a single item with attributes matching ``**kwargs``.
361
362 :param base_url: if provided, the generated URL will be appended to it
363 """
364 kwargs = self._filter_kwargs(kwargs)
365
366 rl = self._list(
367 '%(base_url)s%(query)s' % {
368 'base_url': self.build_url(base_url=base_url, **kwargs),
369 'query': '?%s' % parse.urlencode(kwargs) if kwargs else '',
370 },
371 self.collection_key)
372 num = len(rl)
373
374 if num == 0:
375 msg = "No %s matching %s." % (self.resource_class.__name__, kwargs)
376 raise exceptions.NotFound(404, msg)
377 elif num > 1:
378 raise exceptions.NoUniqueMatch
379 else:
380 return rl[0]
381
382
383 class Extension(HookableMixin):
384 """Extension descriptor."""
385
386 SUPPORTED_HOOKS = ('__pre_parse_args__', '__post_parse_args__')
387 manager_class = None
388
389 def __init__(self, name, module):
390 super(Extension, self).__init__()
391 self.name = name
392 self.module = module
393 self._parse_extension_module()
394
395 def _parse_extension_module(self):
396 self.manager_class = None
397 for attr_name, attr_value in self.module.__dict__.items():
398 if attr_name in self.SUPPORTED_HOOKS:
399 self.add_hook(attr_name, attr_value)
400 else:
401 try:
402 if issubclass(attr_value, BaseManager):
403 self.manager_class = attr_value
404 except TypeError:
405 pass
406
407 def __repr__(self):
408 return "<Extension '%s'>" % self.name
409
410
411 class Resource(object):
412 """Base class for OpenStack resources (tenant, user, etc.).
413
414 This is pretty much just a bag for attributes.
415 """
416
417 HUMAN_ID = False
418 NAME_ATTR = 'name'
419
420 def __init__(self, manager, info, loaded=False):
421 """Populate and bind to a manager.
422
423 :param manager: BaseManager object
424 :param info: dictionary representing resource attributes
425 :param loaded: prevent lazy-loading if set to True
426 """
427 self.manager = manager
428 self._info = info
429 self._add_details(info)
430 self._loaded = loaded
431
432 def __repr__(self):
433 reprkeys = sorted(k
434 for k in self.__dict__.keys()
435 if k[0] != '_' and k != 'manager')
436 info = ", ".join("%s=%s" % (k, getattr(self, k)) for k in reprkeys)
437 self_cls_name = reflection.get_class_name(self,
438 fully_qualified=False)
439 return "<%s %s>" % (self_cls_name, info)
440
441 @property
442 def human_id(self):
443 """Human-readable ID which can be used for bash completion.
444 """
445 if self.NAME_ATTR in self.__dict__ and self.HUMAN_ID:
446 return strutils.to_slug(getattr(self, self.NAME_ATTR))
447 return None
448
449 def _add_details(self, info):
450 for (k, v) in info.items():
451 try:
452 setattr(self, k, v)
453 self._info[k] = v
454 except AttributeError:
455 # In this case we already defined the attribute on the class
456 pass
457
458 def __getattr__(self, k):
459 if k == "__setstate__":
460 raise AttributeError(k)
461 if k not in self.__dict__:
462 # NOTE(bcwaldon): disallow lazy-loading if already loaded once
463 if not self.is_loaded:
464 self._get()
465 return self.__getattr__(k)
466
467 raise AttributeError(k)
468 else:
469 return self.__dict__[k]
470
471 def _get(self):
472 # set _loaded first ... so if we have to bail, we know we tried.
473 self._loaded = True
474 if not hasattr(self.manager, 'get'):
475 return
476
477 new = self.manager.get(self.id)
478 if new:
479 self._add_details(new._info)
480
481 def __eq__(self, other):
482 if not isinstance(other, Resource):
483 return NotImplemented
484 # two resources of different types are not equal
485 if not isinstance(other, self.__class__):
486 return False
487 if hasattr(self, 'id') and hasattr(other, 'id'):
488 return self.id == other.id
489 return self._info == other._info
490
491 @property
492 def is_loaded(self):
493 return self._loaded
494
495 def to_dict(self):
496 return copy.deepcopy(self._info)