/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: Vincent Ladeuil
  • Date: 2010-07-07 11:21:19 UTC
  • mto: (5193.7.1 unify-confs)
  • mto: This revision was merged to the branch mainline in revision 5349.
  • Revision ID: v.ladeuil+lp@free.fr-20100707112119-jwyh312df41w6l0o
Revert previous change as I can't reproduce the related problem anymore.

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