/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 bzrlib/hooks.py

  • Committer: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/hooks.py
1
 
# Copyright (C) 2007-2011 Canonical Ltd
 
1
# Copyright (C) 2007-2010 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
 
17
 
17
18
"""Support for plugin hooking logic."""
18
 
 
19
 
from __future__ import absolute_import
20
 
 
21
 
from . import (
22
 
    errors,
23
 
    registry,
24
 
    )
25
 
from .lazy_import import lazy_import
 
19
from bzrlib import registry
 
20
from bzrlib.lazy_import import lazy_import
26
21
lazy_import(globals(), """
27
22
import textwrap
28
23
 
29
 
from breezy import (
30
 
    _format_version_tuple,
31
 
    pyutils,
32
 
    )
33
 
from breezy.i18n import gettext
 
24
from bzrlib import (
 
25
        _format_version_tuple,
 
26
        errors,
 
27
        )
 
28
from bzrlib.help_topics import help_as_plain_text
34
29
""")
35
30
 
36
31
 
37
 
class UnknownHook(errors.BzrError):
38
 
 
39
 
    _fmt = "The %(type)s hook '%(hook)s' is unknown in this version of breezy."
40
 
 
41
 
    def __init__(self, hook_type, hook_name):
42
 
        errors.BzrError.__init__(self)
43
 
        self.type = hook_type
44
 
        self.hook = hook_name
45
 
 
46
 
 
47
 
class KnownHooksRegistry(registry.Registry):
48
 
    # known_hooks registry contains
49
 
    # tuple of (module, member name) which is the hook point
50
 
    # module where the specific hooks are defined
51
 
    # callable to get the empty specific Hooks for that attribute
52
 
 
53
 
    def register_lazy_hook(self, hook_module_name, hook_member_name,
54
 
                           hook_factory_member_name):
55
 
        self.register_lazy((hook_module_name, hook_member_name),
56
 
                           hook_module_name, hook_factory_member_name)
57
 
 
58
 
    def iter_parent_objects(self):
59
 
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
60
 
        hook, where 'parent_object' is the object that holds the hook
61
 
        instance.
62
 
 
63
 
        This is useful for resetting/restoring all the hooks to a known state,
64
 
        as is done in breezy.tests.TestCase._clear_hooks.
65
 
        """
66
 
        for key in self.keys():
67
 
            yield key, self.key_to_parent_and_attribute(key)
68
 
 
69
 
    def key_to_parent_and_attribute(self, key):
70
 
        """Convert a known_hooks key to a (parent_obj, attr) pair.
71
 
 
72
 
        :param key: A tuple (module_name, member_name) as found in the keys of
73
 
            the known_hooks registry.
74
 
        :return: The parent_object of the hook and the name of the attribute on
75
 
            that parent object where the hook is kept.
76
 
        """
77
 
        parent_mod, parent_member, attr = pyutils.calc_parent_name(*key)
78
 
        return pyutils.get_named_object(parent_mod, parent_member), attr
79
 
 
80
 
 
81
 
_builtin_known_hooks = (
82
 
    ('breezy.branch', 'Branch.hooks', 'BranchHooks'),
83
 
    ('breezy.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
84
 
    ('breezy.commands', 'Command.hooks', 'CommandHooks'),
85
 
    ('breezy.config', 'ConfigHooks', '_ConfigHooks'),
86
 
    ('breezy.info', 'hooks', 'InfoHooks'),
87
 
    ('breezy.lock', 'Lock.hooks', 'LockHooks'),
88
 
    ('breezy.merge', 'Merger.hooks', 'MergeHooks'),
89
 
    ('breezy.msgeditor', 'hooks', 'MessageEditorHooks'),
90
 
    ('breezy.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
91
 
    ('breezy.bzr.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
92
 
    ('breezy.bzr.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
93
 
    ('breezy.status', 'hooks', 'StatusHooks'),
94
 
    ('breezy.transport', 'Transport.hooks', 'TransportHooks'),
95
 
    ('breezy.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
96
 
        'RioVersionInfoBuilderHooks'),
97
 
    ('breezy.merge_directive', 'BaseMergeDirective.hooks',
98
 
        'MergeDirectiveHooks'),
99
 
    )
100
 
 
101
 
known_hooks = KnownHooksRegistry()
102
 
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
103
 
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
104
 
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
105
 
 
106
 
 
107
 
def known_hooks_key_to_object(key):
108
 
    """Convert a known_hooks key to a object.
