18
18
"""Support for plugin hooking logic."""
19
from bzrlib import registry
20
24
from bzrlib.lazy_import import lazy_import
21
from bzrlib.symbol_versioning import deprecated_method
22
25
lazy_import(globals(), """
25
28
from bzrlib import (
26
_format_version_tuple,
29
from bzrlib.help_topics import help_as_plain_text
29
_format_version_tuple,
33
from bzrlib.i18n import gettext
33
known_hooks = registry.Registry()
34
# known_hooks registry contains
35
# tuple of (module, member name) which is the hook point
36
# module where the specific hooks are defined
37
# callable to get the empty specific Hooks for that attribute
38
known_hooks.register_lazy(('bzrlib.branch', 'Branch.hooks'), 'bzrlib.branch',
40
known_hooks.register_lazy(('bzrlib.bzrdir', 'BzrDir.hooks'), 'bzrlib.bzrdir',
42
known_hooks.register_lazy(('bzrlib.commands', 'Command.hooks'),
43
'bzrlib.commands', 'CommandHooks')
44
known_hooks.register_lazy(('bzrlib.info', 'hooks'),
45
'bzrlib.info', 'InfoHooks')
46
known_hooks.register_lazy(('bzrlib.lock', 'Lock.hooks'), 'bzrlib.lock',
48
known_hooks.register_lazy(('bzrlib.merge', 'Merger.hooks'), 'bzrlib.merge',
50
known_hooks.register_lazy(('bzrlib.msgeditor', 'hooks'), 'bzrlib.msgeditor',
52
known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),
53
'bzrlib.mutabletree', 'MutableTreeHooks')
54
known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),
55
'bzrlib.smart.client', 'SmartClientHooks')
56
known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),
57
'bzrlib.smart.server', 'SmartServerHooks')
58
known_hooks.register_lazy(
59
('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks'),
60
'bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilderHooks')
61
known_hooks.register_lazy(
62
('bzrlib.merge_directive', '_BaseMergeDirective.hooks'),
63
'bzrlib.merge_directive', 'MergeDirectiveHooks')
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
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)
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
53
This is useful for resetting/restoring all the hooks to a known state,
54
as is done in bzrlib.tests.TestCase._clear_hooks.
56
for key in self.keys():
57
yield key, self.key_to_parent_and_attribute(key)
59
def key_to_parent_and_attribute(self, (module_name, member_name)):
60
"""Convert a known_hooks key to a (parent_obj, attr) pair.
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.
67
parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
69
return pyutils.get_named_object(parent_mod, parent_member), attr
72
_builtin_known_hooks = (
73
('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
74
('bzrlib.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
75
('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
76
('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
77
('bzrlib.info', 'hooks', 'InfoHooks'),
78
('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
79
('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
80
('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
81
('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
82
('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
83
('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
84
('bzrlib.status', 'hooks', 'StatusHooks'),
85
('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
86
'RioVersionInfoBuilderHooks'),
87
('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
88
'MergeDirectiveHooks'),
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
66
97
def known_hooks_key_to_object((module_name, member_name)):
97
117
FOO hook is triggered.
120
def __init__(self, module=None, member_name=None):
121
"""Create a new hooks dictionary.
123
:param module: The module from which this hooks dictionary should be loaded
124
(used for lazy hooks)
125
:param member_name: Name under which this hooks dictionary should be loaded.
126
(used for lazy hooks)
101
128
dict.__init__(self)
102
129
self._callable_names = {}
130
self._lazy_callable_names = {}
131
self._module = module
132
self._member_name = member_name
134
def add_hook(self, name, doc, introduced, deprecated=None):
135
"""Add a hook point to this dictionary.
137
:param name: The name of the hook, for clients to use when registering.
138
:param doc: The docs for the hook.
139
:param introduced: When the hook was introduced (e.g. (0, 15)).
140
:param deprecated: When the hook was deprecated, None for
144
raise errors.DuplicateKey(name)
146
callbacks = _lazy_hooks.setdefault(
147
(self._module, self._member_name, name), [])
150
hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
151
deprecated=deprecated, callbacks=callbacks)
152
self[name] = hookpoint
154
@symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
104
155
def create_hook(self, hook):
105
156
"""Create a hook which can have callbacks registered for it.
146
197
the code names are rarely meaningful for end users and this is not
147
198
intended for debugging.
149
return self._callable_names.get(a_callable, "No hook name")
200
name = self._callable_names.get(a_callable, None)
201
if name is None and a_callable is not None:
202
name = self._lazy_callable_names.get((a_callable.__module__,
203
a_callable.__name__),
206
return 'No hook name'
210
def install_named_hook_lazy(self, hook_name, callable_module,
211
callable_member, name):
212
"""Install a_callable in to the hook hook_name lazily, and label it.
214
:param hook_name: A hook name. See the __init__ method for the complete
216
:param callable_module: Name of the module in which the callable is
218
:param callable_member: Member name of the callable.
219
:param name: A name to associate the callable with, to show users what
223
hook = self[hook_name]
225
raise errors.UnknownHook(self.__class__.__name__, hook_name)
227
hook_lazy = getattr(hook, "hook_lazy")
228
except AttributeError:
229
raise errors.UnsupportedOperation(self.install_named_hook_lazy,
232
hook_lazy(callable_module, callable_member, name)
234
self.name_hook_lazy(callable_module, callable_member, name)
151
236
def install_named_hook(self, hook_name, a_callable, name):
152
237
"""Install a_callable in to the hook hook_name, and label it name.
154
:param hook_name: A hook name. See the __init__ method of BranchHooks
155
for the complete list of hooks.
239
:param hook_name: A hook name. See the __init__ method for the complete
156
241
:param a_callable: The callable to be invoked when the hook triggers.
157
242
The exact signature will depend on the hook - see the __init__
158
method of BranchHooks for details on each hook.
243
method for details on each hook.
159
244
:param name: A name to associate a_callable with, to show users what is
171
256
if name is not None:
172
257
self.name_hook(a_callable, name)
259
def uninstall_named_hook(self, hook_name, label):
260
"""Uninstall named hooks.
262
:param hook_name: Hook point name
263
:param label: Label of the callable to uninstall
266
hook = self[hook_name]
268
raise errors.UnknownHook(self.__class__.__name__, hook_name)
270
uninstall = getattr(hook, "uninstall")
271
except AttributeError:
272
raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
174
276
def name_hook(self, a_callable, name):
175
277
"""Associate name with a_callable to show users what is running."""
176
278
self._callable_names[a_callable] = name
280
def name_hook_lazy(self, callable_module, callable_member, callable_name):
281
self._lazy_callable_names[(callable_module, callable_member)]= \
179
285
class HookPoint(object):
180
286
"""A single hook that clients can register to be called back when it fires.
182
288
:ivar name: The name of the hook.
289
:ivar doc: The docs for using the hook.
183
290
:ivar introduced: A version tuple specifying what version the hook was
184
291
introduced in. None indicates an unknown version.
185
292
:ivar deprecated: A version tuple specifying what version the hook was
186
293
deprecated or superseded in. None indicates that the hook is not
187
294
superseded or deprecated. If the hook is superseded then the doc
188
295
should describe the recommended replacement hook to register for.
189
:ivar doc: The docs for using the hook.
192
def __init__(self, name, doc, introduced, deprecated):
298
def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
193
299
"""Create a HookPoint.
195
301
:param name: The name of the hook, for clients to use when registering.
added
removed
bzrlib/hooks.py
