← 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-05-08 11:20:31 UTC
  • mto: This revision was merged to the branch mainline in revision 5844.
  • Revision ID: jelmer@samba.org-20110508112031-dqa1cw1gjhqsj2zr
Move vf-specific gather_stats bits to vf_repository.

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(('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')
 
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.info', 'hooks', 'InfoHooks'),
 
76
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
 
77
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
 
78
    ('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
 
79
    ('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
 
80
    ('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
 
81
    ('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
 
82
    ('bzrlib.status', 'hooks', 'StatusHooks'),
 
83
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
 
84
        'RioVersionInfoBuilderHooks'),
 
85
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
 
86
        'MergeDirectiveHooks'),
 
87
    )
 
88
 
 
89
known_hooks = KnownHooksRegistry()
 
90
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
 
91
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
 
92
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
65
93
 
66
94
 
67
95
def known_hooks_key_to_object((module_name, member_name)):
71
99
        the known_hooks registry.
72
100
    :return: The object this specifies.
73
101
    """
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
 
102
    return pyutils.get_named_object(module_name, member_name)
 
103
 
 
104
 
 
105
@symbol_versioning.deprecated_function(symbol_versioning.deprecated_in((2, 3)))
 
106
def known_hooks_key_to_parent_and_attribute(key):
 
107
    """See KnownHooksRegistry.key_to_parent_and_attribute."""
 
108
    return known_hooks.key_to_parent_and_attribute(key)
92
109
 
93
110
 
94
111
class Hooks(dict):
98
115
    FOO hook is triggered.
99
116
    """
100
117
 
101
 
    def __init__(self):
 
118
    def __init__(self, module=None, member_name=None):
 
119
        """Create a new hooks dictionary.
 
120
 
 
121
        :param module: The module from which this hooks dictionary should be loaded
 
122
            (used for lazy hooks)
 
123
        :param member_name: Name under which this hooks dictionary should be loaded.
 
124
            (used for lazy hooks)
 
125
        """
102
126
        dict.__init__(self)
103
127
        self._callable_names = {}
104
 
 
 
128
        self._module = module
 
129
        self._member_name = member_name
 
130
 
 
131
    def add_hook(self, name, doc, introduced, deprecated=None):
 
132
        """Add a hook point to this dictionary.
 
133
 
 
134
        :param name: The name of the hook, for clients to use when registering.
 
135
        :param doc: The docs for the hook.
 
136
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
137
        :param deprecated: When the hook was deprecated, None for
 
138
            not-deprecated.
 
139
        """
 
140
        if name in self:
 
141
            raise errors.DuplicateKey(name)
 
142
        if self._module:
 
143
            callbacks = _lazy_hooks.setdefault(
 
144
                (self._module, self._member_name, name), [])
 
145
        else:
 
146
            callbacks = None
 
147
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
 
148
                              deprecated=deprecated, callbacks=callbacks)
 
149
        self[name] = hookpoint
 
150
 
 
151
    @symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
105
152
    def create_hook(self, hook):
106
153
        """Create a hook which can have callbacks registered for it.
107
154
 
149
196
        """
150
197
        return self._callable_names.get(a_callable, "No hook name")
151
198
 
 
199
    def install_named_hook_lazy(self, hook_name, callable_module,
 
200
        callable_member, name):
 
201
        """Install a_callable in to the hook hook_name lazily, and label it.
 
202
 
 
203
        :param hook_name: A hook name. See the __init__ method for the complete
 
204
            list of hooks.
 
205
        :param callable_module: Name of the module in which the callable is
 
206
            present.
 
207
        :param callable_member: Member name of the callable.
 
208
        :param name: A name to associate the callable with, to show users what
 
209
            is running.
 
210
        """
 
211
        try:
 
212
            hook = self[hook_name]
 
213
        except KeyError:
 
214
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
215
        try:
 
216
            hook_lazy = getattr(hook, "hook_lazy")
 
217
        except AttributeError:
 
218
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
 
219
                self)
 
