← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Aaron Bentley
  • Date: 2009-06-19 21:16:31 UTC
  • mto: This revision was merged to the branch mainline in revision 4481.
  • Revision ID: aaron@aaronbentley.com-20090619211631-4fnkv2uui98xj7ux
Provide control over switch and shelver messaging.

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, 2008 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
 
21
from bzrlib.symbol_versioning import deprecated_method
25
22
lazy_import(globals(), """
26
23
import textwrap
27
24
 
28
25
from bzrlib import (
29
 
    _format_version_tuple,
30
 
    errors,
31
 
    pyutils,
32
 
    )
 
26
        _format_version_tuple,
 
27
        errors,
 
28
        )
 
29
from bzrlib.help_topics import help_as_plain_text
33
30
""")
34
31
 
35
32
 
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
 
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')
94
62
 
95
63
 
96
64
def known_hooks_key_to_object((module_name, member_name)):
100
68
        the known_hooks registry.
101
69
    :return: The object this specifies.
102
70
    """
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)
 
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
110
89
 
111
90
 
112
91
class Hooks(dict):
116
95
    FOO hook is triggered.
117
96
    """
118
97
 
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
 
        """
 
98
    def __init__(self):
127
99
        dict.__init__(self)
128
100
        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)))
 
101
 
153
102
    def create_hook(self, hook):
154
103
        """Create a hook which can have callbacks registered for it.
155
104
 
197
146
        """
198
147
        return self._callable_names.get(a_callable, "No hook name")
199
148
 
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
149
    def install_named_hook(self, hook_name, a_callable, name):
225
150
        """Install a_callable in to the hook hook_name, and label it name.
226
151
 
227
 
        :param hook_name: A hook name. See the __init__ method for the complete
228
 
            list of hooks.
 
152
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
153
            for the complete list of hooks.
229
154
        :param a_callable: The callable to be invoked when the hook triggers.
230
155
            The exact signature will depend on the hook - see the __init__
231
 
            method for details on each hook.
 
156
            method of BranchHooks for details on each hook.
232
157
        :param name: A name to associate a_callable with, to show users what is
233
158
            running.
234
159
        """
244
169
        if name is not None:
245
170
            self.name_hook(a_callable, name)
246
171
 
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
172
    def name_hook(self, a_callable, name):
265
173
        """Associate name with a_callable to show users what is running."""
266
174
        self._callable_names[a_callable] = name
270
178
    """A single hook that clients can register to be called back when it fires.
271
179
 
272
180
    :ivar name: The name of the hook.
273
 
    :ivar doc: The docs for using the hook.
274
181
    :ivar introduced: A version tuple specifying what version the hook was
275
182
        introduced in. None indicates an unknown version.
276
183
    :ivar deprecated: A version tuple specifying what version the hook was
277
184
        deprecated or superseded in. None indicates that the hook is not
278
185
        superseded or deprecated. If the hook is superseded then the doc
279
186
        should describe the recommended replacement hook to register for.
 
187
    :ivar doc: The docs for using the hook.
280
188
    """
281
189
 
282
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
190
    def __init__(self, name, doc, introduced, deprecated):
283
191
        """Create a HookPoint.
284
192
 
285
193
        :param name: The name of the hook, for clients to use when registering.
292
200
        self.__doc__ = doc
293
201
        self.introduced = introduced
294
202
        self.deprecated = deprecated
295
 
        if callbacks is None:
296
 
            self._callbacks = []
297
 
        else:
298
 
            self._callbacks = callbacks
 
203
        self._callbacks = []
 
204
        self._callback_names = {}
299
205
 
300
206
    def docs(self):
301
207
        """Generate the documentation for this HookPoint.
313
219
        strings.append('Introduced in: %s' % introduced_string)
314
220
        if self.deprecated:
315
221
            deprecated_string = _format_version_tuple(self.deprecated)
316
 
            strings.append('Deprecated in: %s' % deprecated_string)
 
222
        else:
 
223
            deprecated_string = 'Not deprecated'
 
224
        strings.append('Deprecated in: %s' % deprecated_string)
317
225
        strings.append('')
318
 
        strings.extend(textwrap.wrap(self.__doc__,
319
 
            break_long_words=False))
 
226
        strings.extend(textwrap.wrap(self.__doc__))
320
227
        strings.append('')
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)
396
276
 
397
277
  yyy.hooks.install_named_hook("xxx", ...)
398
278
 
399
 
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
 
279
See `Using hooks`_ in the User Guide for examples.
 
280
 
 
281
.. _Using hooks: ../user-guide/index.html#using-hooks
400
282
 
401
283
The class that contains each hook is given before the hooks it supplies. For
402
284
instance, BranchHooks as the class is the hooks class for
423
305
        hooks = known_hooks_key_to_object(hook_key)
424
306
        segments.append(hooks.docs())
425
307
    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))