← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Jelmer Vernooij
  • Date: 2011-12-16 16:40:10 UTC
  • mto: This revision was merged to the branch mainline in revision 6391.
  • Revision ID: jelmer@samba.org-20111216164010-z3hy00xrnclnkf7a
Update tests.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/hooks.py
1
 
# Copyright (C) 2007-2010 Canonical Ltd
 
1
# Copyright (C) 2007-2011 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
16
16
 
17
17
 
18
18
"""Support for plugin hooking logic."""
19
 
from bzrlib import registry
 
19
 
 
20
from bzrlib import (
 
21
    registry,
 
22
    symbol_versioning,
 
23
    )
20
24
from bzrlib.lazy_import import lazy_import
21
25
lazy_import(globals(), """
22
26
import textwrap
23
27
 
24
28
from bzrlib import (
25
 
        _format_version_tuple,
26
 
        errors,
27
 
        )
28
 
from bzrlib.help_topics import help_as_plain_text
 
29
    _format_version_tuple,
 
30
    errors,
 
31
    pyutils,
 
32
    )
 
33
from bzrlib.i18n import gettext
29
34
""")
30
35
 
31
36
 
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(('bzrlib.status', 'hooks'),
58
 
    'bzrlib.status', 'StatusHooks')
59
 
known_hooks.register_lazy(
60
 
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks'),
61
 
    'bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilderHooks')
62
 
known_hooks.register_lazy(
63
 
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks'),
64
 
    'bzrlib.merge_directive', 'MergeDirectiveHooks')
 
37
class KnownHooksRegistry(registry.Registry):
 
38
    # known_hooks registry contains
 
39
    # tuple of (module, member name) which is the hook point
 
40
    # module where the specific hooks are defined
 
41
    # callable to get the empty specific Hooks for that attribute
 
42
 
 
43
    def register_lazy_hook(self, hook_module_name, hook_member_name,
 
44
            hook_factory_member_name):
 
45
        self.register_lazy((hook_module_name, hook_member_name),
 
46
            hook_module_name, hook_factory_member_name)
 
47
 
 
48
    def iter_parent_objects(self):
 
49
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
 
50
        hook, where 'parent_object' is the object that holds the hook
 
51
        instance.
 
52
 
 
53
        This is useful for resetting/restoring all the hooks to a known state,
 
54
        as is done in bzrlib.tests.TestCase._clear_hooks.
 
55
        """
 
56
        for key in self.keys():
 
57
            yield key, self.key_to_parent_and_attribute(key)
 
58
 
 
59
    def key_to_parent_and_attribute(self, (module_name, member_name)):
 
60
        """Convert a known_hooks key to a (parent_obj, attr) pair.
 
61
 
 
62
        :param key: A tuple (module_name, member_name) as found in the keys of
 
63
            the known_hooks registry.
 
64
        :return: The parent_object of the hook and the name of the attribute on
 
65
            that parent object where the hook is kept.
 
66
        """
 
67
        parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
 
68
            member_name)
 
69
        return pyutils.get_named_object(parent_mod, parent_member), attr
 
70
 
 
71
 
 
72
_builtin_known_hooks = (
 
73
    ('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
 
74
    ('bzrlib.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
 
75
    ('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
 
76
    ('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
 
77
    ('bzrlib.info', 'hooks', 'InfoHooks'),
 
78
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
 
79
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
 
80
    ('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
 
81
    ('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
 
82
    ('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
 
83
    ('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
 
84
    ('bzrlib.status', 'hooks', 'StatusHooks'),
 
85
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
 
86
        'RioVersionInfoBuilderHooks'),
 
87
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
 
88
        'MergeDirectiveHooks'),
 
89
    )
 
90
 
 
91
known_hooks = KnownHooksRegistry()
 
92
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
 
93
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
 
94
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
65
95
 
66
96
 
67
97
def known_hooks_key_to_object((module_name, member_name)):
71
101
        the known_hooks registry.
72
102
    :return: The object this specifies.
73
103
    """
74
 
    return registry._LazyObjectGetter(module_name, member_name).get_obj()
75
 
 
76
 
 
77
 
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
78
 
    """Convert a known_hooks key to a object.
79
 
 
80
 
    :param key: A tuple (module_name, member_name) as found in the keys of
81
 
        the known_hooks registry.
82
 
    :return: The object this specifies.
83
 
    """
84
 
    member_list = member_name.rsplit('.', 1)
85
 
    if len(member_list) == 2:
86
 
        parent_name, attribute = member_list
87
 
    else:
88
 
        parent_name = None
89
 
        attribute = member_name
90
 
    parent = known_hooks_key_to_object((module_name, parent_name))
91
 
    return parent, attribute
 
104
    return pyutils.get_named_object(module_name, member_name)
 
105
 
 
106
 
 
107
@symbol_versioning.deprecated_function(symbol_versioning.deprecated_in((2, 3)))
 
108
def known_hooks_key_to_parent_and_attribute(key):
 
109
    """See KnownHooksRegistry.key_to_parent_and_attribute."""
 
110
    return known_hooks.key_to_parent_and_attribute(key)
