| 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) |