← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Martin
  • Date: 2011-08-04 00:17:53 UTC
  • mto: This revision was merged to the branch mainline in revision 6055.
  • Revision ID: gzlist@googlemail.com-20110804001753-plgpwcpsxcum16yb
Make tests raising KnownFailure use the knownFailure method instead

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
    )
29
33
""")
30
34
 
31
35
 
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')
 
36
class KnownHooksRegistry(registry.Registry):
 
37
    # known_hooks registry contains
 
38
    # tuple of (module, member name) which is the hook point
 
39
    # module where the specific hooks are defined
 
40
    # callable to get the empty specific Hooks for that attribute
 
41
 
 
42
    def register_lazy_hook(self, hook_module_name, hook_member_name,
 
43
            hook_factory_member_name):
 
44
        self.register_lazy((hook_module_name, hook_member_name),
 
45
            hook_module_name, hook_factory_member_name)
 
46
 
 
47
    def iter_parent_objects(self):
 
48
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
 
49
        hook, where 'parent_object' is the object that holds the hook
 
50
        instance.
 
51
 
 
52
        This is useful for resetting/restoring all the hooks to a known state,
 
53
        as is done in bzrlib.tests.TestCase._clear_hooks.
 
54
        """
 
55
        for key in self.keys():
 
56
            yield key, self.key_to_parent_and_attribute(key)
 
57
 
 
58
    def key_to_parent_and_attribute(self, (module_name, member_name)):
 
59
        """Convert a known_hooks key to a (parent_obj, attr) pair.
 
60
 
 
61
        :param key: A tuple (module_name, member_name) as found in the keys of
 
62
            the known_hooks registry.
 
63
        :return: The parent_object of the hook and the name of the attribute on
 
64
            that parent object where the hook is kept.
 
65
        """
 
66
        parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
 
67
            member_name)
 
68
        return pyutils.get_named_object(parent_mod, parent_member), attr
 
