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
"""Classes to provide name-to-object registry-like support."""
20
from bzrlib.pyutils import get_named_object
23
class _ObjectGetter(object):
24
"""Maintain a reference to an object, and return the object on request.
26
This is used by Registry to make plain objects function similarly
27
to lazily imported objects.
29
Objects can be any sort of python object (class, function, module,
35
def __init__(self, obj):
39
"""Get the object that was saved at creation time"""
43
class _LazyObjectGetter(_ObjectGetter):
44
"""Keep a record of a possible object.
46
When requested, load and return it.
49
__slots__ = ['_module_name', '_member_name', '_imported']
51
def __init__(self, module_name, member_name):
52
self._module_name = module_name
53
self._member_name = member_name
54
self._imported = False
55
super(_LazyObjectGetter, self).__init__(None)
58
"""Get the referenced object.
60
Upon first request, the object will be imported. Future requests will
61
return the imported object.
63
if not self._imported:
64
self._obj = get_named_object(self._module_name, self._member_name)
66
return super(_LazyObjectGetter, self).get_obj()
69
return "<%s.%s object at %x, module=%r attribute=%r imported=%r>" % (
70
self.__class__.__module__, self.__class__.__name__, id(self),
71
self._module_name, self._member_name, self._imported)
74
class Registry(object):
75
"""A class that registers objects to a name.
77
There are many places that want to collect related objects and access them
78
by a key. This class is designed to allow registering the mapping from key
79
to object. It goes one step further, and allows registering a name to a
80
hypothetical object which has not been imported yet. It also supports
81
adding additional information at registration time so that decisions can be
82
made without having to import the object (which may be expensive).
84
The functions 'get', 'get_info', and 'get_help' also support a
85
'default_key' (settable through my_registry.default_key = XXX, XXX must
86
already be registered.) Calling my_registry.get() or my_registry.get(None),
87
will return the entry for the default key.
91
"""Create a new Registry."""
92
self._default_key = None
93
# Map from key => (is_lazy, info)
98
def register(self, key, obj, help=None, info=None,
99
override_existing=False):
100
"""Register a new object to a name.
102
:param key: This is the key to use to request the object later.
103
:param obj: The object to register.
104
:param help: Help text for this entry. This may be a string or
105
a callable. If it is a callable, it should take two
106
parameters (registry, key): this registry and the key that
107
the help was registered under.
108
:param info: More information for this entry. Registry.get_info()
109
can be used to get this information. Registry treats this as an
110
opaque storage location (it is defined by the caller).
111
:param override_existing: Raise KeyErorr if False and something has
112
already been registered for that key. If True, ignore if there
113
is an existing key (always register the new value).
115
if not override_existing:
116
if key in self._dict:
117
raise KeyError('Key %r already registered' % key)
118
self._dict[key] = _ObjectGetter(obj)
119
self._add_help_and_info(key, help=help, info=info)
121
def register_lazy(self, key, module_name, member_name,
122
help=None, info=None,
123
override_existing=False):
124
"""Register a new object to be loaded on request.
126
:param module_name: The python path to the module. Such as 'os.path'.
127
:param member_name: The member of the module to return. If empty or
128
None, get() will return the module itself.
129
:param help: Help text for this entry. This may be a string or
131
:param info: More information for this entry. Registry
132
:param override_existing: If True, replace the existing object
133
with the new one. If False, if there is already something
134
registered with the same key, raise a KeyError
136
if not override_existing:
137
if key in self._dict:
138
raise KeyError('Key %r already registered' % key)
139
self._dict[key] = _LazyObjectGetter(module_name, member_name)
140
self._add_help_and_info(key, help=help, info=info)
142
def _add_help_and_info(self, key, help=None, info=None):
143
"""Add the help and information about this key"""
144
self._help_dict[key] = help
145
self._info_dict[key] = info
147
def get(self, key=None):
148
"""Return the object register()'ed to the given key.
150
May raise ImportError if the object was registered lazily and
151
there are any problems, or AttributeError if the module does not
152
have the supplied member.
154
:param key: The key to obtain the object for. If no object has been
155
registered to that key, the object registered for self.default_key
156
will be returned instead, if it exists. Otherwise KeyError will be
158
:return: The previously registered object.
159
:raises ImportError: If the object was registered lazily, and there are
160
problems during import.
161
:raises AttributeError: If registered lazily, and the module does not
162
contain the registered member.
164
return self._dict[self._get_key_or_default(key)].get_obj()
166
def get_prefix(self, fullname):
167
"""Return an object whose key is a prefix of the supplied value.
169
:fullname: The name to find a prefix for
170
:return: a tuple of (object, remainder), where the remainder is the
171
portion of the name that did not match the key.
173
for key in self.keys():
174
if fullname.startswith(key):
175
return self.get(key), fullname[len(key):]
177
def _get_key_or_default(self, key=None):
178
"""Return either 'key' or the default key if key is None"""
181
if self.default_key is None:
182
raise KeyError('Key is None, and no default key is set')
184
return self.default_key
186
def get_help(self, key=None):
187
"""Get the help text associated with the given key"""
188
the_help = self._help_dict[self._get_key_or_default(key)]
189
if callable(the_help):
190
return the_help(self, key)
193
def get_info(self, key=None):
194
"""Get the extra information associated with the given key"""
195
return self._info_dict[self._get_key_or_default(key)]
197
def remove(self, key):
198
"""Remove a registered entry.
200
This is mostly for the test suite, but it can be used by others
204
def __contains__(self, key):
205
return key in self._dict
208
"""Get a list of registered entries"""
209
return sorted(self._dict.keys())
212
for key, getter in self._dict.iteritems():
213
yield key, getter.get_obj()
216
# We should not use the iteritems() implementation below (see bug
218
return sorted([(key, getter.get_obj())
219
for key, getter in self._dict.items()])
221
def _set_default_key(self, key):
222
if not self._dict.has_key(key):
223
raise KeyError('No object registered under key %s.' % key)
225
self._default_key = key
227
def _get_default_key(self):
228
return self._default_key
230
default_key = property(_get_default_key, _set_default_key,
231
doc="Current value of the default key."
232
" Can be set to any existing key.")
235
class FormatRegistry(Registry):
236
"""Registry specialised for handling formats."""
238
def __init__(self, other_registry=None):
239
Registry.__init__(self)
240
self._other_registry = other_registry
242
def register(self, key, obj, help=None, info=None,
243
override_existing=False):
244
Registry.register(self, key, obj, help=help, info=info,
245
override_existing=override_existing)
246
if self._other_registry is not None:
247
self._other_registry.register(key, obj, help=help,
248
info=info, override_existing=override_existing)
250
def register_lazy(self, key, module_name, member_name,
251
help=None, info=None,
252
override_existing=False):
253
# Overridden to allow capturing registrations to two seperate
254
# registries in a single call.
255
Registry.register_lazy(self, key, module_name, member_name,
256
help=help, info=info, override_existing=override_existing)
257
if self._other_registry is not None:
258
self._other_registry.register_lazy(key, module_name, member_name,
259
help=help, info=info, override_existing=override_existing)
261
def get(self, format_string):
262
r = Registry.get(self, format_string)
added
removed
bzrlib/registry.py
