/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-06-10 16:40:42 UTC
  • mfrom: (6653.6.7 rename-controldir)
  • mto: This revision was merged to the branch mainline in revision 6690.
  • Revision ID: jelmer@jelmer.uk-20170610164042-zrxqgy2htyduvke2
Merge rename-controldir branch.

Show diffs side-by-side

added added

removed removed

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