~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Tarmac
  • Author(s): Vincent Ladeuil
  • Date: 2017-01-30 14:42:05 UTC
  • mfrom: (6620.1.1 trunk)
  • Revision ID: tarmac-20170130144205-r8fh2xpmiuxyozpv
Merge  2.7 into trunk including fix for bug #1657238 [r=vila]

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2007, 2008 Canonical Ltd
 
1
# Copyright (C) 2007-2011 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
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 
 
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
16
 
18
17
"""Support for plugin hooking logic."""
 
18
 
 
19
from __future__ import absolute_import
 
20
 
 
21
from bzrlib import (
 
22
    registry,
 
23
    symbol_versioning,
 
24
    )
19
25
from bzrlib.lazy_import import lazy_import
20
 
from bzrlib.symbol_versioning import deprecated_method, one_five
21
26
lazy_import(globals(), """
 
27
import textwrap
 
28
 
22
29
from bzrlib import (
23
 
        errors,
24
 
        )
 
30
    _format_version_tuple,
 
31
    errors,
 
32
    pyutils,
 
33
    )
 
34
from bzrlib.i18n import gettext
25
35
""")
26
36
 
27
37
 
 
38
class KnownHooksRegistry(registry.Registry):
 
39
    # known_hooks registry contains
 
40
    # tuple of (module, member name) which is the hook point
 
41
    # module where the specific hooks are defined
 
42
    # callable to get the empty specific Hooks for that attribute
 
43
 
 
44
    def register_lazy_hook(self, hook_module_name, hook_member_name,
 
45
            hook_factory_member_name):
 
46
        self.register_lazy((hook_module_name, hook_member_name),
 
47
            hook_module_name, hook_factory_member_name)
 
48
 
 
49
    def iter_parent_objects(self):
 
50
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
 
51
        hook, where 'parent_object' is the object that holds the hook
 
52
        instance.
 
53
 
 
54
        This is useful for resetting/restoring all the hooks to a known state,
 
55
        as is done in bzrlib.tests.TestCase._clear_hooks.
 
56
        """
 
57
        for key in self.keys():
 
58
            yield key, self.key_to_parent_and_attribute(key)
 
59
 
 
60
    def key_to_parent_and_attribute(self, (module_name, member_name)):
 
61
        """Convert a known_hooks key to a (parent_obj, attr) pair.
 
62
 
 
63
        :param key: A tuple (module_name, member_name) as found in the keys of
 
64
            the known_hooks registry.
 
65
        :return: The parent_object of the hook and the name of the attribute on
 
66
            that parent object where the hook is kept.
 
67
        """
 
68
        parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
 
69
            member_name)
 
70
        return pyutils.get_named_object(parent_mod, parent_member), attr
 
71
 
 
72
 
 
73
_builtin_known_hooks = (
 
74
    ('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
 
75
    ('bzrlib.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
 
76
    ('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
 
77
    ('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
 
78
    ('bzrlib.info', 'hooks', 'InfoHooks'),
 
79
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
 
80
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
 
81
    ('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
 
82
    ('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
 
83
    ('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
 
84
    ('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
 
85
    ('bzrlib.status', 'hooks', 'StatusHooks'),
 
86
    ('bzrlib.transport', 'Transport.hooks', 'TransportHooks'),
 
87
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
 
88
        'RioVersionInfoBuilderHooks'),
 
89
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
 
90
        'MergeDirectiveHooks'),
 
91
    )
 
92
 
 
93
known_hooks = KnownHooksRegistry()
 
94
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
 
95
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
 
96
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
 
97
 
 
98
 
 
99
def known_hooks_key_to_object((module_name, member_name)):
 
100
    """Convert a known_hooks key to a object.
 
101
 
 
102
    :param key: A tuple (module_name, member_name) as found in the keys of
 
103
        the known_hooks registry.
 
104
    :return: The object this specifies.
 
105
    """
 
106
    return pyutils.get_named_object(module_name, member_name)
 
107
 
 
108
 
28
109
class Hooks(dict):
29
110
    """A dictionary mapping hook name to a list of callables.
