/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: Canonical.com Patch Queue Manager
  • Date: 2010-04-06 06:59:03 UTC
  • mfrom: (5051.5.1 subunit)
  • Revision ID: pqm@pqm.ubuntu.com-20100406065903-y9dxgwmog1pmw7dz
Use subunit when running tests in PQM.

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
 
21
from bzrlib.symbol_versioning import deprecated_method
26
22
lazy_import(globals(), """
27
23
import textwrap
28
24
 
29
 
from breezy import (
30
 
    _format_version_tuple,
31
 
    pyutils,
32
 
    )
33
 
from breezy.i18n import gettext
 
25
from bzrlib import (
 
26
        _format_version_tuple,
 
27
        errors,
 
28
        )
 
29
from bzrlib.help_topics import help_as_plain_text
34
30
""")
35
31
 
36
32
 
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)
 
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.merge', 'Merger.hooks'), 'bzrlib.merge',
 
49
    'MergeHooks')
 
50
known_hooks.register_lazy(('bzrlib.msgeditor', 'hooks'), 'bzrlib.msgeditor',
 
51
    'MessageEditorHooks')
 
52
known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),
 
53
    'bzrlib.mutabletree', 'MutableTreeHooks')
 
54
known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),
 
55
    'bzrlib.smart.client', 'SmartClientHooks')
 
56
known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),
 
57
    'bzrlib.smart.server', 'SmartServerHooks')
 
58
known_hooks.register_lazy(
 
59
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks'),
 
60
    'bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilderHooks')
 
61
known_hooks.register_lazy(
 
62
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks'),
 
63
    'bzrlib.merge_directive', 'MergeDirectiveHooks')
 
64
 
 
65
 
 
66
def known_hooks_key_to_object((module_name, member_name)):
 
67
    """Convert a known_hooks key to a object.
 
68
 
 
69
    :param key: A tuple (module_name, member_name) as found in the keys of
 
70
        the known_hooks registry.
 
71
    :return: The object this specifies.
 
72
    """
 
73
    return registry._LazyObjectGetter(module_name, member_name).get_obj()
 
74
 
 
75
 
 
76
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
 
77
    """Convert a known_hooks key to a object.
 
78
 
 
79
    :param key: A tuple (module_name, member_name) as found in the keys of
 
80
        the known_hooks registry.
 
81
    :return: The object this specifies.
 
82
    """
 
83
    member_list = member_name.rsplit('.', 1)
 
84
    if len(member_list) == 2:
 
85
        parent_name, attribute = member_list
 
86
    else:
 
87
        parent_name = None
 
88
        attribute = member_name
 
89
    parent = known_hooks_key_to_object((module_name, parent_name))
 
90
    return parent, attribute
115
91
 
116
92
 
117
93
class Hooks(dict):
121
97
    FOO hook is triggered.
122
98
    """
123
99
 
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
 
        """
 
100
    def __init__(self):
132
101
        dict.__init__(self)
133
102
        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.
 
103
 
 
104
    def create_hook(self, hook):
 
105
        """Create a hook which can have callbacks registered for it.
 
106
 
 
107
        :param hook: The hook to create. An object meeting the protocol of
 
108
            bzrlib.hooks.HookPoint. It's name is used as the key for future
 
109
            lookups.
146
110
        """
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
 
111
        if hook.name in self:
 
112
            raise errors.DuplicateKey(hook.name)
 
113
        self[hook.name] = hook
157
114
 
158
115
    def docs(self):
159
116
        """Generate the documentation for this Hooks instance.
164
121
        hook_docs = []
165
122
        name = self.__class__.__name__
166
123
        hook_docs.append(name)
167
 
        hook_docs.append("-" * len(name))
 
124
        hook_docs.append("-"*len(name))
168
125
        hook_docs.append("")
169
126
        for hook_name in hook_names:
170
127
            hook = self[hook_name]
177
134
                strings.append("~" * len(hook_name))
178
135
                strings.append("")
179
136
                strings.append("An old-style hook. For documentation see the __init__ "
180
 
                               "method of '%s'\n" % (name,))
 
137
                    "method of '%s'\n" % (name,))
181
138
                hook_docs.extend(strings)
182
139
        return "\n".join(hook_docs)
183
140
 
189
146
        the code names are rarely meaningful for end users and this is not
190
147
        intended for debugging.
191
148
        """
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
 
    def install_named_hook_lazy(self, hook_name, callable_module,
202
 
                                callable_member, name):
