← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-05-28 00:25:32 UTC
  • mfrom: (5264.1.2 command-help-bug-177500)
  • Revision ID: pqm@pqm.ubuntu.com-20100528002532-9bzj1fajyxckd1rg
(lifeless) Stop raising at runtime when a command has no help,
 instead have a test in the test suite that checks all known command objects.
 (Robert Collins)

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
16
16
 
17
17
 
18
18
"""Support for plugin hooking logic."""
19
 
 
20
 
from bzrlib import (
21
 
    registry,
22
 
    symbol_versioning,
23
 
    )
 
19
from bzrlib import registry
24
20
from bzrlib.lazy_import import lazy_import
25
21
lazy_import(globals(), """
26
22
import textwrap
27
23
 
28
24
from bzrlib import (
29
 
    _format_version_tuple,
30
 
    errors,
31
 
    pyutils,
32
 
    )
 
25
        _format_version_tuple,
 
26
        errors,
 
27
        )
 
28
from bzrlib.help_topics import help_as_plain_text
33
29
""")
34
30
 
35
31
 
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
 
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')
94
63
 
95
64
 
96
65
def known_hooks_key_to_object((module_name, member_name)):
100
69
        the known_hooks registry.
101
70
    :return: The object this specifies.
102
71
    """
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)
 
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
110
90
 
111
91
 
112
92
class Hooks(dict):
116
96
    FOO hook is triggered.
117
97
    """
118
98
 
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
 
        """
 
99
    def __init__(self):
127
100
        dict.__init__(self)
128
101
        self._callable_names = {}
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)))
 
102
 
153
103
    def create_hook(self, hook):
154
104
        """Create a hook which can have callbacks registered for it.
155
105
 
197
147
        """
198
148
        return self._callable_names.get(a_callable, "No hook name")
199
149
 
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
 
 
224
150
    def install_named_hook(self, hook_name, a_callable, name):
225
151
        """Install a_callable in to the hook hook_name, and label it name.
226
152
 
227
 
        :param hook_name: A hook name. See the __init__ method for the complete
228
 
            list of hooks.
 
153
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
154
            for the complete list of hooks.
229
155
        :param a_callable: The callable to be invoked when the hook triggers.
230
156
            The exact signature will depend on the hook - see the __init__
231
 
            method for details on each hook.
 
157
            method of BranchHooks for details on each hook.
232
158
        :param name: A name to associate a_callable with, to show users what is
233
159
            running.
234
160
        """
244
170
        if name is not None:
245
171
            self.name_hook(a_callable, name)
246
172
 
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
 
 
264
173
    def name_hook(self, a_callable, name):
265
174
        """Associate name with a_callable to show users what is running."""
266
175
        self._callable_names[a_callable] = name
270
179
    """A single hook that clients can register to be called back when it fires.
271
180
 
272
181
    :ivar name: The name of the hook.
273
 
    :ivar doc: The docs for using the hook.
274
182
    :ivar introduced: A version tuple specifying what version the hook was
275
183
        introduced in. None indicates an unknown version.
276
184
    :ivar deprecated: A version tuple specifying what version the hook was
277
185
        deprecated or superseded in. None indicates that the hook is not
278
186
        superseded or deprecated. If the hook is superseded then the doc
279
187
        should describe the recommended replacement hook to register for.
 
188
    :ivar doc: The docs for using the hook.
280
189
    """
281
190
 
282
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
191
    def __init__(self, name, doc, introduced, deprecated):
283
192
        """Create a HookPoint.
284
193
 
285
194
        :param name: The name of the hook, for clients to use when registering.
292
201
        self.__doc__ = doc
293
202
        self.introduced = introduced
294
203
        self.deprecated = deprecated
295
 
        if callbacks is None:
296
 
            self._callbacks = []
297
 
        else:
298
 
            self._callbacks = callbacks
 
204
        self._callbacks = []
 
205
        self._callback_names = {}
299
206
 
300
207
    def docs(self):
301
208
        """Generate the documentation for this HookPoint.
321
228
        return '\n'.join(strings)
322
229
 
323
230
    def __eq__(self, other):
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))
 
231
        return (type(other) == type(self) and 
 
232
            other.__dict__ == self.__dict__)
338
233
 
339
234
    def hook(self, callback, callback_label):
340
235
        """Register a callback to be called when this HookPoint fires.
343
238
        :param callback_label: A label to show in the UI while this callback is
344
239
            processing.
345
240
        """
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)
 
241
        self._callbacks.append(callback)
 
242
        if callback_label is not None:
 
243
            self._callback_names[callback] = callback_label
363
244
 
364
245
    def __iter__(self):
365
 
        return (callback.get_obj() for callback, name in self._callbacks)
 
246
        return iter(self._callbacks)
366
247
 
367
248
    def __len__(self):
368
249
        return len(self._callbacks)
372
253
        strings.append("<%s(" % type(self).__name__)
373
254
        strings.append(self.name)
374
255
        strings.append("), callbacks=[")
375
 
        callbacks = self._callbacks
376
 
        for (callback, callback_name) in callbacks:
377
 
            strings.append(repr(callback.get_obj()))
 
256
        for callback in self._callbacks:
 
257
            strings.append(repr(callback))
378
258
            strings.append("(")
379
 
            strings.append(callback_name)
 
259
            strings.append(self._callback_names[callback])
380
260
            strings.append("),")
381
 
        if len(callbacks) == 1:
 
261
        if len(self._callbacks) == 1:
382
262
            strings[-1] = ")"
383
263
        strings.append("]>")
384
264
        return ''.join(strings)
423
303
        hooks = known_hooks_key_to_object(hook_key)
424
304
        segments.append(hooks.docs())
425
305
    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))