30
 
    
 
111
 
31
112
    e.g. ['FOO'] Is the list of items to be called when the
32
113
    FOO hook is triggered.
33
114
    """
34
115
 
35
 
    def __init__(self):
 
116
    def __init__(self, module=None, member_name=None):
 
117
        """Create a new hooks dictionary.
 
118
 
 
119
        :param module: The module from which this hooks dictionary should be loaded
 
120
            (used for lazy hooks)
 
121
        :param member_name: Name under which this hooks dictionary should be loaded.
 
122
            (used for lazy hooks)
 
123
        """
36
124
        dict.__init__(self)
37
125
        self._callable_names = {}
 
126
        self._lazy_callable_names = {}
 
127
        self._module = module
 
128
        self._member_name = member_name
 
129
 
 
130
    def add_hook(self, name, doc, introduced, deprecated=None):
 
131
        """Add a hook point to this dictionary.
 
132
 
 
133
        :param name: The name of the hook, for clients to use when registering.
 
134
        :param doc: The docs for the hook.
 
135
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
136
        :param deprecated: When the hook was deprecated, None for
 
137
            not-deprecated.
 
138
        """
 
139
        if name in self:
 
140
            raise errors.DuplicateKey(name)
 
141
        if self._module:
 
142
            callbacks = _lazy_hooks.setdefault(
 
143
                (self._module, self._member_name, name), [])
 
144
        else:
 
145
            callbacks = None
 
146
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
 
147
                              deprecated=deprecated, callbacks=callbacks)
 
148
        self[name] = hookpoint
 
149
 
 
150
    def docs(self):
 
151
        """Generate the documentation for this Hooks instance.
 
152
 
 
153
        This introspects all the individual hooks and returns their docs as well.
 
154
        """
 
155
        hook_names = sorted(self.keys())
 
156
        hook_docs = []
 
157
        name = self.__class__.__name__
 
158
        hook_docs.append(name)
 
159
        hook_docs.append("-"*len(name))
 
160
        hook_docs.append("")
 
161
        for hook_name in hook_names:
 
162
            hook = self[hook_name]
 
163
            try:
 
164
                hook_docs.append(hook.docs())
 
165
            except AttributeError:
 
166
                # legacy hook
 
167
                strings = []
 
168
                strings.append(hook_name)
 
169
                strings.append("~" * len(hook_name))
 
170
                strings.append("")
 
171
                strings.append("An old-style hook. For documentation see the __init__ "
 
172
                    "method of '%s'\n" % (name,))
 
173
                hook_docs.extend(strings)
 
174
        return "\n".join(hook_docs)
38
175
 
39
176
    def get_hook_name(self, a_callable):
40
177
        """Get the name for a_callable for UI display.
41
178
 
42
179
        If no name has been registered, the string 'No hook name' is returned.
43
180
        We use a fixed string rather than repr or the callables module because
44
 
        the code names are rarely meaningful for end users and this is not 
 
181
        the code names are rarely meaningful for end users and this is not
45
182
        intended for debugging.
46
183
        """
47
 
        return self._callable_names.get(a_callable, "No hook name")
48
 
 
49
 
    @deprecated_method(one_five)
50
 
    def install_hook(self, hook_name, a_callable):
51
 
        """Install a_callable in to the hook hook_name.
52
 
 
53
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
54
 
            for the complete list of hooks.
55
 
        :param a_callable: The callable to be invoked when the hook triggers.
56
 
            The exact signature will depend on the hook - see the __init__ 
57
 
            method of BranchHooks for details on each hook.
 
184
        name = self._callable_names.get(a_callable, None)
 
185
        if name is None and a_callable is not None:
 
186
            name = self._lazy_callable_names.get((a_callable.__module__,
 
187
                                                  a_callable.__name__),
 
188
                                                 None)
 
189
        if name is None:
 
190
            return 'No hook name'
 
191
        return name
 
