1
# Copyright (C) 2006-2010 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
from __future__ import absolute_import
19
"""Classes to provide name-to-object registry-like support."""
22
from bzrlib.pyutils import get_named_object
25
class _ObjectGetter(object):
26
"""Maintain a reference to an object, and return the object on request.
28
This is used by Registry to make plain objects function similarly
29
to lazily imported objects.
31
Objects can be any sort of python object (class, function, module,
37
def __init__(self, obj):
41
"""Get the module the object was loaded from."""
42
return self._obj.__module__
45
"""Get the object that was saved at creation time"""
49
class _LazyObjectGetter(_ObjectGetter):
50
"""Keep a record of a possible object.
52
When requested, load and return it.
55
__slots__ = ['_module_name', '_member_name', '_imported']
57
def __init__(self, module_name, member_name):
58
self._module_name = module_name
59
self._member_name = member_name
60
self._imported = False
61
super(_LazyObjectGetter, self).__init__(None)
64
"""Get the module the referenced object will be loaded from.
66
return self._module_name
69
"""Get the referenced object.
71
Upon first request, the object will be imported. Future requests will
72
return the imported object.
74
if not self._imported:
75
self._obj = get_named_object(self._module_name, self._member_name)
77
return super(_LazyObjectGetter, self).get_obj()
80
return "<%s.%s object at %x, module=%r attribute=%r imported=%r>" % (
81
self.__class__.__module__, self.__class__.__name__, id(self),
82
self._module_name, self._member_name, self._imported)
85
class Registry(object):
86
"""A class that registers objects to a name.
88
There are many places that want to collect related objects and access them
89
by a key. This class is designed to allow registering the mapping from key
90
to object. It goes one step further, and allows registering a name to a
91
hypothetical object which has not been imported yet. It also supports
92
adding additional information at registration time so that decisions can be
93
made without having to import the object (which may be expensive).
95
The functions 'get', 'get_info', and 'get_help' also support a
96
'default_key' (settable through my_registry.default_key = XXX, XXX must
97
already be registered.) Calling my_registry.get() or my_registry.get(None),
98
will return the entry for the default key.
102
"""Create a new Registry."""
103
self._default_key = None
104
# Map from key => (is_lazy, info)
109
def register(self, key, obj, help=None, info=None,
110
override_existing=False):
111
"""Register a new object to a name.
113
:param key: This is the key to use to request the object later.
114
:param obj: The object to register.
115
:param help: Help text for this entry. This may be a string or
116
a callable. If it is a callable, it should take two
117
parameters (registry, key): this registry and the key that
118
the help was registered under.
119
:param info: More information for this entry. Registry.get_info()
120
can be used to get this information. Registry treats this as an
121
opaque storage location (it is defined by the caller).
122
:param override_existing: Raise KeyErorr if False and something has
123
already been registered for that key. If True, ignore if there
124
is an existing key (always register the new value).
126
if not override_existing:
127
if key in self._dict:
128
raise KeyError('Key %r already registered' % key)
129
self._dict[key] = _ObjectGetter(obj)
130
self._add_help_and_info(key, help=help, info=info)
132
def register_lazy(self, key, module_name, member_name,
133
help=None, info=None,
134
override_existing=False):
135
"""Register a new object to be loaded on request.
137
:param key: This is the key to use to request the object later.
138
:param module_name: The python path to the module. Such as 'os.path'.
139
:param member_name: The member of the module to return. If empty or
140
None, get() will return the module itself.
141
:param help: Help text for this entry. This may be a string or
143
:param info: More information for this entry. Registry.get_info()
144
can be used to get this information. Registry treats this as an
145
opaque storage location (it is defined by the caller).
146
:param override_existing: If True, replace the existing object
147
with the new one. If False, if there is already something
148
registered with the same key, raise a KeyError
150
if not override_existing:
151
if key in self._dict:
152
raise KeyError('Key %r already registered' % key)
153
self._dict[key] = _LazyObjectGetter(module_name, member_name)
154
self._add_help_and_info(key, help=help, info=info)
156
def _add_help_and_info(self, key, help=None, info=None):
157
"""Add the help and information about this key"""
158
self._help_dict[key] = help
159
self._info_dict[key] = info
161
def get(self, key=None):
162
"""Return the object register()'ed to the given key.
164
May raise ImportError if the object was registered lazily and
165
there are any problems, or AttributeError if the module does not
166
have the supplied member.
168
:param key: The key to obtain the object for. If no object has been
169
registered to that key, the object registered for self.default_key
170
will be returned instead, if it exists. Otherwise KeyError will be
172
:return: The previously registered object.
173
:raises ImportError: If the object was registered lazily, and there are
174
problems during import.
175
:raises AttributeError: If registered lazily, and the module does not
176
contain the registered member.
178
return self._dict[self._get_key_or_default(key)].get_obj()
180
def _get_module(self, key):
181
"""Return the module the object will be or was loaded from.
183
:param key: The key to obtain the module for.
184
:return: The name of the module
186
return self._dict[key].get_module()
188
def get_prefix(self, fullname):
189
"""Return an object whose key is a prefix of the supplied value.
191
:fullname: The name to find a prefix for
192
:return: a tuple of (object, remainder), where the remainder is the
193
portion of the name that did not match the key.
195
for key in self.keys():
196
if fullname.startswith(key):
197
return self.get(key), fullname[len(key):]
199
def _get_key_or_default(self, key=None):
200
"""Return either 'key' or the default key if key is None"""
203
if self.default_key is None:
204
raise KeyError('Key is None, and no default key is set')
206
return self.default_key
208
def get_help(self, key=None):
209
"""Get the help text associated with the given key"""
210
the_help = self._help_dict[self._get_key_or_default(key)]
211
if callable(the_help):
212
return the_help(self, key)
215
def get_info(self, key=None):
216
"""Get the extra information associated with the given key"""
217
return self._info_dict[self._get_key_or_default(key)]
219
def remove(self, key):
220
"""Remove a registered entry.
222
This is mostly for the test suite, but it can be used by others
226
def __contains__(self, key):
227
return key in self._dict
230
"""Get a list of registered entries"""
231
return sorted(self._dict.keys())
234
for key, getter in self._dict.iteritems():
235
yield key, getter.get_obj()
238
# We should not use the iteritems() implementation below (see bug
240
return sorted([(key, getter.get_obj())
241
for key, getter in self._dict.items()])
243
def _set_default_key(self, key):
244
if not self._dict.has_key(key):
245
raise KeyError('No object registered under key %s.' % key)
247
self._default_key = key
249
def _get_default_key(self):
250
return self._default_key
252
default_key = property(_get_default_key, _set_default_key,
253
doc="Current value of the default key."
254
" Can be set to any existing key.")
257
class FormatRegistry(Registry):
258
"""Registry specialised for handling formats."""
260
def __init__(self, other_registry=None):
261
Registry.__init__(self)
262
self._other_registry = other_registry
264
def register(self, key, obj, help=None, info=None,
265
override_existing=False):
266
Registry.register(self, key, obj, help=help, info=info,
267
override_existing=override_existing)
268
if self._other_registry is not None:
269
self._other_registry.register(key, obj, help=help,
270
info=info, override_existing=override_existing)
272
def register_lazy(self, key, module_name, member_name,
273
help=None, info=None,
274
override_existing=False):
275
# Overridden to allow capturing registrations to two seperate
276
# registries in a single call.
277
Registry.register_lazy(self, key, module_name, member_name,
278
help=help, info=info, override_existing=override_existing)
279
if self._other_registry is not None:
280
self._other_registry.register_lazy(key, module_name, member_name,
281
help=help, info=info, override_existing=override_existing)
283
def remove(self, key):
284
Registry.remove(self, key)
285
if self._other_registry is not None:
286
self._other_registry.remove(key)
288
def get(self, format_string):
289
r = Registry.get(self, format_string)
added
removed
bzrlib/registry.py
