/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: Martin
  • Date: 2018-11-16 16:38:22 UTC
  • mto: This revision was merged to the branch mainline in revision 7172.
  • Revision ID: gzlist@googlemail.com-20181116163822-yg1h1cdng6w7w9kn
Make --profile-imports work on Python 3

Also tweak heading to line up correctly.

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
    errors,
 
23
    registry,
 
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
    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 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)
90
115
 
91
116
 
92
117
class Hooks(dict):
96
121
    FOO hook is triggered.
97
122
    """
98
123
 
99
 
    def __init__(self):
 
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
132
        dict.__init__(self)
101
133
        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.
 
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.
109
146
        """
110
 
        if hook.name in self:
111
 
            raise errors.DuplicateKey(hook.name)
112
 
        self[hook.name] = hook
 
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
113
157
 
114
158
    def docs(self):
115
159
        """Generate the documentation for this Hooks instance.
145
189
        the code names are rarely meaningful for end users and this is not
146
190
        intended for debugging.
147
191
        """
148
 
        return self._callable_names.get(a_callable, "No hook name")
 
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
 
 
202
    def install_named_hook_lazy(self, hook_name, callable_module,
 
203
        callable_member, name):
 
204
        """Install a_callable in to the hook hook_name lazily, and label it.
 
205
 
 
206
        :param hook_name: A hook name. See the __init__ method for the complete
 
207
            list of hooks.
 
208
        :param callable_module: Name of the module in which the callable is
 
209
            present.
 
210
        :param callable_member: Member name of the callable.
 
211
        :param name: A name to associate the callable with, to show users what
 
212
            is running.
 
213
        """
 
214
        try:
 
215
            hook = self[hook_name]
 
216
        except KeyError:
 
217
            raise UnknownHook(self.__class__.__name__, hook_name)
 
218
        try:
 
219
            hook_lazy = getattr(hook, "hook_lazy")
 
220
        except AttributeError:
 
221
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
 
222
                self)
 
223
        else:
 
224
            hook_lazy(callable_module, callable_member, name)
 
225
        if name is not None:
 
226
            self.name_hook_lazy(callable_module, callable_member, name)
149
227
 
150
228
    def install_named_hook(self, hook_name, a_callable, name):
151
229
        """Install a_callable in to the hook hook_name, and label it name.
152
230
 
153
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
154
 
            for the complete list of hooks.
 
231
        :param hook_name: A hook name. See the __init__ method for the complete
 
232
            list of hooks.
155
233
        :param a_callable: The callable to be invoked when the hook triggers.
156
234
            The exact signature will depend on the hook - see the __init__
157
 
            method of BranchHooks for details on each hook.
 
235
            method for details on each hook.
158
236
        :param name: A name to associate a_callable with, to show users what is
159
237
            running.
160
238
        """
161
239
        try:
162
240
            hook = self[hook_name]
163
241
        except KeyError:
164
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
242
            raise UnknownHook(self.__class__.__name__, hook_name)
165
243
        try:
166
244
            # list hooks, old-style, not yet deprecated but less useful.
167
245
            hook.append(a_callable)
170
248
        if name is not None:
171
249
            self.name_hook(a_callable, name)
172
250
 
 
251
    def uninstall_named_hook(self, hook_name, label):
 
252
        """Uninstall named hooks.
 
253
 
 
254
        :param hook_name: Hook point name
 
255
        :param label: Label of the callable to uninstall
 
256
        """
 
257
        try:
 
258
            hook = self[hook_name]
 
259
        except KeyError:
 
260
            raise UnknownHook(self.__class__.__name__, hook_name)
 
261
        try:
 
262
            uninstall = getattr(hook, "uninstall")
 
263
        except AttributeError:
 
264
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
 
265
        else:
 
266
            uninstall(label)
 
267
 
173
268
    def name_hook(self, a_callable, name):
174
269
        """Associate name with a_callable to show users what is running."""
175
270
        self._callable_names[a_callable] = name
176
271
 
 
272
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
 
273
        self._lazy_callable_names[(callable_module, callable_member)]= \
 
274
            callable_name
 
275
 
177
276
 
178
277
class HookPoint(object):
179
278
    """A single hook that clients can register to be called back when it fires.
180
279
 
181
280
    :ivar name: The name of the hook.
 
281
    :ivar doc: The docs for using the hook.
182
282
    :ivar introduced: A version tuple specifying what version the hook was
183
283
        introduced in. None indicates an unknown version.
184
284
    :ivar deprecated: A version tuple specifying what version the hook was
185
285
        deprecated or superseded in. None indicates that the hook is not
186
286
        superseded or deprecated. If the hook is superseded then the doc
187
287
        should describe the recommended replacement hook to register for.
188
 
    :ivar doc: The docs for using the hook.
189
288
    """
190
289
 
191
 
    def __init__(self, name, doc, introduced, deprecated):
 
