/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 breezy/hooks.py

  • Committer: Jelmer Vernooij
  • Date: 2017-05-30 22:09:29 UTC
  • mto: This revision was merged to the branch mainline in revision 6641.
  • Revision ID: jelmer@jelmer.uk-20170530220929-qkha5n0v2fgvftk9
Ignore warning.

Show diffs side-by-side

added added

removed removed

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