109
 
 
110
 
    :param key: A tuple (module_name, member_name) as found in the keys of
111
 
        the known_hooks registry.
112
 
    :return: The object this specifies.
113
 
    """
114
 
    return pyutils.get_named_object(*key)
 
32
known_hooks = registry.Registry()
 
33
# known_hooks registry contains
 
34
# tuple of (module, member name) which is the hook point
 
35
# module where the specific hooks are defined
 
36
# callable to get the empty specific Hooks for that attribute
 
37
known_hooks.register_lazy(('bzrlib.branch', 'Branch.hooks'), 'bzrlib.branch',
 
38
    'BranchHooks')
 
39
known_hooks.register_lazy(('bzrlib.bzrdir', 'BzrDir.hooks'), 'bzrlib.bzrdir',
 
40
    'BzrDirHooks')
 
41
known_hooks.register_lazy(('bzrlib.commands', 'Command.hooks'),
 
42
    'bzrlib.commands', 'CommandHooks')
 
43
known_hooks.register_lazy(('bzrlib.info', 'hooks'),
 
44
    'bzrlib.info', 'InfoHooks')
 
45
known_hooks.register_lazy(('bzrlib.lock', 'Lock.hooks'), 'bzrlib.lock',
 
46
    'LockHooks')
 
47
known_hooks.register_lazy(('bzrlib.merge', 'Merger.hooks'), 'bzrlib.merge',
 
48
    'MergeHooks')
 
49
known_hooks.register_lazy(('bzrlib.msgeditor', 'hooks'), 'bzrlib.msgeditor',
 
50
    'MessageEditorHooks')
 
51
known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),
 
52
    'bzrlib.mutabletree', 'MutableTreeHooks')
 
53
known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),
 
54
    'bzrlib.smart.client', 'SmartClientHooks')
 
55
known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),
 
56
    'bzrlib.smart.server', 'SmartServerHooks')
 
57
known_hooks.register_lazy(
 
58
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks'),
 
59
    'bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilderHooks')
 
60
known_hooks.register_lazy(
 
61
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks'),
 
62
    'bzrlib.merge_directive', 'MergeDirectiveHooks')
 
63
 
 
64
 
 
65
def known_hooks_key_to_object((module_name, member_name)):
 
66
    """Convert a known_hooks key to a object.
 
67
 
 
68
    :param key: A tuple (module_name, member_name) as found in the keys of
 
69
        the known_hooks registry.
 
70
    :return: The object this specifies.
 
71
    """
 
72
    return registry._LazyObjectGetter(module_name, member_name).get_obj()
 
73
 
 
74
 
 
75
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
 
76
    """Convert a known_hooks key to a object.
 
77
 
 
78
    :param key: A tuple (module_name, member_name) as found in the keys of
 
79
        the known_hooks registry.
 
80
    :return: The object this specifies.
 
81
    """
 
82
    member_list = member_name.rsplit('.', 1)
 
83
    if len(member_list) == 2:
 
84
        parent_name, attribute = member_list
 
85
    else:
 
86
        parent_name = None
 
87
        attribute = member_name
 
88
    parent = known_hooks_key_to_object((module_name, parent_name))
 
89
    return parent, attribute
115
90
 
116
91
 
117
92
class Hooks(dict):
121
96
    FOO hook is triggered.
122
97
    """
123
98
 
124
 
    def __init__(self, module=None, member_name=None):
125
 
        """Create a new hooks dictionary.
126
 
 
127
 
        :param module: The module from which this hooks dictionary should be loaded
128
 
            (used for lazy hooks)
129
 
        :param member_name: Name under which this hooks dictionary should be loaded.
130
 
            (used for lazy hooks)
131
 
        """
 
99
    def __init__(self):
132
100
        dict.__init__(self)
133
101
        self._callable_names = {}
134
 
        self._lazy_callable_names = {}
135
 
        self._module = module
136
 
        self._member_name = member_name
137
 
 
138
 
    def add_hook(self, name, doc, introduced, deprecated=None):
