← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Martin Packman
  • Date: 2011-10-06 16:41:45 UTC
  • mfrom: (6015.33.10 2.4)
  • mto: This revision was merged to the branch mainline in revision 6202.
  • Revision ID: martin.packman@canonical.com-20111006164145-o98oqn32440extgt
Merge 2.4 into dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/hooks.py
1
 
# Copyright (C) 2007, 2008 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
 
from bzrlib.symbol_versioning import deprecated_method
22
25
lazy_import(globals(), """
23
26
import textwrap
24
27
 
25
28
from bzrlib import (
26
 
        _format_version_tuple,
27
 
        errors,
28
 
        )
29
 
from bzrlib.help_topics import help_as_plain_text
 
29
    _format_version_tuple,
 
30
    errors,
 
31
    pyutils,
 
32
    )
 
33
from bzrlib.i18n import gettext
30
34
""")
31
35
 
32
36
 
33
 
known_hooks = registry.Registry()
34
 
# known_hooks registry contains
35
 
# tuple of (module, member name) which is the hook point
36
 
# module where the specific hooks are defined
37
 
# callable to get the empty specific Hooks for that attribute
38
 
known_hooks.register_lazy(('bzrlib.branch', 'Branch.hooks'), 'bzrlib.branch',
39
 
    'BranchHooks')
40
 
known_hooks.register_lazy(('bzrlib.bzrdir', 'BzrDir.hooks'), 'bzrlib.bzrdir',
41
 
    'BzrDirHooks')
42
 
known_hooks.register_lazy(('bzrlib.commands', 'Command.hooks'),
43
 
    'bzrlib.commands', 'CommandHooks')
44
 
known_hooks.register_lazy(('bzrlib.info', 'hooks'),
45
 
    'bzrlib.info', 'InfoHooks')
46
 
known_hooks.register_lazy(('bzrlib.lock', 'Lock.hooks'), 'bzrlib.lock',
47
 
    'LockHooks')
48
 
known_hooks.register_lazy(('bzrlib.msgeditor', 'hooks'), 'bzrlib.msgeditor',
49
 
    'MessageEditorHooks')
50
 
known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),
51
 
    'bzrlib.mutabletree', 'MutableTreeHooks')
52
 
known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),
53
 
    'bzrlib.smart.client', 'SmartClientHooks')
54
 
known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),
55
 
    'bzrlib.smart.server', 'SmartServerHooks')
56
 
known_hooks.register_lazy(
57
 
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks'),
58
 
    'bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilderHooks')
59
 
known_hooks.register_lazy(
60
 
    ('bzrlib.merge_directive', '_BaseMergeDirective.hooks'),
61
 
    '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.bzrdir', 'BzrDir.hooks', 'BzrDirHooks'),
 
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
62
95
 
63
96
 
64
97
def known_hooks_key_to_object((module_name, member_name)):
68
101
        the known_hooks registry.
69
102
    :return: The object this specifies.
70
103
    """
71
 
    return registry._LazyObjectGetter(module_name, member_name).get_obj()
72
 
 
73
 
 
74
 
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
75
 
    """Convert a known_hooks key to a object.
76
 
 
77
 
    :param key: A tuple (module_name, member_name) as found in the keys of
78
 
        the known_hooks registry.
79
 
    :return: The object this specifies.
80
 
    """
81
 
    member_list = member_name.rsplit('.', 1)
82
 
    if len(member_list) == 2:
83
 
        parent_name, attribute = member_list
84
 
    else:
85
 
        parent_name = None
86
 
        attribute = member_name
87
 
    parent = known_hooks_key_to_object((module_name, parent_name))
88
 
    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)
89
111
 
90
112
 
91
113
class Hooks(dict):
95
117
    FOO hook is triggered.
96
118
    """
97
119
 
98
 
    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
        """
99
128
        dict.__init__(self)
100
129
        self._callable_names = {}
101
 
 
 
130
        self._module = module
 
131
        self._member_name = member_name
 
132
 
 
133
    def add_hook(self, name, doc, introduced, deprecated=None):
 
134
        """Add a hook point to this dictionary.
 
135
 
 
136
        :param name: The name of the hook, for clients to use when registering.
 
137
        :param doc: The docs for the hook.
 
138
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
139
        :param deprecated: When the hook was deprecated, None for
 
