/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Robert Collins
  • Date: 2010-05-06 11:08:10 UTC
  • mto: This revision was merged to the branch mainline in revision 5223.
  • Revision ID: robertc@robertcollins.net-20100506110810-h3j07fh5gmw54s25
Cleaner matcher matching revised unlocking protocol.

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
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
 
17
 
17
18
"""Support for plugin hooking logic."""
18
 
 
19
 
from __future__ import absolute_import
20
 
 
21
 
from . import (
22
 
    registry,
23
 
    )
24
 
from .lazy_import import lazy_import
 
19
from bzrlib import registry
 
20
from bzrlib.lazy_import import lazy_import
25
21
lazy_import(globals(), """
26
22
import textwrap
27
23
 
28
 
from breezy import (
29
 
    _format_version_tuple,
30
 
    errors,
31
 
    pyutils,
32
 
    )
33
 
from breezy.i18n import gettext
 
24
from bzrlib import (
 
25
        _format_version_tuple,
 
26
        errors,
 
27
        )
 
28
from bzrlib.help_topics import help_as_plain_text
34
29
""")
35
30
 
36
31
 
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 breezy.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, key):
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(*key)
68
 
        return pyutils.get_named_object(parent_mod, parent_member), attr
69
 
 
70
 
 
71
 
_builtin_known_hooks = (
72
 
    ('breezy.branch', 'Branch.hooks', 'BranchHooks'),
73
 
    ('breezy.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
74
 
    ('breezy.commands', 'Command.hooks', 'CommandHooks'),
75
 
    ('breezy.config', 'ConfigHooks', '_ConfigHooks'),
76
 
    ('breezy.info', 'hooks', 'InfoHooks'),
77
 
    ('breezy.lock', 'Lock.hooks', 'LockHooks'),
78
 
    ('breezy.merge', 'Merger.hooks', 'MergeHooks'),
79
 
    ('breezy.msgeditor', 'hooks', 'MessageEditorHooks'),
80
 
    ('breezy.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
81
 
    ('breezy.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
82
 
    ('breezy.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
83
 
    ('breezy.status', 'hooks', 'StatusHooks'),
84
 
    ('breezy.transport', 'Transport.hooks', 'TransportHooks'),
85
 
    ('breezy.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
86
 
        'RioVersionInfoBuilderHooks'),
87
 
    ('breezy.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
95
 
 
96
 
 
97
 
def known_hooks_key_to_object(key):
98
 
    """Convert a known_hooks key to a object.
99
 
 
100
 
    :param key: A tuple (module_name, member_name) as found in the keys of
101
 
        the known_hooks registry.
102
 
    :return: The object this specifies.
103
 
    """
104
 
    return pyutils.get_named_object(*key)
 
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')
 
63
 
 
64
 
 
65
def known_hooks_key_to_object((module_name, member_name)):
 
66
    """Convert a known_hooks key to a object.
 
67
 
 
68
    :param key: A tuple (module_name, member_name) as found in the keys of
 
69
        the known_hooks registry.
 
70
    :return: The object this specifies.
 
71
    """
 
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
105
90
 
106
91
 
107
92
class Hooks(dict):
111
96
    FOO hook is triggered.
112
97
    """
113
98
 
114
 
    def __init__(self, module=None, member_name=None):
115
 
        """Create a new hooks dictionary.
116
 
 
117
 
        :param module: The module from which this hooks dictionary should be loaded
118
 
            (used for lazy hooks)
119
 
        :param member_name: Name under which this hooks dictionary should be loaded.
120
 
            (used for lazy hooks)
121
 
        """
 
99
    def __init__(self):
122
100
        dict.__init__(self)
123
101
        self._callable_names = {}
124
 
        self._lazy_callable_names = {}
125
 
        self._module = module
126
 
        self._member_name = member_name
127
 
 
128
 
    def add_hook(self, name, doc, introduced, deprecated=None):
129
 
        """Add a hook point to this dictionary.
130
 
 
131
 
        :param name: The name of the hook, for clients to use when registering.
132
 
        :param doc: The docs for the hook.
133
 
        :param introduced: When the hook was introduced (e.g. (0, 15)).
134
 
        :param deprecated: When the hook was deprecated, None for
135
 
            not-deprecated.
 
102
 
 
103
    def create_hook(self, hook):
 
104
        """Create a hook which can have callbacks registered for it.
 
105
 
 
106
        :param hook: The hook to create. An object meeting the protocol of
 
107
            bzrlib.hooks.HookPoint. It's name is used as the key for future
 
108
            lookups.
136
109
        """
137
 
        if name in self:
138
 
            raise errors.DuplicateKey(name)
139
 
        if self._module:
140
 
            callbacks = _lazy_hooks.setdefault(
141
 
                (self._module, self._member_name, name), [])
142
 
        else:
143
 
            callbacks = None
144
 
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
145
 
                              deprecated=deprecated, callbacks=callbacks)
146
 
        self[name] = hookpoint
 
110
        if hook.name in self:
 
111
            raise errors.DuplicateKey(hook.name)
 
112
        self[hook.name] = hook
147
113
 
148
114
    def docs(self):
149
115
        """Generate the documentation for this Hooks instance.
179
145
        the code names are rarely meaningful for end users and this is not
180
146
        intended for debugging.
181
147
        """
182
 
        name = self._callable_names.get(a_callable, None)
183
 
        if name is None and a_callable is not None:
184
 
            name = self._lazy_callable_names.get((a_callable.__module__,
185
 
                                                  a_callable.__name__),
186
 
                                                 None)
187
 
        if name is None:
188
 
            return 'No hook name'
189
 
        return name
190
 
 
191
 
 
192
 
    def install_named_hook_lazy(self, hook_name, callable_module,
193
 
        callable_member, name):
194
 
        """Install a_callable in to the hook hook_name lazily, and label it.
195
 
 
196
 
        :param hook_name: A hook name. See the __init__ method for the complete
197
 
            list of hooks.
198
 
        :param callable_module: Name of the module in which the callable is
199
 
            present.
200
 
        :param callable_member: Member name of the callable.
201
 
        :param name: A name to associate the callable with, to show users what
202
 
            is running.
203
 
        """
204
 
        try:
205
 
            hook = self[hook_name]
206
 
        except KeyError:
207
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
208
 
        try:
209
 
            hook_lazy = getattr(hook, "hook_lazy")
210
 
        except AttributeError:
211
 
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
212
 
                self)
213
 
        else:
214
 
            hook_lazy(callable_module, callable_member, name)
215
 
        if name is not None:
216
 
            self.name_hook_lazy(callable_module, callable_member, name)
 
148
        return self._callable_names.get(a_callable, "No hook name")
217
149
 
218
150
    def install_named_hook(self, hook_name, a_callable, name):
219
151
        """Install a_callable in to the hook hook_name, and label it name.
220
152
 
221
 
        :param hook_name: A hook name. See the __init__ method for the complete
222
 
            list of hooks.
 
153
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
154
            for the complete list of hooks.
223
155
        :param a_callable: The callable to be invoked when the hook triggers.
224
156
            The exact signature will depend on the hook - see the __init__
225
 
            method for details on each hook.
 
157
            method of BranchHooks for details on each hook.
226
158
        :param name: A name to associate a_callable with, to show users what is
227
159
            running.
228
160
        """
238
170
        if name is not None:
239
171
            self.name_hook(a_callable, name)
240
172
 
241
 
    def uninstall_named_hook(self, hook_name, label):
242
 
        """Uninstall named hooks.
243
 
 
244
 
        :param hook_name: Hook point name
245
 
        :param label: Label of the callable to uninstall
246
 
        """
247
 
        try:
248
 
            hook = self[hook_name]
249
 
        except KeyError:
250
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
251
 
        try:
252
 
            uninstall = getattr(hook, "uninstall")
253
 
        except AttributeError:
254
 
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
255
 
        else:
256
 
            uninstall(label)
257
 
 
258
173
    def name_hook(self, a_callable, name):
259
174
        """Associate name with a_callable to show users what is running."""
260
175
        self._callable_names[a_callable] = name
261
176
 
262
 
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
263
 
        self._lazy_callable_names[(callable_module, callable_member)]= \
264
 
            callable_name
265
 
 
266
177
 
267
178
class HookPoint(object):
268
179
    """A single hook that clients can register to be called back when it fires.
269
180
 
270
181
    :ivar name: The name of the hook.
271
 
    :ivar doc: The docs for using the hook.
272
182
    :ivar introduced: A version tuple specifying what version the hook was
273
183
        introduced in. None indicates an unknown version.
274
184
    :ivar deprecated: A version tuple specifying what version the hook was
275
185
        deprecated or superseded in. None indicates that the hook is not
276
186
        superseded or deprecated. If the hook is superseded then the doc
277
187
        should describe the recommended replacement hook to register for.
 
188
    :ivar doc: The docs for using the hook.
278
189
    """
279
190
 
280
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
191
    def __init__(self, name, doc, introduced, deprecated):
281
192
        """Create a HookPoint.
282
193
 
283
194
        :param name: The name of the hook, for clients to use when registering.
290
201
        self.__doc__ = doc
291
202
        self.introduced = introduced
292
203
        self.deprecated = deprecated
293
 
        if callbacks is None:
294
 
            self._callbacks = []
295
 
        else:
296
 
            self._callbacks = callbacks
 
204
        self._callbacks = []
 
205
        self._callback_names = {}
297
206
 
298
207
    def docs(self):
299
208
        """Generate the documentation for this HookPoint.
308
217
            introduced_string = _format_version_tuple(self.introduced)
309
218
        else:
310
219
            introduced_string = 'unknown'
311
 
        strings.append(gettext('Introduced in: %s') % introduced_string)
 
220
        strings.append('Introduced in: %s' % introduced_string)
312
221
        if self.deprecated:
313
222
            deprecated_string = _format_version_tuple(self.deprecated)
314
 
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
 
223
            strings.append('Deprecated in: %s' % deprecated_string)
315
224
        strings.append('')
316
225
        strings.extend(textwrap.wrap(self.__doc__,
317
226
            break_long_words=False))
319
228
        return '\n'.join(strings)
320
229
 
321
230
    def __eq__(self, other):
322
 
        return (isinstance(other, type(self)) and other.__dict__ == self.__dict__)
323
 
 
324
 
    def hook_lazy(self, callback_module, callback_member, callback_label):
325
 
        """Lazily register a callback to be called when this HookPoint fires.
326
 
 
327
 
        :param callback_module: Module of the callable to use when this
328
 
            HookPoint fires.
329
 
        :param callback_member: Member name of the callback.
330
 
        :param callback_label: A label to show in the UI while this callback is
331
 
            processing.
332
 
        """
333
 
        obj_getter = registry._LazyObjectGetter(callback_module,
334
 
            callback_member)
335
 
        self._callbacks.append((obj_getter, callback_label))
 
231
        return (type(other) == type(self) and 
 
232
            other.__dict__ == self.__dict__)
336
233
 
337
234
    def hook(self, callback, callback_label):
338
235
        """Register a callback to be called when this HookPoint fires.
341
238
        :param callback_label: A label to show in the UI while this callback is
342
239
            processing.
343
240
        """
344
 
        obj_getter = registry._ObjectGetter(callback)
345
 
        self._callbacks.append((obj_getter, callback_label))
346
 
 
347
 
    def uninstall(self, label):
348
 
        """Uninstall the callback with the specified label.
349
 
 
350
 
        :param label: Label of the entry to uninstall
351
 
        """
352
 
        entries_to_remove = []
353
 
        for entry in self._callbacks:
354
 
            (entry_callback, entry_label) = entry
355
 
            if entry_label == label:
356
 
                entries_to_remove.append(entry)
357
 
        if entries_to_remove == []:
358
 
            raise KeyError("No entry with label %r" % label)
359
 
        for entry in entries_to_remove:
360
 
            self._callbacks.remove(entry)
 
241
        self._callbacks.append(callback)
 
242
        if callback_label is not None:
 
243
            self._callback_names[callback] = callback_label
361
244
 
362
245
    def __iter__(self):
363
 
        return (callback.get_obj() for callback, name in self._callbacks)
 
246
        return iter(self._callbacks)
364
247
 
365
248
    def __len__(self):
366
249
        return len(self._callbacks)
370
253
        strings.append("<%s(" % type(self).__name__)
371
254
        strings.append(self.name)
372
255
        strings.append("), callbacks=[")
373
 
        callbacks = self._callbacks
374
 
        for (callback, callback_name) in callbacks:
375
 
            strings.append(repr(callback.get_obj()))
 
256
        for callback in self._callbacks:
 
257
            strings.append(repr(callback))
376
258
            strings.append("(")
377
 
            strings.append(callback_name)
 
259
            strings.append(self._callback_names[callback])
378
260
            strings.append("),")
379
 
        if len(callbacks) == 1:
 
261
        if len(self._callbacks) == 1:
380
262
            strings[-1] = ")"
381
263
        strings.append("]>")
382
264
        return ''.join(strings)
394
276
 
395
277
  yyy.hooks.install_named_hook("xxx", ...)
396
278
 
397
 
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/hooks.html
398
282
 
399
283
The class that contains each hook is given before the hooks it supplies. For
400
284
instance, BranchHooks as the class is the hooks class for
401
 
`breezy.branch.Branch.hooks`.
 
285
`bzrlib.branch.Branch.hooks`.
402
286
 
403
287
Each description also indicates whether the hook runs on the client (the
404
288
machine where bzr was invoked) or the server (the machine addressed by
421
305
        hooks = known_hooks_key_to_object(hook_key)
422
306
        segments.append(hooks.docs())
423
307
    return '\n'.join(segments)
424
 
 
425
 
 
426
 
# Lazily registered hooks. Maps (module, name, hook_name) tuples
427
 
# to lists of tuples with objectgetters and names
428
 
_lazy_hooks = {}
429
 
 
430
 
 
431
 
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
432
 
    a_callable, name):
433
 
    """Install a callable in to a hook lazily, and label it name.
434
 
 
435
 
    :param hookpoints_module: Module name of the hook points.
436
 
    :param hookpoints_name: Name of the hook points.
437
 
    :param hook_name: A hook name.
438
 
    :param callable: a callable to call for the hook.
439
 
    :param name: A name to associate a_callable with, to show users what is
440
 
        running.
441
 
    """
442
 
    key = (hookpoints_module, hookpoints_name, hook_name)
443
 
    obj_getter = registry._ObjectGetter(a_callable)
444
 
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))