139
 
        """Add a hook point to this dictionary.
140
 
 
141
 
        :param name: The name of the hook, for clients to use when registering.
142
 
        :param doc: The docs for the hook.
143
 
        :param introduced: When the hook was introduced (e.g. (0, 15)).
144
 
        :param deprecated: When the hook was deprecated, None for
145
 
            not-deprecated.
 
102
 
 
103
    def create_hook(self, hook):
 
104
        """Create a hook which can have callbacks registered for it.
 
105
 
 
106
        :param hook: The hook to create. An object meeting the protocol of
 
107
            bzrlib.hooks.HookPoint. It's name is used as the key for future
 
108
            lookups.
146
109
        """
147
 
        if name in self:
148
 
            raise errors.DuplicateKey(name)
149
 
        if self._module:
150
 
            callbacks = _lazy_hooks.setdefault(
151
 
                (self._module, self._member_name, name), [])
152
 
        else:
153
 
            callbacks = None
154
 
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
155
 
                              deprecated=deprecated, callbacks=callbacks)
156
 
        self[name] = hookpoint
 
110
        if hook.name in self:
 
111
            raise errors.DuplicateKey(hook.name)
 
112
        self[hook.name] = hook
157
113
 
158
114
    def docs(self):
159
115
        """Generate the documentation for this Hooks instance.
164
120
        hook_docs = []
165
121
        name = self.__class__.__name__
166
122
        hook_docs.append(name)
167
 
        hook_docs.append("-" * len(name))
 
123
        hook_docs.append("-"*len(name))
168
124
        hook_docs.append("")
169
125
        for hook_name in hook_names:
170
126
            hook = self[hook_name]
177
133
                strings.append("~" * len(hook_name))
178
134
                strings.append("")
179
135
                strings.append("An old-style hook. For documentation see the __init__ "
180
 
                               "method of '%s'\n" % (name,))
 
136
                    "method of '%s'\n" % (name,))
181
137
                hook_docs.extend(strings)
182
138
        return "\n".join(hook_docs)
183
139
 
189
145
        the code names are rarely meaningful for end users and this is not
190
146
        intended for debugging.
191
147
        """
192
 
        name = self._callable_names.get(a_callable, None)
193
 
        if name is None and a_callable is not None:
194
 
            name = self._lazy_callable_names.get((a_callable.__module__,
195
 
                                                  a_callable.__name__),
196
 
                                                 None)
197
 
        if name is None:
198
 
            return 'No hook name'
199
 
        return name
200
 
 
201
 
    def install_named_hook_lazy(self, hook_name, callable_module,
202
 
                                callable_member, name):
203
 
        """Install a_callable in to the hook hook_name lazily, and label it.
204
 
 
205
 
        :param hook_name: A hook name. See the __init__ method for the complete
206
 
            list of hooks.
207
 
        :param callable_module: Name of the module in which the callable is
208
 
            present.
209
 
        :param callable_member: Member name of the callable.
210
 
        :param name: A name to associate the callable with, to show users what
211
 
            is running.
212
 
        """
213
 
        try:
214
 
            hook = self[hook_name]
215
 
        except KeyError:
216
 
            raise UnknownHook(self.__class__.__name__, hook_name)
217
 
        try:
218
 
            hook_lazy = getattr(hook, "hook_lazy")
219
 
        except AttributeError:
220
 
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
221
 
                                              self)
222
 
        else:
223
 
            hook_lazy(callable_module, callable_member, name)
224
 
        if name is not None:
225
 
            self.name_hook_lazy(callable_module, callable_member, name)
 
148
        return self._callable_names.get(a_callable, "No hook name")
226
149
 
227
150
    def install_named_hook(self, hook_name, a_callable, name):
228
151
        """Install a_callable in to the hook hook_name, and label it name.
229
152
 
230
 
        :param hook_name: A hook name. See the __init__ method for the complete
231
 
            list of hooks.
 
153
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
154
            for the complete list of hooks.
232
155
        :param a_callable: The callable to be invoked when the hook triggers.
233
156
            The exact signature will depend on the hook - see the __init__
234
 
            method for details on each hook.
 
157
            method of BranchHooks for details on each hook.