92
111
 
93
112
 
94
113
class Hooks(dict):
98
117
    FOO hook is triggered.
99
118
    """
100
119
 
101
 
    def __init__(self):
 
120
    def __init__(self, module=None, member_name=None):
 
121
        """Create a new hooks dictionary.
 
122
 
 
123
        :param module: The module from which this hooks dictionary should be loaded
 
124
            (used for lazy hooks)
 
125
        :param member_name: Name under which this hooks dictionary should be loaded.
 
126
            (used for lazy hooks)
 
127
        """
102
128
        dict.__init__(self)
103
129
        self._callable_names = {}
104
 
 
 
130
        self._lazy_callable_names = {}
 
131
        self._module = module
 
132
        self._member_name = member_name
 
133
 
 
134
    def add_hook(self, name, doc, introduced, deprecated=None):
 
135
        """Add a hook point to this dictionary.
 
136
 
 
137
        :param name: The name of the hook, for clients to use when registering.
 
138
        :param doc: The docs for the hook.
 
139
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
140
        :param deprecated: When the hook was deprecated, None for
 
141
            not-deprecated.
 
142
        """
 
143
        if name in self:
 
144
            raise errors.DuplicateKey(name)
 
145
        if self._module:
 
146
            callbacks = _lazy_hooks.setdefault(
 
147
                (self._module, self._member_name, name), [])
 
148
        else:
 
149
            callbacks = None
 
150
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
 
151
                              deprecated=deprecated, callbacks=callbacks)
 
152
        self[name] = hookpoint
 
153
 
 
154
    @symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
105
155
    def create_hook(self, hook):
106
156
        """Create a hook which can have callbacks registered for it.
107
157
 
147
197
        the code names are rarely meaningful for end users and this is not
148
198
        intended for debugging.
149
199
        """
150
 
        return self._callable_names.get(a_callable, "No hook name")
 
200
        name = self._callable_names.get(a_callable, None)
 
201
        if name is None and a_callable is not None:
 
202
            name = self._lazy_callable_names.get((a_callable.__module__,
 
203
                                                  a_callable.__name__),
 
204
                                                 None)
 
205
        if name is None:
 
206
            return 'No hook name'
 
207
        return name
 
208
 
 
209
 
 
210
    def install_named_hook_lazy(self, hook_name, callable_module,
 
211
        callable_member, name):
 
212
        """Install a_callable in to the hook hook_name lazily, and label it.
 
213
 
 
214
        :param hook_name: A hook name. See the __init__ method for the complete
 
215
            list of hooks.
 
216
        :param callable_module: Name of the module in which the callable is
 
217
            present.
 
218
        :param callable_member: Member name of the callable.
 
219
        :param name: A name to associate the callable with, to show users what
 
220
            is running.
 
221
        """
 
222
        try:
 
223
            hook = self[hook_name]
 
224
        except KeyError:
 
225
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
226
        try:
 
227
            hook_lazy = getattr(hook, "hook_lazy")
 
228
        except AttributeError:
 
229
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
 
230
                self)
 
231
        else:
 
232
            hook_lazy(callable_module, callable_member, name)
 
233
        if name is not None:
 
234
            self.name_hook_lazy(callable_module, callable_member, name)
151
235
 
152
236
    def install_named_hook(self, hook_name, a_callable, name):
153
237
        """Install a_callable in to the hook hook_name, and label it name.
154
238
 
155
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
156
 
            for the complete list of hooks.
 
239
        :param hook_name: A hook name. See the __init__ method for the complete
 
240
            list of hooks.
157
241
        :param a_callable: The callable to be invoked when the hook triggers.
158
242
            The exact signature will depend on the hook - see the __init__
159
 
            method of BranchHooks for details on each hook.
 
243
            method for details on each hook.
160
244
        :param name: A name to associate a_callable with, to show users what is
161
245
            running.
162
246
        """
172
256
        if name is not None:
173
257
            self.name_hook(a_callable, name)
174
258
 
 
259
    def uninstall_named_hook(self, hook_name, label):
 
260
        """Uninstall named hooks.
 
261
 
 
262
        :param hook_name: Hook point name
 
263
        :param label: Label of the callable to uninstall
 
264
        """
 
265
        try:
 
266
            hook = self[hook_name]
 
267
        except KeyError:
 
268
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
269
        try:
 
270
            uninstall = getattr(hook, "uninstall")
 
271
        except AttributeError:
 
272
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
 
273
        else:
 
274
            uninstall(label)
 
275
 
175
276
    def name_hook(self, a_callable, name):
176
277
        """Associate name with a_callable to show users what is running."""
177
278
        self._callable_names[a_callable] = name
178
279
 
 
280
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
 
281
        self._lazy_callable_names[(callable_module, callable_member)]= \
 
282
            callable_name
 
283
 
179
284
 
180
285
class HookPoint(object):
181
286
    """A single hook that clients can register to be called back when it fires.
190
295
        should describe the recommended replacement hook to register for.
191
296
    """
192
297
 
193
 
    def __init__(self, name, doc, introduced, deprecated):
 
298
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
194
299
        """Create a HookPoint.
