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
25
from .lazy_import import lazy_import
19
from bzrlib import registry
20
from bzrlib.lazy_import import lazy_import
26
21
lazy_import(globals(), """
30
_format_version_tuple,
33
from breezy.i18n import gettext
25
_format_version_tuple,
28
from bzrlib.help_topics import help_as_plain_text
37
class UnknownHook(errors.BzrError):
39
_fmt = "The %(type)s hook '%(hook)s' is unknown in this version of breezy."
41
def __init__(self, hook_type, hook_name):
42
errors.BzrError.__init__(self)
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
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)
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
63
This is useful for resetting/restoring all the hooks to a known state,
64
as is done in breezy.tests.TestCase._clear_hooks.
66
for key in self.keys():
67
yield key, self.key_to_parent_and_attribute(key)
69
def key_to_parent_and_attribute(self, key):
70
"""Convert a known_hooks key to a (parent_obj, attr) pair.
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.
77
parent_mod, parent_member, attr = pyutils.calc_parent_name(*key)
78
return pyutils.get_named_object(parent_mod, parent_member), attr
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'),
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
107
def known_hooks_key_to_object(key):
108
"""Convert a known_hooks key to a object.
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.
114
return pyutils.get_named_object(*key)
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')
65
def known_hooks_key_to_object((module_name, member_name)):
66
"""Convert a known_hooks key to a object.
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.
72
return registry._LazyObjectGetter(module_name, member_name).get_obj()
75
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
76
"""Convert a known_hooks key to a object.
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.
82
member_list = member_name.rsplit('.', 1)
83
if len(member_list) == 2:
84
parent_name, attribute = member_list
87
attribute = member_name
88
parent = known_hooks_key_to_object((module_name, parent_name))
89
return parent, attribute
117
92
class Hooks(dict):
121
96
FOO hook is triggered.
124
def __init__(self, module=None, member_name=None):
125
"""Create a new hooks dictionary.
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)
132
100
dict.__init__(self)
133
101
self._callable_names = {}
134
self._lazy_callable_names = {}
135
self._module = module
136
self._member_name = member_name
138
def add_hook(self, name, doc, introduced, deprecated=None):
139
"""Add a hook point to this dictionary.
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
103
def create_hook(self, hook):
104
"""Create a hook which can have callbacks registered for it.
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
148
raise errors.DuplicateKey(name)
150
callbacks = _lazy_hooks.setdefault(
151
(self._module, self._member_name, name), [])
154
hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
155
deprecated=deprecated, callbacks=callbacks)
156
self[name] = hookpoint
110
if hook.name in self:
111
raise errors.DuplicateKey(hook.name)
112
self[hook.name] = hook
159
115
"""Generate the documentation for this Hooks instance.
189
145
the code names are rarely meaningful for end users and this is not
190
146
intended for debugging.
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__),
198
return 'No hook name'
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.
206
:param hook_name: A hook name. See the __init__ method for the complete
208
:param callable_module: Name of the module in which the callable is
210
:param callable_member: Member name of the callable.
211
:param name: A name to associate the callable with, to show users what
215
hook = self[hook_name]
217
raise UnknownHook(self.__class__.__name__, hook_name)
219
hook_lazy = getattr(hook, "hook_lazy")
220
except AttributeError:
221
raise errors.UnsupportedOperation(self.install_named_hook_lazy,
224
hook_lazy(callable_module, callable_member, name)
226
self.name_hook_lazy(callable_module, callable_member, name)
148
return self._callable_names.get(a_callable, "No hook name")
228
150
def install_named_hook(self, hook_name, a_callable, name):
229
151
"""Install a_callable in to the hook hook_name, and label it name.
231
: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.
233
155
:param a_callable: The callable to be invoked when the hook triggers.
234
156
The exact signature will depend on the hook - see the __init__
235
method for details on each hook.
157
method of BranchHooks for details on each hook.
236
158
:param name: A name to associate a_callable with, to show users what is
240
162
hook = self[hook_name]
242
raise UnknownHook(self.__class__.__name__, hook_name)
164
raise errors.UnknownHook(self.__class__.__name__, hook_name)
244
166
# list hooks, old-style, not yet deprecated but less useful.
245
167
hook.append(a_callable)
248
170
if name is not None:
249
171
self.name_hook(a_callable, name)
251
def uninstall_named_hook(self, hook_name, label):
252
"""Uninstall named hooks.
254
:param hook_name: Hook point name
255
:param label: Label of the callable to uninstall
258
hook = self[hook_name]
260
raise UnknownHook(self.__class__.__name__, hook_name)
262
uninstall = getattr(hook, "uninstall")
263
except AttributeError:
264
raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
268
173
def name_hook(self, a_callable, name):
269
174
"""Associate name with a_callable to show users what is running."""
270
175
self._callable_names[a_callable] = name
272
def name_hook_lazy(self, callable_module, callable_member, callable_name):
273
self._lazy_callable_names[(callable_module, callable_member)]= \
277
178
class HookPoint(object):
278
179
"""A single hook that clients can register to be called back when it fires.
280
181
:ivar name: The name of the hook.
281
:ivar doc: The docs for using the hook.
282
182
:ivar introduced: A version tuple specifying what version the hook was
283
183
introduced in. None indicates an unknown version.
284
184
:ivar deprecated: A version tuple specifying what version the hook was
285
185
deprecated or superseded in. None indicates that the hook is not
286
186
superseded or deprecated. If the hook is superseded then the doc
287
187
should describe the recommended replacement hook to register for.
188
:ivar doc: The docs for using the hook.
290
def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
191
def __init__(self, name, doc, introduced, deprecated):
291
192
"""Create a HookPoint.
293
194
:param name: The name of the hook, for clients to use when registering.