235
158
        :param name: A name to associate a_callable with, to show users what is
236
159
            running.
237
160
        """
238
161
        try:
239
162
            hook = self[hook_name]
240
163
        except KeyError:
241
 
            raise UnknownHook(self.__class__.__name__, hook_name)
 
164
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
242
165
        try:
243
166
            # list hooks, old-style, not yet deprecated but less useful.
244
167
            hook.append(a_callable)
247
170
        if name is not None:
248
171
            self.name_hook(a_callable, name)
249
172
 
250
 
    def uninstall_named_hook(self, hook_name, label):
251
 
        """Uninstall named hooks.
252
 
 
253
 
        :param hook_name: Hook point name
254
 
        :param label: Label of the callable to uninstall
255
 
        """
256
 
        try:
257
 
            hook = self[hook_name]
258
 
        except KeyError:
259
 
            raise UnknownHook(self.__class__.__name__, hook_name)
260
 
        try:
261
 
            uninstall = getattr(hook, "uninstall")
262
 
        except AttributeError:
263
 
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
264
 
        else:
265
 
            uninstall(label)
266
 
 
267
173
    def name_hook(self, a_callable, name):
268
174
        """Associate name with a_callable to show users what is running."""
269
175
        self._callable_names[a_callable] = name
270
176
 
271
 
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
272
 
        self._lazy_callable_names[(callable_module, callable_member)] = \
273
 
            callable_name
274
 
 
275
177
 
276
178
class HookPoint(object):
277
179
    """A single hook that clients can register to be called back when it fires.
278
180
 
279
181
    :ivar name: The name of the hook.
280
 
    :ivar doc: The docs for using the hook.
281
182
    :ivar introduced: A version tuple specifying what version the hook was
282
183
        introduced in. None indicates an unknown version.
283
184
    :ivar deprecated: A version tuple specifying what version the hook was
284
185
        deprecated or superseded in. None indicates that the hook is not
285
186
        superseded or deprecated. If the hook is superseded then the doc
286
187
        should describe the recommended replacement hook to register for.
 
188
    :ivar doc: The docs for using the hook.
287
189
    """
288
190
 
289
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
191
    def __init__(self, name, doc, introduced, deprecated):
290
192
        """Create a HookPoint.
291
193
 
292
194
        :param name: The name of the hook, for clients to use when registering.
299
201
        self.__doc__ = doc
300
202
        self.introduced = introduced
301
203
        self.deprecated = deprecated
302
 
        if callbacks is None:
303
 
            self._callbacks = []
304
 
        else:
305
 
            self._callbacks = callbacks
 
204
        self._callbacks = []
 
205
        self._callback_names = {}
306
206
 
307
207
    def docs(self):
308
208
        """Generate the documentation for this HookPoint.
311
211
        """
312
212
        strings = []
313
213
        strings.append(self.name)
314
 
        strings.append('~' * len(self.name))
 
214
        strings.append('~'*len(self.name))
315
215
        strings.append('')
316
216
        if self.introduced:
317
217
            introduced_string = _format_version_tuple(self.introduced)
318
218
        else:
319
219
            introduced_string = 'unknown'
320
 
        strings.append(gettext('Introduced in: %s') % introduced_string)
 
220
        strings.append('Introduced in: %s' % introduced_string)
321
221
        if self.deprecated:
322
222
            deprecated_string = _format_version_tuple(self.deprecated)
323
 
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
 
223
            strings.append('Deprecated in: %s' % deprecated_string)
324
224
        strings.append('')
325
225
        strings.extend(textwrap.wrap(self.__doc__,
326
 
                                     break_long_words=False))
 
226
            break_long_words=False))
327
227
        strings.append('')
328
228
        return '\n'.join(strings)
329
229
 
330
230
    def __eq__(self, other):
331
 
        return (isinstance(other, type(self)) and other.__dict__ == self.__dict__)
332
 
 
333
 
    def hook_lazy(self, callback_module, callback_member, callback_label):
334
 
        """Lazily register a callback to be called when this HookPoint fires.
335
 
 
336
 
        :param callback_module: Module of the callable to use when this
337
 
            HookPoint fires.
338
 
        :param callback_member: Member name of the callback.
339
 
        :param callback_label: A label to show in the UI while this callback is
340
 
            processing.
341
 
        """