192
 
 
193
 
 
194
    def install_named_hook_lazy(self, hook_name, callable_module,
 
195
        callable_member, name):
 
196
        """Install a_callable in to the hook hook_name lazily, and label it.
 
197
 
 
198
        :param hook_name: A hook name. See the __init__ method for the complete
 
199
            list of hooks.
 
200
        :param callable_module: Name of the module in which the callable is
 
201
            present.
 
202
        :param callable_member: Member name of the callable.
 
203
        :param name: A name to associate the callable with, to show users what
 
204
            is running.
58
205
        """
59
 
        self.install_named_hook(hook_name, a_callable, None)
 
206
        try:
 
207
            hook = self[hook_name]
 
208
        except KeyError:
 
209
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
210
        try:
 
211
            hook_lazy = getattr(hook, "hook_lazy")
 
212
        except AttributeError:
 
213
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
 
214
                self)
 
215
        else:
 
216
            hook_lazy(callable_module, callable_member, name)
 
217
        if name is not None:
 
218
            self.name_hook_lazy(callable_module, callable_member, name)
60
219
 
61
220
    def install_named_hook(self, hook_name, a_callable, name):
62
221
        """Install a_callable in to the hook hook_name, and label it name.
63
222
 
64
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
65
 
            for the complete list of hooks.
 
223
        :param hook_name: A hook name. See the __init__ method for the complete
 
224
            list of hooks.
66
225
        :param a_callable: The callable to be invoked when the hook triggers.
67
 
            The exact signature will depend on the hook - see the __init__ 
68
 
            method of BranchHooks for details on each hook.
 
226
            The exact signature will depend on the hook - see the __init__
 
227
            method for details on each hook.
69
228
        :param name: A name to associate a_callable with, to show users what is
70
229
            running.
71
230
        """
72
231
        try:
73
 
            self[hook_name].append(a_callable)
 
232
            hook = self[hook_name]
74
233
        except KeyError:
75
234
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
235
        try:
 
236
            # list hooks, old-style, not yet deprecated but less useful.
 
237
            hook.append(a_callable)
 
238
        except AttributeError:
 
239
            hook.hook(a_callable, name)
76
240
        if name is not None:
77
241
            self.name_hook(a_callable, name)
78
242
 
 
243
    def uninstall_named_hook(self, hook_name, label):
 
244
        """Uninstall named hooks.
 
245
 
 
246
        :param hook_name: Hook point name
 
247
        :param label: Label of the callable to uninstall
 
248
        """
 
249
        try:
 
250
            hook = self[hook_name]
 
251
        except KeyError:
 
252
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
253
        try:
 
254
            uninstall = getattr(hook, "uninstall")
 
255
        except AttributeError:
 
256
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
 
257
        else:
 
258
            uninstall(label)
 
259
 
79
260
    def name_hook(self, a_callable, name):
80
261
        """Associate name with a_callable to show users what is running."""
81
262
        self._callable_names[a_callable] = name
 
263
 
 
264
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
 
265
        self._lazy_callable_names[(callable_module, callable_member)]= \
 
266
            callable_name
 
267
 
 
268
 
 
269
class HookPoint(object):
 
270
    """A single hook that clients can register to be called back when it fires.
 
271
 
 
272
    :ivar name: The name of the hook.
 
273
    :ivar doc: The docs for using the hook.
 
274
    :ivar introduced: A version tuple specifying what version the hook was
 
275
        introduced in. None indicates an unknown version.
 
276
    :ivar deprecated: A version tuple specifying what version the hook was
 
277
        deprecated or superseded in. None indicates that the hook is not
 
278
        superseded or deprecated. If the hook is superseded then the doc
 
279
        should describe the recommended replacement hook to register for.
 
280
    """
 
281
 
 
282
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
 
283
        """Create a HookPoint.
 
284
 
 
285
        :param name: The name of the hook, for clients to use when registering.
 
286
        :param doc: The docs for the hook.
 
287
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
288
        :param deprecated: When the hook was deprecated, None for
 
289
            not-deprecated.
 
290
        """
 
