keystone  18.0.0
About: OpenStack Keystone (Core Service: Identity) provides an authentication and authorization service for other OpenStack services. Provides a catalog of endpoints for all OpenStack services.
The "Victoria" series (maintained release).
  Fossies Dox: keystone-18.0.0.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

driver_hints.py
Go to the documentation of this file.
1 # Copyright 2013 OpenStack Foundation
2 # Copyright 2013 IBM Corp.
3 #
4 # Licensed under the Apache License, Version 2.0 (the "License"); you may
5 # not use this file except in compliance with the License. You may obtain
6 # a copy of the License at
7 #
8 # http://www.apache.org/licenses/LICENSE-2.0
9 #
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 # License for the specific language governing permissions and limitations
14 # under the License.
15 
16 import functools
17 
18 from keystone import exception
19 from keystone.i18n import _
20 
21 
22 def truncated(f):
23  """Ensure list truncation is detected in Driver list entity methods.
24 
25  This is designed to wrap Driver list_{entity} methods in order to
26  calculate if the resultant list has been truncated. Provided a limit dict
27  is found in the hints list, we increment the limit by one so as to ask the
28  wrapped function for one more entity than the limit, and then once the list
29  has been generated, we check to see if the original limit has been
30  exceeded, in which case we truncate back to that limit and set the
31  'truncated' boolean to 'true' in the hints limit dict.
32 
33  """
34  @functools.wraps(f)
35  def wrapper(self, hints, *args, **kwargs):
36  if not hasattr(hints, 'limit'):
38  _('Cannot truncate a driver call without hints list as '
39  'first parameter after self '))
40 
41  if hints.limit is None or hints.filters:
42  return f(self, hints, *args, **kwargs)
43 
44  # A limit is set, so ask for one more entry than we need
45  list_limit = hints.limit['limit']
46  hints.set_limit(list_limit + 1)
47  ref_list = f(self, hints, *args, **kwargs)
48 
49  # If we got more than the original limit then trim back the list and
50  # mark it truncated. In both cases, make sure we set the limit back
51  # to its original value.
52  if len(ref_list) > list_limit:
53  hints.set_limit(list_limit, truncated=True)
54  return ref_list[:list_limit]
55  else:
56  hints.set_limit(list_limit)
57  return ref_list
58  return wrapper
59 
60 
61 class Hints(object):
62  """Encapsulate driver hints for listing entities.
63 
64  Hints are modifiers that affect the return of entities from a
65  list_<entities> operation. They are typically passed to a driver to give
66  direction as to what filtering, pagination or list limiting actions are
67  being requested.
68 
69  It is optional for a driver to action some or all of the list hints,
70  but any filters that it does satisfy must be marked as such by calling
71  removing the filter from the list.
72 
73  A Hint object contains filters, which is a list of dicts that can be
74  accessed publicly. Also it contains a dict called limit, which will
75  indicate the amount of data we want to limit our listing to.
76 
77  If the filter is discovered to never match, then `cannot_match` can be set
78  to indicate that there will not be any matches and the backend work can be
79  short-circuited.
80 
81  Each filter term consists of:
82 
83  * ``name``: the name of the attribute being matched
84  * ``value``: the value against which it is being matched
85  * ``comparator``: the operation, which can be one of ``equals``,
86  ``contains``, ``startswith`` or ``endswith``
87  * ``case_sensitive``: whether any comparison should take account of
88  case
89 
90  """
91 
92  def __init__(self):
93  self.limit = None
94  self.filters = list()
95  self.cannot_match = False
96 
97  def add_filter(self, name, value, comparator='equals',
98  case_sensitive=False):
99  """Add a filter to the filters list, which is publicly accessible."""
100  self.filters.append({'name': name, 'value': value,
101  'comparator': comparator,
102  'case_sensitive': case_sensitive})
103 
104  def get_exact_filter_by_name(self, name):
105  """Return a filter key and value if exact filter exists for name."""
106  for entry in self.filters:
107  if (entry['name'] == name and entry['comparator'] == 'equals'):
108  return entry
109 
110  def set_limit(self, limit, truncated=False):
111  """Set a limit to indicate the list should be truncated."""
112  self.limit = {'limit': limit, 'truncated': truncated}
keystone.common.driver_hints.Hints.set_limit
def set_limit(self, limit, truncated=False)
Definition: driver_hints.py:110
keystone.common.driver_hints.Hints.add_filter
def add_filter(self, name, value, comparator='equals', case_sensitive=False)
Definition: driver_hints.py:98
keystone.common.driver_hints.truncated
def truncated(f)
Definition: driver_hints.py:22
keystone.exception.UnexpectedError
Definition: exception.py:566
keystone.common.driver_hints.Hints.get_exact_filter_by_name
def get_exact_filter_by_name(self, name)
Definition: driver_hints.py:104
keystone.common.driver_hints.Hints.filters
filters
Definition: driver_hints.py:94
keystone.common.driver_hints.Hints.limit
limit
Definition: driver_hints.py:93
keystone.common.driver_hints.Hints.cannot_match
cannot_match
Definition: driver_hints.py:95
keystone.i18n._
_
Definition: i18n.py:29
keystone.i18n
Definition: i18n.py:1
keystone.common.driver_hints.Hints.__init__
def __init__(self)
Definition: driver_hints.py:92
keystone.common.driver_hints.Hints
Definition: driver_hints.py:61