← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/registry.py

- increment version

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/registry.py
1
 
# Copyright (C) 2006 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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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
 
        obj = __import__(self._module_name, globals(), locals(),
66
 
                         [self._member_name])
67
 
        if self._member_name:
68
 
            obj = getattr(obj, self._member_name)
69
 
        self._obj = obj
70
 
        self._imported = True
71
 
 
72
 
 
73
 
class Registry(object):
74
 
    """A class that registers objects to a name.
75
 
 
76
 
    There are many places that want to collect related objects and access them
77
 
    by a key. This class is designed to allow registering the mapping from key
78
 
    to object. It goes one step further, and allows registering a name to a
79
 
    hypothetical object which has not been imported yet. It also supports
80
 
    adding additional information at registration time so that decisions can be
81
 
    made without having to import the object (which may be expensive).
82
 
 
83
 
    The functions 'get', 'get_info', and 'get_help' also support a
84
 
    'default_key' (settable through my_registry.default_key = XXX, XXX must
85
 
    already be registered.) Calling my_registry.get() or my_registry.get(None),
86
 
    will return the entry for the default key.
87
 
    """
88
 
 
89
 
    def __init__(self):
90
 
        """Create a new Registry."""
91
 
        self._default_key = None
92
 
        # Map from key => (is_lazy, info)
93
 
        self._dict = {}
94
 
        self._help_dict = {}
95
 
        self._info_dict = {}
96
 
 
97
 
    def register(self, key, obj, help=None, info=None,
98
 
                 override_existing=False):
99
 
        """Register a new object to a name.
100
 
 
101
 
        :param key: This is the key to use to request the object later.
102
 
        :param obj: The object to register.
103
 
        :param help: Help text for this entry. This may be a string or
104
 
                a callable. If it is a callable, it should take two
105
 
                parameters (registry, key): this registry and the key that 
106
 
                the help was registered under.
107
 
        :param info: More information for this entry. Registry.get_info()
108
 
                can be used to get this information. Registry treats this as an
109
 
                opaque storage location (it is defined by the caller).
110
 
        :param override_existing: Raise KeyErorr if False and something has
111
 
                already been registered for that key. If True, ignore if there
112
 
                is an existing key (always register the new value).
113
 
        """
114
 
        if not override_existing:
115
 
            if key in self._dict:
116
 
                raise KeyError('Key %r already registered' % key)
117
 
        self._dict[key] = _ObjectGetter(obj)
118
 
        self._add_help_and_info(key, help=help, info=info)
119
 
 
120
 
    def register_lazy(self, key, module_name, member_name,
121
 
                      help=None, info=None,
122
 
                      override_existing=False):
123
 
        """Register a new object to be loaded on request.
124
 
 
125
 
        :param module_name: The python path to the module. Such as 'os.path'.
126
 
        :param member_name: The member of the module to return.  If empty or 
127
 
                None, get() will return the module itself.
128
 
        :param help: Help text for this entry. This may be a string or
129
 
                a callable.
130
 
        :param info: More information for this entry. Registry 
131
 
        :param override_existing: If True, replace the existing object
132
 
                with the new one. If False, if there is already something
133
 
                registered with the same key, raise a KeyError
134
 
        """
135
 
        if not override_existing:
136
 
            if key in self._dict:
137
 
                raise KeyError('Key %r already registered' % key)
138
 
        self._dict[key] = _LazyObjectGetter(module_name, member_name)
139
 
        self._add_help_and_info(key, help=help, info=info)
140
 
 
141
 
    def _add_help_and_info(self, key, help=None, info=None):
142
 
        """Add the help and information about this key"""
143
 
        self._help_dict[key] = help
144
 
        self._info_dict[key] = info
145
 
 
146
 
    def get(self, key=None):
147
 
        """Return the object register()'ed to the given key.
148
 
 
149
 
        May raise ImportError if the object was registered lazily and
150
 
        there are any problems, or AttributeError if the module does not 
151
 
        have the supplied member.
152
 
 
153
 
        :param key: The key to obtain the object for. If no object has been
154
 
            registered to that key, the object registered for self.default_key
155
 
            will be returned instead, if it exists. Otherwise KeyError will be
156
 
            raised.
157
 
        :return: The previously registered object.
158
 
        :raises ImportError: If the object was registered lazily, and there are
159
 
            problems during import.
160
 
        :raises AttributeError: If registered lazily, and the module does not
161
 
            contain the registered member.
162
 
        """
163
 
        return self._dict[self._get_key_or_default(key)].get_obj()
164
 
 
165
 
    def _get_key_or_default(self, key=None):
166
 
        """Return either 'key' or the default key if key is None"""
167
 
        if key is not None:
168
 
            return key
169
 
        if self.default_key is None:
170
 
            raise KeyError('Key is None, and no default key is set')
171
 
        else:
172
 
            return self.default_key
173
 
 
174
 
    def get_help(self, key=None):
175
 
        """Get the help text associated with the given key"""
176
 
        the_help = self._help_dict[self._get_key_or_default(key)]
177
 
        if callable(the_help):
178
 
            return the_help(self, key)
179
 
        return the_help
180
 
 
181
 
    def get_info(self, key=None):
182
 
        """Get the extra information associated with the given key"""
183
 
        return self._info_dict[self._get_key_or_default(key)]
184
 
 
185
 
    def remove(self, key):
186
 
        """Remove a registered entry.
187
 
 
188
 
        This is mostly for the test suite, but it can be used by others
189
 
        """
190
 
        del self._dict[key]
191
 
 
192
 
    def __contains__(self, key):
193
 
        return key in self._dict
194
 
 
195
 
    def keys(self):
196
 
        """Get a list of registered entries"""
197
 
        return sorted(self._dict.keys())
198
 
 
199
 
    def iteritems(self):
200
 
        for key, getter in self._dict.iteritems():
201
 
            yield key, getter.get_obj()
202
 
 
203
 
    def _set_default_key(self, key):
204
 
        if not self._dict.has_key(key):
205
 
            raise KeyError('No object registered under key %s.' % key)
206
 
        else:
207
 
            self._default_key = key
208
 
 
209
 
    def _get_default_key(self):
210
 
        return self._default_key
211
 
 
212
 
    default_key = property(_get_default_key, _set_default_key,
213
 
                            doc="Current value of the default key."
214
 
                                " Can be set to any existing key.")