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
18
17
"""Support for plugin hooking logic."""
19
from bzrlib import registry
19
from __future__ import absolute_import
20
25
from bzrlib.lazy_import import lazy_import
21
from bzrlib.symbol_versioning import deprecated_method
22
26
lazy_import(globals(), """
25
29
from bzrlib import (
26
_format_version_tuple,
29
from bzrlib.help_topics import help_as_plain_text
30
_format_version_tuple,
34
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.msgeditor', 'hooks'), 'bzrlib.msgeditor',
50
known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),
51
'bzrlib.mutabletree', 'MutableTreeHooks')
52
known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),
53
'bzrlib.smart.client', 'SmartClientHooks')
54
known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),
55
'bzrlib.smart.server', 'SmartServerHooks')
56
known_hooks.register_lazy(
57
('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks'),
58
'bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilderHooks')
59
known_hooks.register_lazy(
60
('bzrlib.merge_directive', '_BaseMergeDirective.hooks'),
61
'bzrlib.merge_directive', 'MergeDirectiveHooks')
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.transport', 'Transport.hooks', 'TransportHooks'),
87
('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
88
'RioVersionInfoBuilderHooks'),
89
('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
90
'MergeDirectiveHooks'),
93
known_hooks = KnownHooksRegistry()
94
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
95
known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
96
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
64
99
def known_hooks_key_to_object((module_name, member_name)):
95
119
FOO hook is triggered.
122
def __init__(self, module=None, member_name=None):
123
"""Create a new hooks dictionary.
125
:param module: The module from which this hooks dictionary should be loaded
126
(used for lazy hooks)
127
:param member_name: Name under which this hooks dictionary should be loaded.
128
(used for lazy hooks)
99
130
dict.__init__(self)
100
131
self._callable_names = {}
132
self._lazy_callable_names = {}
133
self._module = module
134
self._member_name = member_name
136
def add_hook(self, name, doc, introduced, deprecated=None):
137
"""Add a hook point to this dictionary.
139
:param name: The name of the hook, for clients to use when registering.
140
:param doc: The docs for the hook.
141
:param introduced: When the hook was introduced (e.g. (0, 15)).
142
:param deprecated: When the hook was deprecated, None for
146
raise errors.DuplicateKey(name)
148
callbacks = _lazy_hooks.setdefault(
149
(self._module, self._member_name, name), [])
152
hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
153
deprecated=deprecated, callbacks=callbacks)
154
self[name] = hookpoint
156
@symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
102
157
def create_hook(self, hook):
103
158
"""Create a hook which can have callbacks registered for it.
144
199
the code names are rarely meaningful for end users and this is not
145
200
intended for debugging.
147
return self._callable_names.get(a_callable, "No hook name")
202
name = self._callable_names.get(a_callable, None)
203
if name is None and a_callable is not None:
204
name = self._lazy_callable_names.get((a_callable.__module__,
205
a_callable.__name__),
208
return 'No hook name'
212
def install_named_hook_lazy(self, hook_name, callable_module,
213
callable_member, name):
214
"""Install a_callable in to the hook hook_name lazily, and label it.
216
:param hook_name: A hook name. See the __init__ method for the complete
218
:param callable_module: Name of the module in which the callable is
220
:param callable_member: Member name of the callable.
221
:param name: A name to associate the callable with, to show users what
225
hook = self[hook_name]
227
raise errors.UnknownHook(self.__class__.__name__, hook_name)
229
hook_lazy = getattr(hook, "hook_lazy")
230
except AttributeError:
231
raise errors.UnsupportedOperation(self.install_named_hook_lazy,
234
hook_lazy(callable_module, callable_member, name)
236
self.name_hook_lazy(callable_module, callable_member, name)
149
238
def install_named_hook(self, hook_name, a_callable, name):
150
239
"""Install a_callable in to the hook hook_name, and label it name.
152
:param hook_name: A hook name. See the __init__ method of BranchHooks
153
for the complete list of hooks.
241
:param hook_name: A hook name. See the __init__ method for the complete
154
243
:param a_callable: The callable to be invoked when the hook triggers.
155
244
The exact signature will depend on the hook - see the __init__
156
method of BranchHooks for details on each hook.
245
method for details on each hook.
157
246
:param name: A name to associate a_callable with, to show users what is
169
258
if name is not None:
170
259
self.name_hook(a_callable, name)
261
def uninstall_named_hook(self, hook_name, label):
262
"""Uninstall named hooks.
264
:param hook_name: Hook point name
265
:param label: Label of the callable to uninstall
268
hook = self[hook_name]
270
raise errors.UnknownHook(self.__class__.__name__, hook_name)
272
uninstall = getattr(hook, "uninstall")
273
except AttributeError:
274
raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
172
278
def name_hook(self, a_callable, name):
173
279
"""Associate name with a_callable to show users what is running."""
174
280
self._callable_names[a_callable] = name
282
def name_hook_lazy(self, callable_module, callable_member, callable_name):
283
self._lazy_callable_names[(callable_module, callable_member)]= \
177
287
class HookPoint(object):
178
288
"""A single hook that clients can register to be called back when it fires.
180
290
:ivar name: The name of the hook.
291
:ivar doc: The docs for using the hook.
181
292
:ivar introduced: A version tuple specifying what version the hook was
182
293
introduced in. None indicates an unknown version.
183
294
:ivar deprecated: A version tuple specifying what version the hook was
184
295
deprecated or superseded in. None indicates that the hook is not
185
296
superseded or deprecated. If the hook is superseded then the doc
186
297
should describe the recommended replacement hook to register for.
187
:ivar doc: The docs for using the hook.
190
def __init__(self, name, doc, introduced, deprecated):
300
def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
191
301
"""Create a HookPoint.
193
303
:param name: The name of the hook, for clients to use when registering.
216
328
introduced_string = _format_version_tuple(self.introduced)
218
330
introduced_string = 'unknown'
219
strings.append('Introduced in: %s' % introduced_string)
331
strings.append(gettext('Introduced in: %s') % introduced_string)
220
332
if self.deprecated:
221
333
deprecated_string = _format_version_tuple(self.deprecated)
223
deprecated_string = 'Not deprecated'
224
strings.append('Deprecated in: %s' % deprecated_string)
334
strings.append(gettext('Deprecated in: %s') % deprecated_string)
225
335
strings.append('')
226
strings.extend(textwrap.wrap(self.__doc__))
336
strings.extend(textwrap.wrap(self.__doc__,
337
break_long_words=False))
227
338
strings.append('')
228
339
return '\n'.join(strings)
230
341
def __eq__(self, other):
231
return (type(other) == type(self) and
232
other.__dict__ == self.__dict__)
342
return (type(other) == type(self) and other.__dict__ == self.__dict__)
344
def hook_lazy(self, callback_module, callback_member, callback_label):
345
"""Lazily register a callback to be called when this HookPoint fires.
347
:param callback_module: Module of the callable to use when this
349
:param callback_member: Member name of the callback.
350
:param callback_label: A label to show in the UI while this callback is
353
obj_getter = registry._LazyObjectGetter(callback_module,
355
self._callbacks.append((obj_getter, callback_label))
234
357
def hook(self, callback, callback_label):
235
358
"""Register a callback to be called when this HookPoint fires.
added
removed
bzrlib/hooks.py
