/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: 2020-04-05 19:11:34 UTC
  • mto: (7490.7.16 work)
  • mto: This revision was merged to the branch mainline in revision 7501.
  • Revision ID: jelmer@jelmer.uk-20200405191134-0aebh8ikiwygxma5
Populate the .gitignore file.

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.
120
164
        hook_docs = []
121
165
        name = self.__class__.__name__
122
166
        hook_docs.append(name)
123
 
        hook_docs.append("-"*len(name))
 
167
        hook_docs.append("-" * len(name))
124
168
        hook_docs.append("")
125
169
        for hook_name in hook_names:
126
170
            hook = self[hook_name]
133
177
                strings.append("~" * len(hook_name))
134
178
                strings.append("")
135
179
                strings.append("An old-style hook. For documentation see the __init__ "
136
 
                    "method of '%s'\n" % (name,))
 
180
                               "method of '%s'\n" % (name,))
137
181
                hook_docs.extend(strings)
138
182
        return "\n".join(hook_docs)
139
183
 
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
    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
226
 
150
227
    def install_named_hook(self, hook_name, a_callable, name):
151
228
        """Install a_callable in to the hook hook_name, and label it name.
152
229
 
153
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
154
 
            for the complete list of hooks.
 
230
        :param hook_name: A hook name. See the __init__ method for the complete
 
231
            list of hooks.
155
232
        :param a_callable: The callable to be invoked when the hook triggers.
156
233
            The exact signature will depend on the hook - see the __init__
157
 
            method of BranchHooks for details on each hook.
 
234
            method for details on each hook.
158
235
        :param name: A name to associate a_callable with, to show users what is
159
236
            running.
160
237
        """
161
238
        try:
162
239
            hook = self[hook_name]
163
240
        except KeyError:
164
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
241
            raise UnknownHook(self.__class__.__name__, hook_name)
165
242
        try:
166
243
            # list hooks, old-style, not yet deprecated but less useful.
167
244
            hook.append(a_callable)
170
247
        if name is not None:
171
248
            self.name_hook(a_callable, name)
172
249
 
 
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
 
173
267
    def name_hook(self, a_callable, name):
174
268
        """Associate name with a_callable to show users what is running."""
175
269
        self._callable_names[a_callable] = name
176
270
 
 
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
 
177
275
 
178
276
class HookPoint(object):
179
277
    """A single hook that clients can register to be called back when it fires.
180
278
 
181
279
    :ivar name: The name of the hook.
 
280
    :ivar doc: The docs for using the hook.
182
281
    :ivar introduced: A version tuple specifying what version the hook was
183
282
        introduced in. None indicates an unknown version.
184
283
    :ivar deprecated: A version tuple specifying what version the hook was
185
284
        deprecated or superseded in. None indicates that the hook is not
186
285
        superseded or deprecated. If the hook is superseded then the doc
187
286
        should describe the recommended replacement hook to register for.
188
 
    :ivar doc: The docs for using the hook.
189
287
    """
190
288
 
191
 
    def __init__(self, name, doc, introduced, deprecated):
 
289
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
192
290
        """Create a HookPoint.
193
291
 
194
292
        :param name: The name of the hook, for clients to use when registering.
201
299
        self.__doc__ = doc
202
300
        self.introduced = introduced
203
301
        self.deprecated = deprecated
204
 
        self._callbacks = []
205
 
        self._callback_names = {}
 
302
        if callbacks is None:
 
303
            self._callbacks = []
 
304
        else:
 
305
            self._callbacks = callbacks
206
306
 
207
307
    def docs(self):
208
308
        """Generate the documentation for this HookPoint.
211
311
        """
212
312
        strings = []
213
313
        strings.append(self.name)
214
 
        strings.append('~'*len(self.name))
 
314
        strings.append('~' * len(self.name))
215
315
        strings.append('')
216
316
        if self.introduced:
217
317
            introduced_string = _format_version_tuple(self.introduced)
218
318
        else:
219
319
            introduced_string = 'unknown'
220
 
        strings.append('Introduced in: %s' % introduced_string)
 
320
        strings.append(gettext('Introduced in: %s') % introduced_string)
221
321
        if self.deprecated:
222
322
            deprecated_string = _format_version_tuple(self.deprecated)
223
 
            strings.append('Deprecated in: %s' % deprecated_string)
 
323
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
224
324
        strings.append('')
225
325
        strings.extend(textwrap.wrap(self.__doc__,
226
 
            break_long_words=False))
 
326
                                     break_long_words=False))
227
327
        strings.append('')
228
328
        return '\n'.join(strings)
229
329
 
230
330
    def __eq__(self, other):
231
 
        return (type(other) == type(self) and 
232
 
            other.__dict__ == self.__dict__)
 
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))
233
345
 
234
346
    def hook(self, callback, callback_label):
235
347
        """Register a callback to be called when this HookPoint fires.
238
350
        :param callback_label: A label to show in the UI while this callback is
239
351
            processing.
240
352
        """
241
 
        self._callbacks.append(callback)
242
 
        if callback_label is not None:
243
 
            self._callback_names[callback] = callback_label
 
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)
244
370
 
245
371
    def __iter__(self):
246
 
        return iter(self._callbacks)
 
372
        return (callback.get_obj() for callback, name in self._callbacks)
247
373
 
248
374
    def __len__(self):
249
375
        return len(self._callbacks)
253
379
        strings.append("<%s(" % type(self).__name__)
254
380
        strings.append(self.name)
255
381
        strings.append("), callbacks=[")
256
 
        for callback in self._callbacks:
257
 
            strings.append(repr(callback))
 
382
        callbacks = self._callbacks
 
383
        for (callback, callback_name) in callbacks:
 
384
            strings.append(repr(callback.get_obj()))
258
385
            strings.append("(")
259
 
            strings.append(self._callback_names[callback])
 
386
            strings.append(callback_name)
260
387
            strings.append("),")
261
 
        if len(self._callbacks) == 1:
 
388
        if len(callbacks) == 1:
262
389
            strings[-1] = ")"
263
390
        strings.append("]>")
264
391
        return ''.join(strings)
265
392
 
266
393
 
267
394
_help_prefix = \
268
 
"""
 
395
    """
269
396
Hooks
270
397
=====
271
398
 
276
403
 
277
404
  yyy.hooks.install_named_hook("xxx", ...)
278
405
 
279
 
See `Using hooks`_ in the User Guide for examples.
280
 
 
281
 
.. _Using hooks: ../user-guide/hooks.html
 
406
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
282
407
 
283
408
The class that contains each hook is given before the hooks it supplies. For
284
409
instance, BranchHooks as the class is the hooks class for
285
 
`bzrlib.branch.Branch.hooks`.
 
410
`breezy.branch.Branch.hooks`.
286
411
 
287
412
Each description also indicates whether the hook runs on the client (the
288
413
machine where bzr was invoked) or the server (the machine addressed by
299
424
 
300
425
"""
301
426
 
 
427
 
302
428
def hooks_help_text(topic):
303
429
    segments = [_help_prefix]
304
430
    for hook_key in sorted(known_hooks.keys()):
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))