140
            not-deprecated.
 
141
        """
 
142
        if name in self:
 
143
            raise errors.DuplicateKey(name)
 
144
        if self._module:
 
145
            callbacks = _lazy_hooks.setdefault(
 
146
                (self._module, self._member_name, name), [])
 
147
        else:
 
148
            callbacks = None
 
149
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
 
150
                              deprecated=deprecated, callbacks=callbacks)
 
151
        self[name] = hookpoint
 
152
 
 
153
    @symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
102
154
    def create_hook(self, hook):
103
155
        """Create a hook which can have callbacks registered for it.
104
156
 
146
198
        """
147
199
        return self._callable_names.get(a_callable, "No hook name")
148
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 errors.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
 
149
225
    def install_named_hook(self, hook_name, a_callable, name):
150
226
        """Install a_callable in to the hook hook_name, and label it name.
151
227
 
152
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
153
 
            for the complete list of hooks.
 
228
        :param hook_name: A hook name. See the __init__ method for the complete
 
229
            list of hooks.
154
230
        :param a_callable: The callable to be invoked when the hook triggers.
155
231
            The exact signature will depend on the hook - see the __init__
156
 
            method of BranchHooks for details on each hook.
 
232
            method for details on each hook.
157
233
        :param name: A name to associate a_callable with, to show users what is
158
234
            running.
159
235
        """
169
245
        if name is not None:
170
246
            self.name_hook(a_callable, name)
171
247
 
 
248
    def uninstall_named_hook(self, hook_name, label):
 
249
        """Uninstall named hooks.
 
250
 
 
251
        :param hook_name: Hook point name
 
252
        :param label: Label of the callable to uninstall
 
253
        """
 
254
        try:
 
255
            hook = self[hook_name]
 
256
        except KeyError:
 
257
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
258
        try:
 
259
            uninstall = getattr(hook, "uninstall")
 
260
        except AttributeError:
 
261
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
 
262
        else:
 
263
            uninstall(label)
 
264
 
172
265
    def name_hook(self, a_callable, name):
173
266
        """Associate name with a_callable to show users what is running."""
174
267
        self._callable_names[a_callable] = name
178
271
    """A single hook that clients can register to be called back when it fires.
179
272
 
180
273
    :ivar name: The name of the hook.
 
274
    :ivar doc: The docs for using the hook.
181
275
    :ivar introduced: A version tuple specifying what version the hook was
182
276
        introduced in. None indicates an unknown version.
183
277
    :ivar deprecated: A version tuple specifying what version the hook was
184
278
        deprecated or superseded in. None indicates that the hook is not
185
279
        superseded or deprecated. If the hook is superseded then the doc
186
280
        should describe the recommended replacement hook to register for.
187
 
    :ivar doc: The docs for using the hook.
188
281
    """
189
282
 
190
 
    def __init__(self, name, doc, introduced, deprecated):
 
283
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
191
284
        """Create a HookPoint.
192
285
 
193
286
        :param name: The name of the hook, for clients to use when registering.
200
293
        self.__doc__ = doc
201
294
        self.introduced = introduced
202
295
        self.deprecated = deprecated
203
 
        self._callbacks = []
204
 
        self._callback_names = {}
 
296
        if callbacks is None:
 
297
            self._callbacks = []
 
298
        else:
 
299
            self._callbacks = callbacks
205
300
 
206
301
    def docs(self):
207
302
        """Generate the documentation for this HookPoint.
216
311
            introduced_string = _format_version_tuple(self.introduced)
217
312
        else:
218
313
            introduced_string = 'unknown'
219
 
        strings.append('Introduced in: %s' % introduced_string)
 
314
        strings.append(gettext('Introduced in: %s') % introduced_string)
220
315
        if self.deprecated:
221
316
            deprecated_string = _format_version_tuple(self.deprecated)
222
 
        else:
223
 
            deprecated_string = 'Not deprecated'
224
 
        strings.append('Deprecated in: %s' % deprecated_string)
 
317
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
225
318
        strings.append('')
226
 
        strings.extend(textwrap.wrap(self.__doc__))
 
319
        strings.extend(textwrap.wrap(self.__doc__,
 
320
            break_long_words=False))
227
321
        strings.append('')
228
322
        return '\n'.join(strings)
229
323
 
230
324
    def __eq__(self, other):
231
 
        return (type(other) == type(self) and 
232
 
            other.__dict__ == self.__dict__)
 
325
        return (type(other) == type(self) and other.__dict__ == self.__dict__)
 
326
 
 
327
    def hook_lazy(self, callback_module, callback_member, callback_label):
 
328
        """Lazily register a callback to be called when this HookPoint fires.
 
