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
17
18
"""Support for plugin hooking logic."""
19
from __future__ import absolute_import
19
from bzrlib import registry
25
20
from bzrlib.lazy_import import lazy_import
26
21
lazy_import(globals(), """
29
24
from bzrlib import (
30
_format_version_tuple,
34
from bzrlib.i18n import gettext
25
_format_version_tuple,
28
from bzrlib.help_topics import help_as_plain_text
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
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)
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
54
This is useful for resetting/restoring all the hooks to a known state,
55
as is done in bzrlib.tests.TestCase._clear_hooks.
57
for key in self.keys():
58
yield key, self.key_to_parent_and_attribute(key)
60
def key_to_parent_and_attribute(self, (module_name, member_name)):
61
"""Convert a known_hooks key to a (parent_obj, attr) pair.
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.
68
parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
70
return pyutils.get_named_object(parent_mod, parent_member), attr
73
_builtin_known_hooks = (
74
('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
75
('bzrlib.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
76
('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
77
('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
78
('bzrlib.info', 'hooks', 'InfoHooks'),
79
('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
80
('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
81
('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
82
('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
83
('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
84
('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
85
('bzrlib.status', 'hooks', 'StatusHooks'),
86
('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
87
'RioVersionInfoBuilderHooks'),
88
('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
89
'MergeDirectiveHooks'),
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
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',
39
known_hooks.register_lazy(('bzrlib.bzrdir', 'BzrDir.hooks'), 'bzrlib.bzrdir',
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',
47
known_hooks.register_lazy(('bzrlib.merge', 'Merger.hooks'), 'bzrlib.merge',
49
known_hooks.register_lazy(('bzrlib.msgeditor', 'hooks'), 'bzrlib.msgeditor',
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')
98
65
def known_hooks_key_to_object((module_name, member_name)):
118
96
FOO hook is triggered.
121
def __init__(self, module=None, member_name=None):
122
"""Create a new hooks dictionary.
124
:param module: The module from which this hooks dictionary should be loaded
125
(used for lazy hooks)
126
:param member_name: Name under which this hooks dictionary should be loaded.
127
(used for lazy hooks)
129
100
dict.__init__(self)
130
101
self._callable_names = {}
131
self._lazy_callable_names = {}
132
self._module = module
133
self._member_name = member_name
135
def add_hook(self, name, doc, introduced, deprecated=None):
136
"""Add a hook point to this dictionary.
138
:param name: The name of the hook, for clients to use when registering.
139
:param doc: The docs for the hook.
140
:param introduced: When the hook was introduced (e.g. (0, 15)).
141
:param deprecated: When the hook was deprecated, None for
145
raise errors.DuplicateKey(name)
147
callbacks = _lazy_hooks.setdefault(
148
(self._module, self._member_name, name), [])
151
hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
152
deprecated=deprecated, callbacks=callbacks)
153
self[name] = hookpoint
155
@symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
156
103
def create_hook(self, hook):
157
104
"""Create a hook which can have callbacks registered for it.
198
145
the code names are rarely meaningful for end users and this is not
199
146
intended for debugging.
201
name = self._callable_names.get(a_callable, None)
202
if name is None and a_callable is not None:
203
name = self._lazy_callable_names.get((a_callable.__module__,
204
a_callable.__name__),
207
return 'No hook name'
211
def install_named_hook_lazy(self, hook_name, callable_module,
212
callable_member, name):
213
"""Install a_callable in to the hook hook_name lazily, and label it.
215
:param hook_name: A hook name. See the __init__ method for the complete
217
:param callable_module: Name of the module in which the callable is
219
:param callable_member: Member name of the callable.
220
:param name: A name to associate the callable with, to show users what
224
hook = self[hook_name]
226
raise errors.UnknownHook(self.__class__.__name__, hook_name)
228
hook_lazy = getattr(hook, "hook_lazy")
229
except AttributeError:
230
raise errors.UnsupportedOperation(self.install_named_hook_lazy,
233
hook_lazy(callable_module, callable_member, name)
235
self.name_hook_lazy(callable_module, callable_member, name)
148
return self._callable_names.get(a_callable, "No hook name")
237
150
def install_named_hook(self, hook_name, a_callable, name):
238
151
"""Install a_callable in to the hook hook_name, and label it name.
240
:param hook_name: A hook name. See the __init__ method for the complete
153
:param hook_name: A hook name. See the __init__ method of BranchHooks
154
for the complete list of hooks.
242
155
:param a_callable: The callable to be invoked when the hook triggers.
243
156
The exact signature will depend on the hook - see the __init__
244
method for details on each hook.
157
method of BranchHooks for details on each hook.
245
158
:param name: A name to associate a_callable with, to show users what is
257
170
if name is not None:
258
171
self.name_hook(a_callable, name)
260
def uninstall_named_hook(self, hook_name, label):
261
"""Uninstall named hooks.
263
:param hook_name: Hook point name
264
:param label: Label of the callable to uninstall
267
hook = self[hook_name]
269
raise errors.UnknownHook(self.__class__.__name__, hook_name)
271
uninstall = getattr(hook, "uninstall")
272
except AttributeError:
273
raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
277
173
def name_hook(self, a_callable, name):
278
174
"""Associate name with a_callable to show users what is running."""
279
175
self._callable_names[a_callable] = name
281
def name_hook_lazy(self, callable_module, callable_member, callable_name):
282
self._lazy_callable_names[(callable_module, callable_member)]= \
286
178
class HookPoint(object):
287
179
"""A single hook that clients can register to be called back when it fires.
289
181
:ivar name: The name of the hook.
290
:ivar doc: The docs for using the hook.
291
182
:ivar introduced: A version tuple specifying what version the hook was
292
183
introduced in. None indicates an unknown version.
293
184
:ivar deprecated: A version tuple specifying what version the hook was
294
185
deprecated or superseded in. None indicates that the hook is not
295
186
superseded or deprecated. If the hook is superseded then the doc
296
187
should describe the recommended replacement hook to register for.
188
:ivar doc: The docs for using the hook.
299
def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
191
def __init__(self, name, doc, introduced, deprecated):
300
192
"""Create a HookPoint.
302
194
:param name: The name of the hook, for clients to use when registering.
added
removed
bzrlib/hooks.py
