/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
 
    errors,
23
 
    registry,
24
 
    )
25
 
from .lazy_import import lazy_import
 
19
from bzrlib import registry
 
20
from bzrlib.lazy_import import lazy_import
26
21
lazy_import(globals(), """
27
22
import textwrap
28
23
 
29
 
from breezy import (
30
 
    _format_version_tuple,
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 UnknownHook(errors.BzrError):
38
 
 
39
 
    _fmt = "The %(type)s hook '%(hook)s' is unknown in this version of breezy."
40
 
 
41
 
    def __init__(self, hook_type, hook_name):
42
 
        errors.BzrError.__init__(self)
43
 
        self.type = hook_type
44
 
        self.hook = hook_name
45
 
 
46
 
 
47
 
class KnownHooksRegistry(registry.Registry):
48
 
    # known_hooks registry contains
49
 
    # tuple of (module, member name) which is the hook point
50
 
    # module where the specific hooks are defined
51
 
    # callable to get the empty specific Hooks for that attribute
52
 
 
53
 
    def register_lazy_hook(self, hook_module_name, hook_member_name,
54
 
            hook_factory_member_name):
55
 
        self.register_lazy((hook_module_name, hook_member_name),
56
 
            hook_module_name, hook_factory_member_name)
57
 
 
58
 
    def iter_parent_objects(self):
59
 
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
60
 
        hook, where 'parent_object' is the object that holds the hook
61
 
        instance.
62
 
 
63
 
        This is useful for resetting/restoring all the hooks to a known state,
64
 
        as is done in breezy.tests.TestCase._clear_hooks.
65
 
        """
66
 
        for key in self.keys():
67
 
            yield key, self.key_to_parent_and_attribute(key)
68
 
 
69
 
    def key_to_parent_and_attribute(self, key):
70
 
        """Convert a known_hooks key to a (parent_obj, attr) pair.
71
 
 
72
 
        :param key: A tuple (module_name, member_name) as found in the keys of
73
 
            the known_hooks registry.
74
 
        :return: The parent_object of the hook and the name of the attribute on
75
 
            that parent object where the hook is kept.
76
 
        """
77
 
        parent_mod, parent_member, attr = pyutils.calc_parent_name(*key)
78
 
        return pyutils.get_named_object(parent_mod, parent_member), attr
79
 
 
80
 
 
81
 
_builtin_known_hooks = (
82
 
    ('breezy.branch', 'Branch.hooks', 'BranchHooks'),
83
 
    ('breezy.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
84
 
    ('breezy.commands', 'Command.hooks', 'CommandHooks'),
85
 
    ('breezy.config', 'ConfigHooks', '_ConfigHooks'),
86
 
    ('breezy.info', 'hooks', 'InfoHooks'),
87
 
    ('breezy.lock', 'Lock.hooks', 'LockHooks'),
88
 
    ('breezy.merge', 'Merger.hooks', 'MergeHooks'),
89
 
    ('breezy.msgeditor', 'hooks', 'MessageEditorHooks'),
90
 
    ('breezy.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
91
 
    ('breezy.bzr.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
92
 
    ('breezy.bzr.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
93
 
    ('breezy.status', 'hooks', 'StatusHooks'),
94
 
    ('breezy.transport', 'Transport.hooks', 'TransportHooks'),
95
 
    ('breezy.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
96
 
        'RioVersionInfoBuilderHooks'),
97
 
    ('breezy.merge_directive', 'BaseMergeDirective.hooks',
98
 
        'MergeDirectiveHooks'),
99
 
    )
100
 
 
101
 
known_hooks = KnownHooksRegistry()
102
 
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
103
 
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
104
 
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
105
 
 
106
 
 
107
 
def known_hooks_key_to_object(key):
108
 
    """Convert a known_hooks key to a object.
109
 
 
110
 
    :param key: A tuple (module_name, member_name) as found in the keys of
111
 
        the known_hooks registry.
112
 
    :return: The object this specifies.
113
 
    """
114
 
    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
115
90
 
116
91
 
117
92
class Hooks(dict):
121
96
    FOO hook is triggered.
122
97
    """
123
98
 
124
 
    def __init__(self, module=None, member_name=None):
125
 
        """Create a new hooks dictionary.
126
 
 
127
 
        :param module: The module from which this hooks dictionary should be loaded
128
 
            (used for lazy hooks)
129
 
        :param member_name: Name under which this hooks dictionary should be loaded.
130
 
            (used for lazy hooks)
131
 
        """
 
99
    def __init__(self):
132
100
        dict.__init__(self)
133
101
        self._callable_names = {}
134
 
        self._lazy_callable_names = {}
135
 
        self._module = module
136
 
        self._member_name = member_name
137
 
 
138
 
    def add_hook(self, name, doc, introduced, deprecated=None):
139
 
        """Add a hook point to this dictionary.
140
 
 
141
 
        :param name: The name of the hook, for clients to use when registering.
142
 
        :param doc: The docs for the hook.
143
 
        :param introduced: When the hook was introduced (e.g. (0, 15)).
144
 
        :param deprecated: When the hook was deprecated, None for
145
 
            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.
146
109
        """
147
 
        if name in self:
148
 
            raise errors.DuplicateKey(name)
149
 
        if self._module:
150
 
            callbacks = _lazy_hooks.setdefault(
151
 
                (self._module, self._member_name, name), [])
152
 
        else:
153
 
            callbacks = None
154
 
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
155
 
                              deprecated=deprecated, callbacks=callbacks)
156
 
        self[name] = hookpoint
 
110
        if hook.name in self:
 
111
            raise errors.DuplicateKey(hook.name)
 
112
        self[hook.name] = hook
157
113
 
158
114
    def docs(self):
159
115
        """Generate the documentation for this Hooks instance.
189
145
        the code names are rarely meaningful for end users and this is not
190
146
        intended for debugging.
191
147
        """
192
 
        name = self._callable_names.get(a_callable, None)
193
 
        if name is None and a_callable is not None:
194
 
            name = self._lazy_callable_names.get((a_callable.__module__,
195
 
                                                  a_callable.__name__),
196
 
                                                 None)
197
 
        if name is None:
198
 
            return 'No hook name'
199
 
        return name
200
 
 
201
 
 
202
 
    def install_named_hook_lazy(self, hook_name, callable_module,
203
 
        callable_member, name):
204
 
        """Install a_callable in to the hook hook_name lazily, and label it.
205
 
 
206
 
        :param hook_name: A hook name. See the __init__ method for the complete
207
 
            list of hooks.
208
 
        :param callable_module: Name of the module in which the callable is
209
 
            present.
210
 
        :param callable_member: Member name of the callable.
211
 
        :param name: A name to associate the callable with, to show users what
212
 
            is running.
213
 
        """
214
 
        try:
215
 
            hook = self[hook_name]
216
 
        except KeyError:
217
 
            raise UnknownHook(self.__class__.__name__, hook_name)
218
 
        try:
219
 
            hook_lazy = getattr(hook, "hook_lazy")
220
 
        except AttributeError:
221
 
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
222
 
                self)
223
 
        else:
224
 
            hook_lazy(callable_module, callable_member, name)
225
 
        if name is not None:
226
 
            self.name_hook_lazy(callable_module, callable_member, name)
 
148
        return self._callable_names.get(a_callable, "No hook name")
227
149
 
228
150
    def install_named_hook(self, hook_name, a_callable, name):
229
151
        """Install a_callable in to the hook hook_name, and label it name.
230
152
 
231
 
        :param hook_name: A hook name. See the __init__ method for the complete
232
 
            list of hooks.
 
153
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
154
            for the complete list of hooks.
233
155
        :param a_callable: The callable to be invoked when the hook triggers.
234
156
            The exact signature will depend on the hook - see the __init__
235
 
            method for details on each hook.
 
157
            method of BranchHooks for details on each hook.
236
158
        :param name: A name to associate a_callable with, to show users what is
237
159
            running.
238
160
        """
239
161
        try:
240
162
            hook = self[hook_name]
241
163
        except KeyError:
242
 
            raise UnknownHook(self.__class__.__name__, hook_name)
 
164
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
243
165
        try:
244
166
            # list hooks, old-style, not yet deprecated but less useful.
245
167
            hook.append(a_callable)
248
170
        if name is not None:
249
171
            self.name_hook(a_callable, name)
250
172
 
251
 
    def uninstall_named_hook(self, hook_name, label):
252
 
        """Uninstall named hooks.
253
 
 
254
 
        :param hook_name: Hook point name
255
 
        :param label: Label of the callable to uninstall
256
 
        """
257
 
        try:
258
 
            hook = self[hook_name]
259
 
        except KeyError:
260
 
            raise UnknownHook(self.__class__.__name__, hook_name)
261
 
        try:
262
 
            uninstall = getattr(hook, "uninstall")
263
 
        except AttributeError:
264
 
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
265
 
        else:
266
 
            uninstall(label)
267
 
 
268
173
    def name_hook(self, a_callable, name):
269
174
        """Associate name with a_callable to show users what is running."""
270
175
        self._callable_names[a_callable] = name
271
176
 
272
 
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
273
 
        self._lazy_callable_names[(callable_module, callable_member)]= \
274
 
            callable_name
275
 
 
276
177
 
277
178
class HookPoint(object):
278
179
    """A single hook that clients can register to be called back when it fires.
279
180
 
280
181
    :ivar name: The name of the hook.
281
 
    :ivar doc: The docs for using the hook.
282
182
    :ivar introduced: A version tuple specifying what version the hook was
283
183
        introduced in. None indicates an unknown version.
284
184
    :ivar deprecated: A version tuple specifying what version the hook was
285
185
        deprecated or superseded in. None indicates that the hook is not
286
186
        superseded or deprecated. If the hook is superseded then the doc
287
187
        should describe the recommended replacement hook to register for.
 
188
    :ivar doc: The docs for using the hook.
288
189
    """
289
190
 
290
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
191
    def __init__(self, name, doc, introduced, deprecated):
291
192
        """Create a HookPoint.
292
193
 
293
194
        :param name: The name of the hook, for clients to use when registering.
300
201
        self.__doc__ = doc
301
202
        self.introduced = introduced
302
203
        self.deprecated = deprecated
303
 
        if callbacks is None:
304
 
            self._callbacks = []
305
 
        else:
306
 
            self._callbacks = callbacks
 
204
        self._callbacks = []
 
205
        self._callback_names = {}
307
206
 
308
207
    def docs(self):
309
208
        """Generate the documentation for this HookPoint.
318
217
            introduced_string = _format_version_tuple(self.introduced)
319
218
        else:
320
219
            introduced_string = 'unknown'
321
 
        strings.append(gettext('Introduced in: %s') % introduced_string)
 
220
        strings.append('Introduced in: %s' % introduced_string)
322
221
        if self.deprecated:
323
222
            deprecated_string = _format_version_tuple(self.deprecated)
324
 
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
 
223
            strings.append('Deprecated in: %s' % deprecated_string)
325
224
        strings.append('')
326
225
        strings.extend(textwrap.wrap(self.__doc__,
327
226
            break_long_words=False))
329
228
        return '\n'.join(strings)
330
229
 
331
230
    def __eq__(self, other):
332
 
        return (isinstance(other, type(self)) and other.__dict__ == self.__dict__)
333
 
 
334
 
    def hook_lazy(self, callback_module, callback_member, callback_label):
335
 
        """Lazily register a callback to be called when this HookPoint fires.
336
 
 
337
 
        :param callback_module: Module of the callable to use when this
338
 
            HookPoint fires.
339
 
        :param callback_member: Member name of the callback.
340
 
        :param callback_label: A label to show in the UI while this callback is
341
 
            processing.
342
 
        """
343
 
        obj_getter = registry._LazyObjectGetter(callback_module,
344
 
            callback_member)
345
 
        self._callbacks.append((obj_getter, callback_label))
 
231
        return (type(other) == type(self) and 
 
232
            other.__dict__ == self.__dict__)
346
233
 
347
234
    def hook(self, callback, callback_label):
348
235
        """Register a callback to be called when this HookPoint fires.
351
238
        :param callback_label: A label to show in the UI while this callback is
352
239
            processing.
353
240
        """
354
 
        obj_getter = registry._ObjectGetter(callback)
355
 
        self._callbacks.append((obj_getter, callback_label))
356
 
 
357
 
    def uninstall(self, label):
358
 
        """Uninstall the callback with the specified label.
359
 
 
360
 
        :param label: Label of the entry to uninstall
361
 
        """
362
 
        entries_to_remove = []
363
 
        for entry in self._callbacks:
364
 
            (entry_callback, entry_label) = entry
365
 
            if entry_label == label:
366
 
                entries_to_remove.append(entry)
367
 
        if entries_to_remove == []:
368
 
            raise KeyError("No entry with label %r" % label)
369
 
        for entry in entries_to_remove:
370
 
            self._callbacks.remove(entry)
 
241
        self._callbacks.append(callback)
 
242
        if callback_label is not None:
 
243
            self._callback_names[callback] = callback_label
371
244
 
372
245
    def __iter__(self):
373
 
        return (callback.get_obj() for callback, name in self._callbacks)
 
246
        return iter(self._callbacks)
374
247
 
375
248
    def __len__(self):
376
249
        return len(self._callbacks)
380
253
        strings.append("<%s(" % type(self).__name__)
381
254
        strings.append(self.name)
382
255
        strings.append("), callbacks=[")
383
 
        callbacks = self._callbacks
384
 
        for (callback, callback_name) in callbacks:
385
 
            strings.append(repr(callback.get_obj()))
 
256
        for callback in self._callbacks:
 
257
            strings.append(repr(callback))
386
258
            strings.append("(")
387
 
            strings.append(callback_name)
 
259
            strings.append(self._callback_names[callback])
388
260
            strings.append("),")
389
 
        if len(callbacks) == 1:
 
261
        if len(self._callbacks) == 1:
390
262
            strings[-1] = ")"
391
263
        strings.append("]>")
392
264
        return ''.join(strings)
404
276
 
405
277
  yyy.hooks.install_named_hook("xxx", ...)
406
278
 
407
 
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
408
282
 
409
283
The class that contains each hook is given before the hooks it supplies. For
410
284
instance, BranchHooks as the class is the hooks class for
411
 
`breezy.branch.Branch.hooks`.
 
285
`bzrlib.branch.Branch.hooks`.
412
286
 
413
287
Each description also indicates whether the hook runs on the client (the
414
288
machine where bzr was invoked) or the server (the machine addressed by
431
305
        hooks = known_hooks_key_to_object(hook_key)
432
306
        segments.append(hooks.docs())
433
307
    return '\n'.join(segments)
434
 
 
435
 
 
436
 
# Lazily registered hooks. Maps (module, name, hook_name) tuples
437
 
# to lists of tuples with objectgetters and names
438
 
_lazy_hooks = {}
439
 
 
440
 
 
441
 
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
442
 
    a_callable, name):
443
 
    """Install a callable in to a hook lazily, and label it name.
444
 
 
445
 
    :param hookpoints_module: Module name of the hook points.
446
 
    :param hookpoints_name: Name of the hook points.
447
 
    :param hook_name: A hook name.
448
 
    :param callable: a callable to call for the hook.
449
 
    :param name: A name to associate a_callable with, to show users what is
450
 
        running.
451
 
    """
452
 
    key = (hookpoints_module, hookpoints_name, hook_name)
453
 
    obj_getter = registry._ObjectGetter(a_callable)
454
 
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))