220
        else:
 
221
            hook_lazy(callable_module, callable_member, name)
 
222
 
152
223
    def install_named_hook(self, hook_name, a_callable, name):
153
224
        """Install a_callable in to the hook hook_name, and label it name.
154
225
 
155
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
156
 
            for the complete list of hooks.
 
226
        :param hook_name: A hook name. See the __init__ method for the complete
 
227
            list of hooks.
157
228
        :param a_callable: The callable to be invoked when the hook triggers.
158
229
            The exact signature will depend on the hook - see the __init__
159
 
            method of BranchHooks for details on each hook.
 
230
            method for details on each hook.
160
231
        :param name: A name to associate a_callable with, to show users what is
161
232
            running.
162
233
        """
172
243
        if name is not None:
173
244
            self.name_hook(a_callable, name)
174
245
 
 
246
    def uninstall_named_hook(self, hook_name, label):
 
247
        """Uninstall named hooks.
 
248
 
 
249
        :param hook_name: Hook point name
 
250
        :param label: Label of the callable to uninstall
 
251
        """
 
252
        try:
 
253
            hook = self[hook_name]
 
254
        except KeyError:
 
255
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
256
        try:
 
257
            uninstall = getattr(hook, "uninstall")
 
258
        except AttributeError:
 
259
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
 
260
                self)
 
261
        else:
 
262
            uninstall(label)
 
263
 
175
264
    def name_hook(self, a_callable, name):
176
265
        """Associate name with a_callable to show users what is running."""
177
266
        self._callable_names[a_callable] = name
190
279
        should describe the recommended replacement hook to register for.
191
280
    """
192
281
 
193
 
    def __init__(self, name, doc, introduced, deprecated):
 
282
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
194
283
        """Create a HookPoint.
195
284
 
196
285
        :param name: The name of the hook, for clients to use when registering.
203
292
        self.__doc__ = doc
204
293
        self.introduced = introduced
205
294
        self.deprecated = deprecated
206
 
        self._callbacks = []
207
 
        self._callback_names = {}
 
295
        if callbacks is None:
 
296
            self._callbacks = []
 
297
        else:
 
298
            self._callbacks = callbacks
208
299
 
209
300
    def docs(self):
210
301
        """Generate the documentation for this HookPoint.
230
321
        return '\n'.join(strings)
231
322
 
232
323
    def __eq__(self, other):
233
 
        return (type(other) == type(self) and 
234
 
            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))
235
338
 
236
339
    def hook(self, callback, callback_label):
237
340
        """Register a callback to be called when this HookPoint fires.
240
343
        :param callback_label: A label to show in the UI while this callback is
241
344
            processing.
242
345
        """
243
 
        self._callbacks.append(callback)
244
 
        if callback_label is not None:
245
 
            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)
246
363
 
247
364
    def __iter__(self):
248
 
        return iter(self._callbacks)
 
365
        return (callback.get_obj() for callback, name in self._callbacks)
249
366
 
250
367
    def __len__(self):
251
368
        return len(self._callbacks)
255
372
        strings.append("<%s(" % type(self).__name__)
256
373
        strings.append(self.name)
257
374
        strings.append("), callbacks=[")
258
 
        for callback in self._callbacks:
259
 
            strings.append(repr(callback))
 
375
        callbacks = self._callbacks
 
376
        for (callback, callback_name) in callbacks:
 
377
            strings.append(repr(callback.get_obj()))
260
378
            strings.append("(")
261
 
            strings.append(self._callback_names[callback])
 
379
            strings.append(callback_name)
262
380
            strings.append("),")
263
 
        if len(self._callbacks) == 1:
 
381
        if len(callbacks) == 1:
264
382
            strings[-1] = ")"
265
383
        strings.append("]>")
266
384
        return ''.join(strings)
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))