~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/registry.py

  • Committer: Ross Lagerwall
  • Date: 2012-08-07 06:32:51 UTC
  • mto: (6437.63.5 2.5)
  • mto: This revision was merged to the branch mainline in revision 6558.
  • Revision ID: rosslagerwall@gmail.com-20120807063251-x9p03ghg2ws8oqjc
Add bzrlib/locale to .bzrignore

bzrlib/locale is generated with ./setup.py build_mo which is in turn called
by ./setup.py build

Show diffs side-by-side

added added

removed removed

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