290
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
192
291
        """Create a HookPoint.
193
292
 
194
293
        :param name: The name of the hook, for clients to use when registering.
201
300
        self.__doc__ = doc
202
301
        self.introduced = introduced
203
302
        self.deprecated = deprecated
204
 
        self._callbacks = []
205
 
        self._callback_names = {}
 
303
        if callbacks is None:
 
304
            self._callbacks = []
 
305
        else:
 
306
            self._callbacks = callbacks
206
307
 
207
308
    def docs(self):
208
309
        """Generate the documentation for this HookPoint.
217
318
            introduced_string = _format_version_tuple(self.introduced)
218
319
        else:
219
320
            introduced_string = 'unknown'
220
 
        strings.append('Introduced in: %s' % introduced_string)
 
321
        strings.append(gettext('Introduced in: %s') % introduced_string)
221
322
        if self.deprecated:
222
323
            deprecated_string = _format_version_tuple(self.deprecated)
223
 
            strings.append('Deprecated in: %s' % deprecated_string)
 
324
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
224
325
        strings.append('')
225
326
        strings.extend(textwrap.wrap(self.__doc__,
226
327
            break_long_words=False))
228
329
        return '\n'.join(strings)
229
330
 
230
331
    def __eq__(self, other):
231
 
        return (type(other) == type(self) and 
232
 
            other.__dict__ == self.__dict__)
 
332
        return (isinstance(other, type(self)) and other.__dict__ == self.__dict__)
 
333
 
 
334
    def hook_lazy(self, callback_module, callback_member, callback_label):
 
335
        """Lazily register a callback to be called when this HookPoint fires.
 
336
 
 
337
        :param callback_module: Module of the callable to use when this
 
338
            HookPoint fires.
 
339
        :param callback_member: Member name of the callback.
 
340
        :param callback_label: A label to show in the UI while this callback is
 
341
            processing.
 
342
        """
 
343
        obj_getter = registry._LazyObjectGetter(callback_module,
 
344
            callback_member)
 
345
        self._callbacks.append((obj_getter, callback_label))
233
346
 
234
347
    def hook(self, callback, callback_label):
235
348
        """Register a callback to be called when this HookPoint fires.
238
351
        :param callback_label: A label to show in the UI while this callback is
239
352
            processing.
240
353
        """
241
 
        self._callbacks.append(callback)
242
 
        if callback_label is not None:
243
 
            self._callback_names[callback] = callback_label
 
354
        obj_getter = registry._ObjectGetter(callback)
 
355
        self._callbacks.append((obj_getter, callback_label))
 
356
 
 
357
    def uninstall(self, label):
 
358
        """Uninstall the callback with the specified label.
 
359
 
 
360
        :param label: Label of the entry to uninstall
 
361
        """
 
362
        entries_to_remove = []
 
363
        for entry in self._callbacks:
 
364
            (entry_callback, entry_label) = entry
 
365
            if entry_label == label:
 
366
                entries_to_remove.append(entry)
 
367
        if entries_to_remove == []:
 
368
            raise KeyError("No entry with label %r" % label)
 
369
        for entry in entries_to_remove:
 
370
            self._callbacks.remove(entry)
244
371
 
245
372
    def __iter__(self):
246
 
        return iter(self._callbacks)
 
373
        return (callback.get_obj() for callback, name in self._callbacks)
247
374
 
248
375
    def __len__(self):
249
376
        return len(self._callbacks)
253
380
        strings.append("<%s(" % type(self).__name__)
254
381
        strings.append(self.name)
255
382
        strings.append("), callbacks=[")
256
 
        for callback in self._callbacks:
257
 
            strings.append(repr(callback))
 
383
        callbacks = self._callbacks
 
384
        for (callback, callback_name) in callbacks:
 
385
            strings.append(repr(callback.get_obj()))
258
386
            strings.append("(")
259
 
            strings.append(self._callback_names[callback])
 
387
            strings.append(callback_name)
260
388
            strings.append("),")
261
 
        if len(self._callbacks) == 1:
 
389
        if len(callbacks) == 1:
262
390
            strings[-1] = ")"
263
391
        strings.append("]>")
264
392
        return ''.join(strings)
276
404
 
277
405
  yyy.hooks.install_named_hook("xxx", ...)
278
406
 
279
 
See `Using hooks`_ in the User Guide for examples.
280
 
 
281
 
.. _Using hooks: ../user-guide/hooks.html
 
407
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
282
408
 
283
409
The class that contains each hook is given before the hooks it supplies. For
284
410
instance, BranchHooks as the class is the hooks class for
285
 
`bzrlib.branch.Branch.hooks`.
 
411
`breezy.branch.Branch.hooks`.
286
412
 
287
413
Each description also indicates whether the hook runs on the client (the
288
414
machine where bzr was invoked) or the server (the machine addressed by
305
431
        hooks = known_hooks_key_to_object(hook_key)
306
432
        segments.append(hooks.docs())
307
433
    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))