291
        self.name = name
 
292
        self.__doc__ = doc
 
293
        self.introduced = introduced
 
294
        self.deprecated = deprecated
 
295
        if callbacks is None:
 
296
            self._callbacks = []
 
297
        else:
 
298
            self._callbacks = callbacks
 
299
 
 
300
    def docs(self):
 
301
        """Generate the documentation for this HookPoint.
 
302
 
 
303
        :return: A string terminated in \n.
 
304
        """
 
305
        strings = []
 
306
        strings.append(self.name)
 
307
        strings.append('~'*len(self.name))
 
308
        strings.append('')
 
309
        if self.introduced:
 
310
            introduced_string = _format_version_tuple(self.introduced)
 
311
        else:
 
312
            introduced_string = 'unknown'
 
313
        strings.append(gettext('Introduced in: %s') % introduced_string)
 
314
        if self.deprecated:
 
315
            deprecated_string = _format_version_tuple(self.deprecated)
 
316
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
 
317
        strings.append('')
 
318
        strings.extend(textwrap.wrap(self.__doc__,
 
319
            break_long_words=False))
 
320
        strings.append('')
 
321
        return '\n'.join(strings)
 
322
 
 
323
    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))
 
338
 
 
339
    def hook(self, callback, callback_label):
 
340
        """Register a callback to be called when this HookPoint fires.
 
341
 
 
342
        :param callback: The callable to use when this HookPoint fires.
 
343
        :param callback_label: A label to show in the UI while this callback is
 
344
            processing.
 
345
        """
 
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)
 
363
 
 
364
    def __iter__(self):
 
365
        return (callback.get_obj() for callback, name in self._callbacks)
 
366
 
 
367
    def __len__(self):
 
368
        return len(self._callbacks)
 
369
 
 
370
    def __repr__(self):
 
371
        strings = []
 
372
        strings.append("<%s(" % type(self).__name__)
 
373
        strings.append(self.name)
 
374
        strings.append("), callbacks=[")
 
375
        callbacks = self._callbacks
 
376
        for (callback, callback_name) in callbacks:
 
377
            strings.append(repr(callback.get_obj()))
 
378
            strings.append("(")
 
379
            strings.append(callback_name)
 
380
            strings.append("),")
 
381
        if len(callbacks) == 1:
 
382
            strings[-1] = ")"
 
383
        strings.append("]>")
 
384
        return ''.join(strings)
 
385
 
 
386
 
 
387
_help_prefix = \
 
388
"""
 
389
Hooks
 
390
=====
 
391
 
 
392
Introduction
 
393
------------
 
394
 
 
395
A hook of type *xxx* of class *yyy* needs to be registered using::
 
396
 
 
397
  yyy.hooks.install_named_hook("xxx", ...)
 
398
 
 
399
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
 
400
 
 
401
The class that contains each hook is given before the hooks it supplies. For
 
402
instance, BranchHooks as the class is the hooks class for
 
403
`bzrlib.branch.Branch.hooks`.
 
404
 
 
405
Each description also indicates whether the hook runs on the client (the
 
406
machine where bzr was invoked) or the server (the machine addressed by
 
407
the branch URL).  These may be, but are not necessarily, the same machine.
 
408
 
 
409
Plugins (including hooks) are run on the server if all of these is true:
 
410
 
 
411
  * The connection is via a smart server (accessed with a URL starting with
 
412
    "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
 
413
    URL when a smart server is available via HTTP).
 
414
 
 
415
  * The hook is either server specific or part of general infrastructure rather
 
416
    than client specific code (such as commit).
 
417
 
 
418
"""
 
419
 
 
420
def hooks_help_text(topic):
 
421
    segments = [_help_prefix]
 
422
    for hook_key in sorted(known_hooks.keys()):
 
423
        hooks = known_hooks_key_to_object(hook_key)
 
424
        segments.append(hooks.docs())
 
425
    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))