/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to breezy/registry.py

  • Committer: Robert Collins
  • Date: 2005-12-24 02:20:45 UTC
  • mto: (1185.50.57 bzr-jam-integration)
  • mto: This revision was merged to the branch mainline in revision 1550.
  • Revision ID: robertc@robertcollins.net-20051224022045-14efc8dfa0e1a4e9
Start tests for api usage.

Show diffs side-by-side

added added

removed removed

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