342
 
        obj_getter = registry._LazyObjectGetter(callback_module,
343
 
                                                callback_member)
344
 
        self._callbacks.append((obj_getter, callback_label))
 
231
        return (type(other) == type(self) and 
 
232
            other.__dict__ == self.__dict__)
345
233
 
346
234
    def hook(self, callback, callback_label):
347
235
        """Register a callback to be called when this HookPoint fires.
350
238
        :param callback_label: A label to show in the UI while this callback is
351
239
            processing.
352
240
        """
353
 
        obj_getter = registry._ObjectGetter(callback)
354
 
        self._callbacks.append((obj_getter, callback_label))
355
 
 
356
 
    def uninstall(self, label):
357
 
        """Uninstall the callback with the specified label.
358
 
 
359
 
        :param label: Label of the entry to uninstall
360
 
        """
361
 
        entries_to_remove = []
362
 
        for entry in self._callbacks:
363
 
            (entry_callback, entry_label) = entry
364
 
            if entry_label == label:
365
 
                entries_to_remove.append(entry)
366
 
        if entries_to_remove == []:
367
 
            raise KeyError("No entry with label %r" % label)
368
 
        for entry in entries_to_remove:
369
 
            self._callbacks.remove(entry)
 
241
        self._callbacks.append(callback)
 
242
        if callback_label is not None:
 
243
            self._callback_names[callback] = callback_label
370
244
 
371
245
    def __iter__(self):
372
 
        return (callback.get_obj() for callback, name in self._callbacks)
 
246
        return iter(self._callbacks)
373
247
 
374
248
    def __len__(self):
375
249
        return len(self._callbacks)
379
253
        strings.append("<%s(" % type(self).__name__)
380
254
        strings.append(self.name)
381
255
        strings.append("), callbacks=[")
382
 
        callbacks = self._callbacks
383
 
        for (callback, callback_name) in callbacks:
384
 
            strings.append(repr(callback.get_obj()))
 
256
        for callback in self._callbacks:
 
257
            strings.append(repr(callback))
385
258
            strings.append("(")
386
 
            strings.append(callback_name)
 
259
            strings.append(self._callback_names[callback])
387
260
            strings.append("),")
388
 
        if len(callbacks) == 1:
 
261
        if len(self._callbacks) == 1:
389
262
            strings[-1] = ")"
390
263
        strings.append("]>")
391
264
        return ''.join(strings)
392
265
 
393
266
 
394
267
_help_prefix = \
395
 
    """
 
268
"""
396
269
Hooks
397
270
=====
398
271
 
407
280
 
408
281
The class that contains each hook is given before the hooks it supplies. For
409
282
instance, BranchHooks as the class is the hooks class for
410
 
`breezy.branch.Branch.hooks`.
 
283
`bzrlib.branch.Branch.hooks`.
411
284
 
412
285
Each description also indicates whether the hook runs on the client (the
413
286
machine where bzr was invoked) or the server (the machine addressed by
424
297
 
425
298
"""
426
299
 
427
 
 
428
300
def hooks_help_text(topic):
429
301
    segments = [_help_prefix]
430
302
    for hook_key in sorted(known_hooks.keys()):
431
303
        hooks = known_hooks_key_to_object(hook_key)
432
304
        segments.append(hooks.docs())
433
305
    return '\n'.join(segments)
434
 
 
435
 
 
436
 
# Lazily registered hooks. Maps (module, name, hook_name) tuples
437
 
# to lists of tuples with objectgetters and names
438
 
_lazy_hooks = {}
439
 
 
440
 
 
441
 
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
442
 
                            a_callable, name):
443
 
    """Install a callable in to a hook lazily, and label it name.
444
 
 
445
 
    :param hookpoints_module: Module name of the hook points.
446
 
    :param hookpoints_name: Name of the hook points.
447
 
    :param hook_name: A hook name.
448
 
    :param callable: a callable to call for the hook.
449
 
    :param name: A name to associate a_callable with, to show users what is
450
 
        running.
451
 
    """
452
 
    key = (hookpoints_module, hookpoints_name, hook_name)
453
 
    obj_getter = registry._ObjectGetter(a_callable)
454
 
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))