~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/registry.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2006-10-10 07:09:12 UTC
  • mfrom: (2063.4.5 lazy_regex)
  • Revision ID: pqm@pqm.ubuntu.com-20061010070912-10e1b070dacb4c40
(John Arbash Meinel) bzrlib.lazy_regex.lazy_compile creates regex objects that are compiled on demand

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2006, 2008 Canonical Ltd
2
 
#
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.
7
 
#
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.
12
 
#
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
16
 
 
17
 
"""Classes to provide name-to-object registry-like support."""
18
 
 
19
 
 
20
 
class _ObjectGetter(object):
21
 
    """Maintain a reference to an object, and return the object on request.
22
 
 
23
 
    This is used by Registry to make plain objects function similarly
24
 
    to lazily imported objects.
25
 
 
26
 
    Objects can be any sort of python object (class, function, module,
27
 
    instance, etc)
28
 
    """
29
 
 
30
 
    __slots__ = ['_obj']
31
 
 
32
 
    def __init__(self, obj):
33
 
        self._obj = obj
34
 
 
35
 
    def get_obj(self):
36
 
        """Get the object that was saved at creation time"""
37
 
        return self._obj
38
 
 
39
 
 
40
 
class _LazyObjectGetter(_ObjectGetter):
41
 
    """Keep a record of a possible object.
42
 
 
43
 
    When requested, load and return it.
44
 
    """
45
 
 
46
 
    __slots__ = ['_module_name', '_member_name', '_imported']
47
 
 
48
 
    def __init__(self, module_name, member_name):
49
 
        self._module_name = module_name
50
 
        self._member_name = member_name
51
 
        self._imported = False
52
 
        super(_LazyObjectGetter, self).__init__(None)
53
 
 
54
 
    def get_obj(self):
55
 
        """Get the referenced object.
56
 
 
57
 
        Upon first request, the object will be imported. Future requests will
58
 
        return the imported object.
59
 
        """
60
 
        if not self._imported:
61
 
            self._do_import()
62
 
        return super(_LazyObjectGetter, self).get_obj()
63
 
 
64
 
    def _do_import(self):
65
 
        if self._member_name:
66
 
            segments = self._member_name.split('.')
67
 
            names = segments[0:1]
68
 
        else:
69
 
            names = [self._member_name]
70
 
        obj = __import__(self._module_name, globals(), locals(), names)
71
 
        if self._member_name:
72
 
            for segment in segments:
73
 
                obj = getattr(obj, segment)
74
 
        self._obj = obj
75
 
        self._imported = True
76
 
 
77
 
    def __repr__(self):
78
 
        return "<%s.%s object at %x, module=%r attribute=%r>" % (
79
 
            self.__class__.__module__, self.__class__.__name__, id(self),
80
 
            self._module_name, self._member_name)
81
 
 
82
 
 
83
 
class Registry(object):
84
 
    """A class that registers objects to a name.
85
 
 
86
 
    There are many places that want to collect related objects and access them
87
 
    by a key. This class is designed to allow registering the mapping from key
88
 
    to object. It goes one step further, and allows registering a name to a
89
 
    hypothetical object which has not been imported yet. It also supports
90
 
    adding additional information at registration time so that decisions can be
91
 
    made without having to import the object (which may be expensive).
92
 
 
93
 
    The functions 'get', 'get_info', and 'get_help' also support a
94
 
    'default_key' (settable through my_registry.default_key = XXX, XXX must
95
 
    already be registered.) Calling my_registry.get() or my_registry.get(None),
96
 
    will return the entry for the default key.
97
 
    """
98
 
 
99
 
    def __init__(self):
100
 
        """Create a new Registry."""
101
 
        self._default_key = None
102
 
        # Map from key => (is_lazy, info)
103
 
        self._dict = {}
104
 
        self._help_dict = {}
105
 
        self._info_dict = {}
106
 
 
107
 
    def register(self, key, obj, help=None, info=None,
108
 
                 override_existing=False):
109
 
        """Register a new object to a name.
110
 
 
111
 
        :param key: This is the key to use to request the object later.
112
 
        :param obj: The object to register.
113
 
        :param help: Help text for this entry. This may be a string or
114
 
                a callable. If it is a callable, it should take two
115
 
                parameters (registry, key): this registry and the key that
116
 
                the help was registered under.
117
 
        :param info: More information for this entry. Registry.get_info()
118
 
                can be used to get this information. Registry treats this as an
119
 
                opaque storage location (it is defined by the caller).
120
 
        :param override_existing: Raise KeyErorr if False and something has
121
 
                already been registered for that key. If True, ignore if there
122
 
                is an existing key (always register the new value).
123
 
        """
124
 
        if not override_existing:
125
 
            if key in self._dict:
126
 
                raise KeyError('Key %r already registered' % key)
127
 
        self._dict[key] = _ObjectGetter(obj)
128
 
        self._add_help_and_info(key, help=help, info=info)
129
 
 
130
 
    def register_lazy(self, key, module_name, member_name,
131
 
                      help=None, info=None,
132
 
                      override_existing=False):