203
 
        """Install a_callable in to the hook hook_name lazily, and label it.
204
 
 
205
 
        :param hook_name: A hook name. See the __init__ method for the complete
206
 
            list of hooks.
207
 
        :param callable_module: Name of the module in which the callable is
208
 
            present.
209
 
        :param callable_member: Member name of the callable.
210
 
        :param name: A name to associate the callable with, to show users what
211
 
            is running.
212
 
        """
213
 
        try:
214
 
            hook = self[hook_name]
215
 
        except KeyError:
216
 
            raise UnknownHook(self.__class__.__name__, hook_name)
217
 
        try:
218
 
            hook_lazy = getattr(hook, "hook_lazy")
219
 
        except AttributeError:
220
 
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
221
 
                                              self)
222
 
        else:
223
 
            hook_lazy(callable_module, callable_member, name)
224
 
        if name is not None:
225
 
            self.name_hook_lazy(callable_module, callable_member, name)
 
149
        return self._callable_names.get(a_callable, "No hook name")
226
150
 
227
151
    def install_named_hook(self, hook_name, a_callable, name):
228
152
        """Install a_callable in to the hook hook_name, and label it name.
229
153
 
230
 
        :param hook_name: A hook name. See the __init__ method for the complete
231
 
            list of hooks.
 
154
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
155
            for the complete list of hooks.
232
156
        :param a_callable: The callable to be invoked when the hook triggers.
233
157
            The exact signature will depend on the hook - see the __init__
234
 
            method for details on each hook.
 
158
            method of BranchHooks for details on each hook.
235
159
        :param name: A name to associate a_callable with, to show users what is
236
160
            running.
237
161
        """
238
162
        try:
239
163
            hook = self[hook_name]
240
164
        except KeyError:
241
 
            raise UnknownHook(self.__class__.__name__, hook_name)
 
165
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
242
166
        try:
243
167
            # list hooks, old-style, not yet deprecated but less useful.
244
168
            hook.append(a_callable)
247
171
        if name is not None:
248
172
            self.name_hook(a_callable, name)
249
173
 
250
 
    def uninstall_named_hook(self, hook_name, label):
251
 
        """Uninstall named hooks.
252
 
 
253
 
        :param hook_name: Hook point name
254
 
        :param label: Label of the callable to uninstall
255
 
        """
256
 
        try:
257
 
            hook = self[hook_name]
258
 
        except KeyError:
259
 
            raise UnknownHook(self.__class__.__name__, hook_name)
260
 
        try:
261
 
            uninstall = getattr(hook, "uninstall")
262
 
        except AttributeError:
263
 
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
264
 
        else:
265
 
            uninstall(label)
266
 
 
267
174
    def name_hook(self, a_callable, name):
268
175
        """Associate name with a_callable to show users what is running."""
269
176
        self._callable_names[a_callable] = name
270
177
 
271
 
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
272
 
        self._lazy_callable_names[(callable_module, callable_member)] = \
273
 
            callable_name
274
 
 
275
178
 
276
179
class HookPoint(object):
277
180
    """A single hook that clients can register to be called back when it fires.
278
181
 
279
182
    :ivar name: The name of the hook.
280
 
    :ivar doc: The docs for using the hook.
281
183
    :ivar introduced: A version tuple specifying what version the hook was
282
184
        introduced in. None indicates an unknown version.
283
185
    :ivar deprecated: A version tuple specifying what version the hook was
284
186
        deprecated or superseded in. None indicates that the hook is not
285
187
        superseded or deprecated. If the hook is superseded then the doc
286
188
        should describe the recommended replacement hook to register for.
 
189
    :ivar doc: The docs for using the hook.
287
190
    """
288
191
 
289
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
192
    def __init__(self, name, doc, introduced, deprecated):
290
193
        """Create a HookPoint.
291
194
 
292
195
        :param name: The name of the hook, for clients to use when registering.
299
202
        self.__doc__ = doc
300
203
        self.introduced = introduced
301
204
        self.deprecated = deprecated
302
 
        if callbacks is None:
303
 
            self._callbacks = []
304
 
        else:
305
 
            self._callbacks = callbacks
 
205
        self._callbacks = []
 
206
        self._callback_names = {}
306
207
 
307
208
    def docs(self):
308
209
        """Generate the documentation for this HookPoint.