329
 
 
330
        :param callback_module: Module of the callable to use when this
 
331
            HookPoint fires.
 
332
        :param callback_member: Member name of the callback.
 
333
        :param callback_label: A label to show in the UI while this callback is
 
334
            processing.
 
335
        """
 
336
        obj_getter = registry._LazyObjectGetter(callback_module,
 
337
            callback_member)
 
338
        self._callbacks.append((obj_getter, callback_label))
233
339
 
234
340
    def hook(self, callback, callback_label):
235
341
        """Register a callback to be called when this HookPoint fires.
238
344
        :param callback_label: A label to show in the UI while this callback is
239
345
            processing.
240
346
        """
241
 
        self._callbacks.append(callback)
242
 
        if callback_label is not None:
243
 
            self._callback_names[callback] = callback_label
 
347
        obj_getter = registry._ObjectGetter(callback)
 
348
        self._callbacks.append((obj_getter, callback_label))
 
349
 
 
350
    def uninstall(self, label):
 
351
        """Uninstall the callback with the specified label.
 
352
 
 
353
        :param label: Label of the entry to uninstall
 
354
        """
 
355
        entries_to_remove = []
 
356
        for entry in self._callbacks:
 
357
            (entry_callback, entry_label) = entry
 
358
            if entry_label == label:
 
359
                entries_to_remove.append(entry)
 
360
        if entries_to_remove == []:
 
361
            raise KeyError("No entry with label %r" % label)
 
362
        for entry in entries_to_remove:
 
363
            self._callbacks.remove(entry)
244
364
 
245
365
    def __iter__(self):
246
 
        return iter(self._callbacks)
 
366
        return (callback.get_obj() for callback, name in self._callbacks)
247
367
 
248
368
    def __len__(self):
249
369
        return len(self._callbacks)
253
373
        strings.append("<%s(" % type(self).__name__)
254
374
        strings.append(self.name)
255
375
        strings.append("), callbacks=[")
256
 
        for callback in self._callbacks:
257
 
            strings.append(repr(callback))
 
376
        callbacks = self._callbacks
 
377
        for (callback, callback_name) in callbacks:
 
378
            strings.append(repr(callback.get_obj()))
258
379
            strings.append("(")
259
 
            strings.append(self._callback_names[callback])
 
380
            strings.append(callback_name)
260
381
            strings.append("),")
261
 
        if len(self._callbacks) == 1:
 
382
        if len(callbacks) == 1:
262
383
            strings[-1] = ")"
263
384
        strings.append("]>")
264
385
        return ''.join(strings)
276
397
 
277
398
  yyy.hooks.install_named_hook("xxx", ...)
278
399
 
279
 
See `Using hooks`_ in the User Guide for examples.
280
 
 
281
 
.. _Using hooks: ../user-guide/index.html#using-hooks
 
400
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
282
401
 
283
402
The class that contains each hook is given before the hooks it supplies. For
284
403
instance, BranchHooks as the class is the hooks class for
305
424
        hooks = known_hooks_key_to_object(hook_key)
306
425
        segments.append(hooks.docs())
307
426
    return '\n'.join(segments)
 
427
 
 
428
 
 
429
# Lazily registered hooks. Maps (module, name, hook_name) tuples
 
430
# to lists of tuples with objectgetters and names
 
431
_lazy_hooks = {}
 
432
 
 
433
 
 
434
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
 
435
    a_callable, name):
 
436
    """Install a callable in to a hook lazily, and label it name.
 
437
 
 
438
    :param hookpoints_module: Module name of the hook points.
 
439
    :param hookpoints_name: Name of the hook points.
 
440
    :param hook_name: A hook name.
 
441
    :param callable: a callable to call for the hook.
 
442
    :param name: A name to associate a_callable with, to show users what is
 
443
        running.
 
444
    """
 
445
    key = (hookpoints_module, hookpoints_name, hook_name)
 
446
    obj_getter = registry._ObjectGetter(a_callable)
 
447
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))