133
 
        """Register a new object to be loaded on request.
134
 
 
135
 
        :param module_name: The python path to the module. Such as 'os.path'.
136
 
        :param member_name: The member of the module to return.  If empty or
137
 
                None, get() will return the module itself.
138
 
        :param help: Help text for this entry. This may be a string or
139
 
                a callable.
140
 
        :param info: More information for this entry. Registry
141
 
        :param override_existing: If True, replace the existing object
142
 
                with the new one. If False, if there is already something
143
 
                registered with the same key, raise a KeyError
144
 
        """
145
 
        if not override_existing:
146
 
            if key in self._dict:
147
 
                raise KeyError('Key %r already registered' % key)
148
 
        self._dict[key] = _LazyObjectGetter(module_name, member_name)
149
 
        self._add_help_and_info(key, help=help, info=info)
150
 
 
151
 
    def _add_help_and_info(self, key, help=None, info=None):
152
 
        """Add the help and information about this key"""
153
 
        self._help_dict[key] = help
154
 
        self._info_dict[key] = info
155
 
 
156
 
    def get(self, key=None):
157
 
        """Return the object register()'ed to the given key.
158
 
 
159
 
        May raise ImportError if the object was registered lazily and
160
 
        there are any problems, or AttributeError if the module does not
161
 
        have the supplied member.
162
 
 
163
 
        :param key: The key to obtain the object for. If no object has been
164
 
            registered to that key, the object registered for self.default_key
165
 
            will be returned instead, if it exists. Otherwise KeyError will be
166
 
            raised.
167
 
        :return: The previously registered object.
168
 
        :raises ImportError: If the object was registered lazily, and there are
169
 
            problems during import.
170
 
        :raises AttributeError: If registered lazily, and the module does not
171
 
            contain the registered member.
172
 
        """
173
 
        return self._dict[self._get_key_or_default(key)].get_obj()
174
 
 
175
 
    def get_prefix(self, fullname):
176
 
        """Return an object whose key is a prefix of the supplied value.
177
 
 
178
 
        :fullname: The name to find a prefix for
179
 
        :return: a tuple of (object, remainder), where the remainder is the
180
 
            portion of the name that did not match the key.
181
 
        """
182
 
        for key in self.keys():
183
 
            if fullname.startswith(key):
184
 
                return self.get(key), fullname[len(key):]
185
 
 
186
 
    def _get_key_or_default(self, key=None):
187
 
        """Return either 'key' or the default key if key is None"""
188
 
        if key is not None:
189
 
            return key
190
 
        if self.default_key is None:
191
 
            raise KeyError('Key is None, and no default key is set')
192
 
        else:
193
 
            return self.default_key
194
 
 
195
 
    def get_help(self, key=None):
196
 
        """Get the help text associated with the given key"""
197
 
        the_help = self._help_dict[self._get_key_or_default(key)]
198
 
        if callable(the_help):
199
 
            return the_help(self, key)
200
 
        return the_help
201
 
 
202
 
    def get_info(self, key=None):
203
 
        """Get the extra information associated with the given key"""
204
 
        return self._info_dict[self._get_key_or_default(key)]
205
 
 
206
 
    def remove(self, key):
207
 
        """Remove a registered entry.
208
 
 
209
 
        This is mostly for the test suite, but it can be used by others
210
 
        """
211
 
        del self._dict[key]
212
 
 
213
 
    def __contains__(self, key):
214
 
        return key in self._dict
215
 
 
216
 
    def keys(self):
217
 
        """Get a list of registered entries"""
218
 
        return sorted(self._dict.keys())
219
 
 
220
 
    def iteritems(self):
221
 
        for key, getter in self._dict.iteritems():
222
 
            yield key, getter.get_obj()
223
 
 
224
 
    def items(self):
225
 
        # We should not use the iteritems() implementation below (see bug
226
 
        # #430510)
227
 
        return sorted([(key, getter.get_obj())
228
 
                       for key, getter in self._dict.items()])
229
 
 
230
 
    def _set_default_key(self, key):
231
 
        if not self._dict.has_key(key):
232
 
            raise KeyError('No object registered under key %s.' % key)
233
 
        else:
234
 
            self._default_key = key
235
 
 
236
 
    def _get_default_key(self):
237
 
        return self._default_key
238
 
 
239
 
    default_key = property(_get_default_key, _set_default_key,
240
 
                            doc="Current value of the default key."
241
 
                                " Can be set to any existing key.")
242
 
 
243
 
 
244
 
class FormatRegistry(Registry):
245
 
    """Registry specialised for handling formats."""
246
 
 
247
 
    def __init__(self, other_registry=None):
248
 
        Registry.__init__(self)
249
 
        self._other_registry = other_registry
250
 
 
251
 
    def register_lazy(self, key, module_name, member_name,
252
 
                      help=None, info=None,
253
 
                      override_existing=False):
254
 
        # Overridden to allow capturing registrations to two seperate
255
 
        # registries in a single call.
256
 
        Registry.register_lazy(self, key, module_name, member_name,
257
 
                help=help, info=info, override_existing=override_existing)
258
 
        if self._other_registry is not None:
259
 
            self._other_registry.register_lazy(key, module_name, member_name,
260
 
                help=help, info=info, override_existing=override_existing)
261
 
 
262
 
    def get(self, format_string):
263
 
        r = Registry.get(self, format_string)
264
 
        if callable(r):
265
 
            r = r()
266
 
        return r
267
 
 
268