311
212
        """
312
213
        strings = []
313
214
        strings.append(self.name)
314
 
        strings.append('~' * len(self.name))
 
215
        strings.append('~'*len(self.name))
315
216
        strings.append('')
316
217
        if self.introduced:
317
218
            introduced_string = _format_version_tuple(self.introduced)
318
219
        else:
319
220
            introduced_string = 'unknown'
320
 
        strings.append(gettext('Introduced in: %s') % introduced_string)
 
221
        strings.append('Introduced in: %s' % introduced_string)
321
222
        if self.deprecated:
322
223
            deprecated_string = _format_version_tuple(self.deprecated)
323
 
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
 
224
            strings.append('Deprecated in: %s' % deprecated_string)
324
225
        strings.append('')
325
226
        strings.extend(textwrap.wrap(self.__doc__,
326
 
                                     break_long_words=False))
 
227
            break_long_words=False))
327
228
        strings.append('')
328
229
        return '\n'.join(strings)
329
230
 
330
231
    def __eq__(self, other):
331
 
        return (isinstance(other, type(self)) and other.__dict__ == self.__dict__)
332
 
 
333
 
    def hook_lazy(self, callback_module, callback_member, callback_label):
334
 
        """Lazily register a callback to be called when this HookPoint fires.
335
 
 
336
 
        :param callback_module: Module of the callable to use when this
337
 
            HookPoint fires.
338
 
        :param callback_member: Member name of the callback.
339
 
        :param callback_label: A label to show in the UI while this callback is
340
 
            processing.
341
 
        """
342
 
        obj_getter = registry._LazyObjectGetter(callback_module,
343
 
                                                callback_member)
344
 
        self._callbacks.append((obj_getter, callback_label))
 
232
        return (type(other) == type(self) and 
 
233
            other.__dict__ == self.__dict__)
345
234
 
346
235
    def hook(self, callback, callback_label):
347
236
        """Register a callback to be called when this HookPoint fires.
350
239
        :param callback_label: A label to show in the UI while this callback is
351
240
            processing.
352
241
        """
353
 
        obj_getter = registry._ObjectGetter(callback)
354
 
        self._callbacks.append((obj_getter, callback_label))
355
 
 
356
 
    def uninstall(self, label):
357
 
        """Uninstall the callback with the specified label.
358
 
 
359
 
        :param label: Label of the entry to uninstall
360
 
        """
361
 
        entries_to_remove = []
362
 
        for entry in self._callbacks:
363
 
            (entry_callback, entry_label) = entry
364
 
            if entry_label == label:
365
 
                entries_to_remove.append(entry)
366
 
        if entries_to_remove == []:
367
 
            raise KeyError("No entry with label %r" % label)
368
 
        for entry in entries_to_remove:
369
 
            self._callbacks.remove(entry)
 
242
        self._callbacks.append(callback)
 
243
        if callback_label is not None:
 
244
            self._callback_names[callback] = callback_label
370
245
 
371
246
    def __iter__(self):
372
 
        return (callback.get_obj() for callback, name in self._callbacks)
 
247
        return iter(self._callbacks)
373
248
 
374
249
    def __len__(self):
375
250
        return len(self._callbacks)
379
254
        strings.append("<%s(" % type(self).__name__)
380
255
        strings.append(self.name)
381
256
        strings.append("), callbacks=[")
382
 
        callbacks = self._callbacks
383
 
        for (callback, callback_name) in callbacks:
384
 
            strings.append(repr(callback.get_obj()))
 
257
        for callback in self._callbacks:
 
258
            strings.append(repr(callback))
385
259
            strings.append("(")
386
 
            strings.append(callback_name)
 
260
            strings.append(self._callback_names[callback])
387
261
            strings.append("),")
388
 
        if len(callbacks) == 1:
 
262
        if len(self._callbacks) == 1:
389
263
            strings[-1] = ")"
390
264
        strings.append("]>")
391
265
        return ''.join(strings)
392
266
 
393
267
 
394
268
_help_prefix = \
395
 
    """
 
269
"""
396
270
Hooks
397
271
=====
398
272
 
403
277
 
404
278
  yyy.hooks.install_named_hook("xxx", ...)
405
279
 
406
 
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
 
280
See `Using hooks`_ in the User Guide for examples.
 
281
 
 
282
.. _Using hooks: ../user-guide/hooks.html
407
283
 
408
284
The class that contains each hook is given before the hooks it supplies. For
409
285
instance, BranchHooks as the class is the hooks class for
410
 
`breezy.branch.Branch.hooks`.
 
286
`bzrlib.branch.Branch.hooks`.
411
287
 
412
288
Each description also indicates whether the hook runs on the client (the
413
289
machine where bzr was invoked) or the server (the machine addressed by
424
300
 
425
301
"""
426
302
 
427
 
 
428
303
def hooks_help_text(topic):
429
304
    segments = [_help_prefix]
430
305
    for hook_key in sorted(known_hooks.keys()):
431
306
        hooks = known_hooks_key_to_object(hook_key)
432
307
        segments.append(hooks.docs())
433
308
    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))