69
 
 
70
 
 
71
_builtin_known_hooks = (
 
72
    ('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
 
73
    ('bzrlib.bzrdir', 'BzrDir.hooks', 'BzrDirHooks'),
 
74
    ('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
 
75
    ('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
 
76
    ('bzrlib.info', 'hooks', 'InfoHooks'),
 
77
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
 
78
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
 
79
    ('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
 
80
    ('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
 
81
    ('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
 
82
    ('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
 
83
    ('bzrlib.status', 'hooks', 'StatusHooks'),
 
84
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
 
85
        'RioVersionInfoBuilderHooks'),
 
86
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
 
87
        'MergeDirectiveHooks'),
 
88
    )
 
89
 
 
90
known_hooks = KnownHooksRegistry()
 
91
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
 
92
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
 
93
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
63
94
 
64
95
 
65
96
def known_hooks_key_to_object((module_name, member_name)):
69
100
        the known_hooks registry.
70
101
    :return: The object this specifies.
71
102
    """
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
 
103
    return pyutils.get_named_object(module_name, member_name)
 
104
 
 
105
 
 
106
@symbol_versioning.deprecated_function(symbol_versioning.deprecated_in((2, 3)))
 
107
def known_hooks_key_to_parent_and_attribute(key):
 
108
    """See KnownHooksRegistry.key_to_parent_and_attribute."""
 
109
    return known_hooks.key_to_parent_and_attribute(key)
90
110
 
91
111
 
92
112
class Hooks(dict):
96
116
    FOO hook is triggered.
97
117
    """
98
118
 
99
 
    def __init__(self):
 
119
    def __init__(self, module=None, member_name=None):
 
120
        """Create a new hooks dictionary.
 
121
 
 
122
        :param module: The module from which this hooks dictionary should be loaded
 
123
            (used for lazy hooks)
 
124
        :param member_name: Name under which this hooks dictionary should be loaded.
 
125
            (used for lazy hooks)
 
126
        """
100
127
        dict.__init__(self)
101
128
        self._callable_names = {}
102
 
 
 
129
        self._module = module
 
130
        self._member_name = member_name
 
131
 
 
132
    def add_hook(self, name, doc, introduced, deprecated=None):
 
133
        """Add a hook point to this dictionary.
 
134
 
 
135
        :param name: The name of the hook, for clients to use when registering.
 
136
        :param doc: The docs for the hook.
 
137
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
138
        :param deprecated: When the hook was deprecated, None for
 
139
            not-deprecated.
 
140
        """
 
141
        if name in self:
 
142
            raise errors.DuplicateKey(name)
 
143
        if self._module:
 
144
            callbacks = _lazy_hooks.setdefault(
 
145
                (self._module, self._member_name, name), [])
 
146
        else:
 
147
            callbacks = None
 
148
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
 
149
                              deprecated=deprecated, callbacks=callbacks)
 
150
        self[name] = hookpoint
 
151
 
 
152
    @symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
103
153
    def create_hook(self, hook):
104
154
        """Create a hook which can have callbacks registered for it.
105
155
 
147
197
        """
148
198
        return self._callable_names.get(a_callable, "No hook name")
149
199
 
 
200
    def install_named_hook_lazy(self, hook_name, callable_module,
 
201
        callable_member, name):
 
202
        """Install a_callable in to the hook hook_name lazily, and label it.
 
203
 
 
204
        :param hook_name: A hook name. See the __init__ method for the complete
 
205
            list of hooks.
 
206
        :param callable_module: Name of the module in which the callable is
 
207
            present.
 
208
        :param callable_member: Member name of the callable.
 
209
        :param name: A name to associate the callable with, to show users what
 
210
            is running.
 
211
        """
 
212
        try:
 
213
            hook = self[hook_name]
 
214
        except KeyError:
 
215
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
216
        try:
 
217
            hook_lazy = getattr(hook, "hook_lazy")
 
218
        except AttributeError:
 
219
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
 
220
                self)
 
221
        else:
 
222
            hook_lazy(callable_module, callable_member, name)
 
223
 
150
224
    def install_named_hook(self, hook_name, a_callable, name):
151
225
        """Install a_callable in to the hook hook_name, and label it name.
152
226
 
153
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
154
 
            for the complete list of hooks.
 
227
        :param hook_name: A hook name. See the __init__ method for the complete
 
228
            list of hooks.
155
229
        :param a_callable: The callable to be invoked when the hook triggers.
156
230
            The exact signature will depend on the hook - see the __init__
157
 
            method of BranchHooks for details on each hook.
 
231
            method for details on each hook.
158
232
        :param name: A name to associate a_callable with, to show users what is
159
233
            running.
160
234
        """
170
244
        if name is not None:
171
245
            self.name_hook(a_callable, name)
172
246
 
 
247
    def uninstall_named_hook(self, hook_name, label):
 
248
        """Uninstall named hooks.
 
249
 
 
250
        :param hook_name: Hook point name
 
251
        :param label: Label of the callable to uninstall
 
252
        """
 
253
        try:
 
254
            hook = self[hook_name]
 
255
        except KeyError:
 
256
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
257
        try:
 
258
            uninstall = getattr(hook, "uninstall")
 
259
        except AttributeError:
 
260
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
 
261
        else:
 
262
            uninstall(label)
 
263
 
173
264
    def name_hook(self, a_callable, name):
174
265
        """Associate name with a_callable to show users what is running."""
175
266
        self._callable_names[a_callable] = name
179
270
    """A single hook that clients can register to be called back when it fires.
180
271
 
181
272
    :ivar name: The name of the hook.
 
273
    :ivar doc: The docs for using the hook.
182
274
    :ivar introduced: A version tuple specifying what version the hook was
183
275
        introduced in. None indicates an unknown version.
184
276
    :ivar deprecated: A version tuple specifying what version the hook was
185
277
        deprecated or superseded in. None indicates that the hook is not
186
278
        superseded or deprecated. If the hook is superseded then the doc
187
279
        should describe the recommended replacement hook to register for.
188
 
    :ivar doc: The docs for using the hook.
189
280
    """
190
281
 
191
 
    def __init__(self, name, doc, introduced, deprecated):
 
282
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
192
283
        """Create a HookPoint.
193
284
 
194
285
        :param name: The name of the hook, for clients to use when registering.
201
292
        self.__doc__ = doc
202
293
        self.introduced = introduced
203
294
        self.deprecated = deprecated
204
 
        self._callbacks = []
205
 
        self._callback_names = {}
 
295
        if callbacks is None:
 
296
            self._callbacks = []
 
297
        else:
 
298
            self._callbacks = callbacks
206
299
 
207
300
    def docs(self):
208
301
        """Generate the documentation for this HookPoint.
228
321
        return '\n'.join(strings)
229
322
 
230
323
    def __eq__(self, other):
231
 
        return (type(other) == type(self) and 
232
 
            other.__dict__ == self.__dict__)
 
324
        return (type(other) == type(self) and other.__dict__ == self.__dict__)
 
325
 
 
326
    def hook_lazy(self, callback_module, callback_member, callback_label):
 
327
        """Lazily register a callback to be called when this HookPoint fires.
 
328
 
 
329
        :param callback_module: Module of the callable to use when this
 
330
            HookPoint fires.
 
331
        :param callback_member: Member name of the callback.
 
332
        :param callback_label: A label to show in the UI while this callback is
 
333
            processing.
 
334
        """
 
335
        obj_getter = registry._LazyObjectGetter(callback_module,
 
336
            callback_member)
 
337
        self._callbacks.append((obj_getter, callback_label))
233
338
 
234
339
    def hook(self, callback, callback_label):
235
340
        """Register a callback to be called when this HookPoint fires.
238
343
        :param callback_label: A label to show in the UI while this callback is
239
344
            processing.
240
345
        """
241
 
        self._callbacks.append(callback)
242
 
        if callback_label is not None:
243
 
            self._callback_names[callback] = callback_label
 
346
        obj_getter = registry._ObjectGetter(callback)
 
347
        self._callbacks.append((obj_getter, callback_label))
 
348
 
 
349
    def uninstall(self, label):
 
350
        """Uninstall the callback with the specified label.
 
351
 
 
352
        :param label: Label of the entry to uninstall
 
353
        """
 
354
        entries_to_remove = []
 
355
        for entry in self._callbacks:
 
356
            (entry_callback, entry_label) = entry
 
357
            if entry_label == label:
 
358
                entries_to_remove.append(entry)
 
359
        if entries_to_remove == []:
 
360
            raise KeyError("No entry with label %r" % label)
 
361
        for entry in entries_to_remove:
 
362
            self._callbacks.remove(entry)
244
363
 
245
364
    def __iter__(self):
246
 
        return iter(self._callbacks)
 
365
        return (callback.get_obj() for callback, name in self._callbacks)
247
366
 
248
367
    def __len__(self):
249
368
        return len(self._callbacks)
253
372
        strings.append("<%s(" % type(self).__name__)
254
373
        strings.append(self.name)
255
374
        strings.append("), callbacks=[")
256
 
        for callback in self._callbacks:
257
 
            strings.append(repr(callback))
 
375
        callbacks = self._callbacks
 
376
        for (callback, callback_name) in callbacks:
 
377
            strings.append(repr(callback.get_obj()))
258
378
            strings.append("(")
259
 
            strings.append(self._callback_names[callback])
 
379
            strings.append(callback_name)
260
380
            strings.append("),")
261
 
        if len(self._callbacks) == 1:
 
381
        if len(callbacks) == 1:
262
382
            strings[-1] = ")"
263
383
        strings.append("]>")
264
384
        return ''.join(strings)
276
396
 
277
397
  yyy.hooks.install_named_hook("xxx", ...)
278
398
 
279
 
See `Using hooks`_ in the User Guide for examples.
280
 
 
281
 
.. _Using hooks: ../user-guide/hooks.html
 
399
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
282
400
 
283
401
The class that contains each hook is given before the hooks it supplies. For
284
402
instance, BranchHooks as the class is the hooks class for
305
423
        hooks = known_hooks_key_to_object(hook_key)
306
424
        segments.append(hooks.docs())
307
425
    return '\n'.join(segments)
 
426
 
 
427
 
 
428
# Lazily registered hooks. Maps (module, name, hook_name) tuples
 
429
# to lists of tuples with objectgetters and names
 
430
_lazy_hooks = {}
 
431
 
 
432
 
 
433
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
 
434
    a_callable, name):
 
435
    """Install a callable in to a hook lazily, and label it name.
 
436
 
 
437
    :param hookpoints_module: Module name of the hook points.
 
438
    :param hookpoints_name: Name of the hook points.
 
439
    :param hook_name: A hook name.
 
440
    :param callable: a callable to call for the hook.
 
441
    :param name: A name to associate a_callable with, to show users what is
 
442
        running.
 
443
    """
 
444
    key = (hookpoints_module, hookpoints_name, hook_name)
 
445
    obj_getter = registry._ObjectGetter(a_callable)
 
446
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))