195
300
 
196
301
        :param name: The name of the hook, for clients to use when registering.
203
308
        self.__doc__ = doc
204
309
        self.introduced = introduced
205
310
        self.deprecated = deprecated
206
 
        self._callbacks = []
207
 
        self._callback_names = {}
 
311
        if callbacks is None:
 
312
            self._callbacks = []
 
313
        else:
 
314
            self._callbacks = callbacks
208
315
 
209
316
    def docs(self):
210
317
        """Generate the documentation for this HookPoint.
219
326
            introduced_string = _format_version_tuple(self.introduced)
220
327
        else:
221
328
            introduced_string = 'unknown'
222
 
        strings.append('Introduced in: %s' % introduced_string)
 
329
        strings.append(gettext('Introduced in: %s') % introduced_string)
223
330
        if self.deprecated:
224
331
            deprecated_string = _format_version_tuple(self.deprecated)
225
 
            strings.append('Deprecated in: %s' % deprecated_string)
 
332
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
226
333
        strings.append('')
227
334
        strings.extend(textwrap.wrap(self.__doc__,
228
335
            break_long_words=False))
230
337
        return '\n'.join(strings)
231
338
 
232
339
    def __eq__(self, other):
233
 
        return (type(other) == type(self) and 
234
 
            other.__dict__ == self.__dict__)
 
340
        return (type(other) == type(self) and other.__dict__ == self.__dict__)
 
341
 
 
342
    def hook_lazy(self, callback_module, callback_member, callback_label):
 
343
        """Lazily register a callback to be called when this HookPoint fires.
 
344
 
 
345
        :param callback_module: Module of the callable to use when this
 
346
            HookPoint fires.
 
347
        :param callback_member: Member name of the callback.
 
348
        :param callback_label: A label to show in the UI while this callback is
 
349
            processing.
 
350
        """
 
351
        obj_getter = registry._LazyObjectGetter(callback_module,
 
352
            callback_member)
 
353
        self._callbacks.append((obj_getter, callback_label))
235
354
 
236
355
    def hook(self, callback, callback_label):
237
356
        """Register a callback to be called when this HookPoint fires.
240
359
        :param callback_label: A label to show in the UI while this callback is
241
360
            processing.
242
361
        """
243
 
        self._callbacks.append(callback)
244
 
        if callback_label is not None:
245
 
            self._callback_names[callback] = callback_label
 
362
        obj_getter = registry._ObjectGetter(callback)
 
363
        self._callbacks.append((obj_getter, callback_label))
 
364
 
 
365
    def uninstall(self, label):
 
366
        """Uninstall the callback with the specified label.
 
367
 
 
368
        :param label: Label of the entry to uninstall
 
369
        """
 
370
        entries_to_remove = []
 
371
        for entry in self._callbacks:
 
372
            (entry_callback, entry_label) = entry
 
373
            if entry_label == label:
 
374
                entries_to_remove.append(entry)
 
375
        if entries_to_remove == []:
 
376
            raise KeyError("No entry with label %r" % label)
 
377
        for entry in entries_to_remove:
 
378
            self._callbacks.remove(entry)
246
379
 
247
380
    def __iter__(self):
248
 
        return iter(self._callbacks)
 
381
        return (callback.get_obj() for callback, name in self._callbacks)
249
382
 
250
383
    def __len__(self):
251
384
        return len(self._callbacks)
255
388
        strings.append("<%s(" % type(self).__name__)
256
389
        strings.append(self.name)
257
390
        strings.append("), callbacks=[")
258
 
        for callback in self._callbacks:
259
 
            strings.append(repr(callback))
 
391
        callbacks = self._callbacks
 
392
        for (callback, callback_name) in callbacks:
 
393
            strings.append(repr(callback.get_obj()))
260
394
            strings.append("(")
261
 
            strings.append(self._callback_names[callback])
 
395
            strings.append(callback_name)
262
396
            strings.append("),")
263
 
        if len(self._callbacks) == 1:
 
397
        if len(callbacks) == 1:
264
398
            strings[-1] = ")"
265
399
        strings.append("]>")
266
400
        return ''.join(strings)
305
439
        hooks = known_hooks_key_to_object(hook_key)
306
440
        segments.append(hooks.docs())
307
441
    return '\n'.join(segments)
 
442
 
 
443
 
 
444
# Lazily registered hooks. Maps (module, name, hook_name) tuples
 
445
# to lists of tuples with objectgetters and names
 
446
_lazy_hooks = {}
 
447
 
 
448
 
 
449
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
 
450
    a_callable, name):
 
451
    """Install a callable in to a hook lazily, and label it name.
 
452
 
 
453
    :param hookpoints_module: Module name of the hook points.
 
454
    :param hookpoints_name: Name of the hook points.
 
455
    :param hook_name: A hook name.
 
456
    :param callable: a callable to call for the hook.
 
457
    :param name: A name to associate a_callable with, to show users what is
 
458
        running.
 
459
    """
 
460
    key = (hookpoints_module, hookpoints_name, hook_name)
 
461
    obj_getter = registry._ObjectGetter(a_callable)
 
462
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))