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
20
from bzrlib.lazy_import import lazy_import
19
from __future__ import absolute_import
25
from .lazy_import import lazy_import
21
26
lazy_import(globals(), """
25
_format_version_tuple,
28
from bzrlib.help_topics import help_as_plain_text
30
_format_version_tuple,
34
from breezy.i18n import gettext
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
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 breezy.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, key):
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(*key)
69
return pyutils.get_named_object(parent_mod, parent_member), attr
72
_builtin_known_hooks = (
73
('breezy.branch', 'Branch.hooks', 'BranchHooks'),
74
('breezy.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
75
('breezy.commands', 'Command.hooks', 'CommandHooks'),
76
('breezy.config', 'ConfigHooks', '_ConfigHooks'),
77
('breezy.info', 'hooks', 'InfoHooks'),
78
('breezy.lock', 'Lock.hooks', 'LockHooks'),
79
('breezy.merge', 'Merger.hooks', 'MergeHooks'),
80
('breezy.msgeditor', 'hooks', 'MessageEditorHooks'),
81
('breezy.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
82
('breezy.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
83
('breezy.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
84
('breezy.status', 'hooks', 'StatusHooks'),
85
('breezy.transport', 'Transport.hooks', 'TransportHooks'),
86
('breezy.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
87
'RioVersionInfoBuilderHooks'),
88
('breezy.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
98
def known_hooks_key_to_object(key):
99
"""Convert a known_hooks key to a object.
101
:param key: A tuple (module_name, member_name) as found in the keys of
102
the known_hooks registry.
103
:return: The object this specifies.
105
return pyutils.get_named_object(*key)
92
108
class Hooks(dict):
96
112
FOO hook is triggered.
115
def __init__(self, module=None, member_name=None):
116
"""Create a new hooks dictionary.
118
:param module: The module from which this hooks dictionary should be loaded
119
(used for lazy hooks)
120
:param member_name: Name under which this hooks dictionary should be loaded.
121
(used for lazy hooks)
100
123
dict.__init__(self)
101
124
self._callable_names = {}
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
125
self._lazy_callable_names = {}
126
self._module = module
127
self._member_name = member_name
129
def add_hook(self, name, doc, introduced, deprecated=None):
130
"""Add a hook point to this dictionary.
132
:param name: The name of the hook, for clients to use when registering.
133
:param doc: The docs for the hook.
134
:param introduced: When the hook was introduced (e.g. (0, 15)).
135
:param deprecated: When the hook was deprecated, None for
110
if hook.name in self:
111
raise errors.DuplicateKey(hook.name)
112
self[hook.name] = hook
139
raise errors.DuplicateKey(name)
141
callbacks = _lazy_hooks.setdefault(
142
(self._module, self._member_name, name), [])
145
hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
146
deprecated=deprecated, callbacks=callbacks)
147
self[name] = hookpoint
115
150
"""Generate the documentation for this Hooks instance.
145
180
the code names are rarely meaningful for end users and this is not
146
181
intended for debugging.
148
return self._callable_names.get(a_callable, "No hook name")
183
name = self._callable_names.get(a_callable, None)
184
if name is None and a_callable is not None:
185
name = self._lazy_callable_names.get((a_callable.__module__,
186
a_callable.__name__),
189
return 'No hook name'
193
def install_named_hook_lazy(self, hook_name, callable_module,
194
callable_member, name):
195
"""Install a_callable in to the hook hook_name lazily, and label it.
197
:param hook_name: A hook name. See the __init__ method for the complete
199
:param callable_module: Name of the module in which the callable is
201
:param callable_member: Member name of the callable.
202
:param name: A name to associate the callable with, to show users what
206
hook = self[hook_name]
208
raise errors.UnknownHook(self.__class__.__name__, hook_name)
210
hook_lazy = getattr(hook, "hook_lazy")
211
except AttributeError:
212
raise errors.UnsupportedOperation(self.install_named_hook_lazy,
215
hook_lazy(callable_module, callable_member, name)
217
self.name_hook_lazy(callable_module, callable_member, name)
150
219
def install_named_hook(self, hook_name, a_callable, name):
151
220
"""Install a_callable in to the hook hook_name, and label it name.
153
:param hook_name: A hook name. See the __init__ method of BranchHooks
154
for the complete list of hooks.
222
:param hook_name: A hook name. See the __init__ method for the complete
155
224
:param a_callable: The callable to be invoked when the hook triggers.
156
225
The exact signature will depend on the hook - see the __init__
157
method of BranchHooks for details on each hook.
226
method for details on each hook.
158
227
:param name: A name to associate a_callable with, to show users what is
170
239
if name is not None:
171
240
self.name_hook(a_callable, name)
242
def uninstall_named_hook(self, hook_name, label):
243
"""Uninstall named hooks.
245
:param hook_name: Hook point name
246
:param label: Label of the callable to uninstall
249
hook = self[hook_name]
251
raise errors.UnknownHook(self.__class__.__name__, hook_name)
253
uninstall = getattr(hook, "uninstall")
254
except AttributeError:
255
raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
173
259
def name_hook(self, a_callable, name):
174
260
"""Associate name with a_callable to show users what is running."""
175
261
self._callable_names[a_callable] = name
263
def name_hook_lazy(self, callable_module, callable_member, callable_name):
264
self._lazy_callable_names[(callable_module, callable_member)]= \
178
268
class HookPoint(object):
179
269
"""A single hook that clients can register to be called back when it fires.
181
271
:ivar name: The name of the hook.
272
:ivar doc: The docs for using the hook.
182
273
:ivar introduced: A version tuple specifying what version the hook was
183
274
introduced in. None indicates an unknown version.
184
275
:ivar deprecated: A version tuple specifying what version the hook was
185
276
deprecated or superseded in. None indicates that the hook is not
186
277
superseded or deprecated. If the hook is superseded then the doc
187
278
should describe the recommended replacement hook to register for.
188
:ivar doc: The docs for using the hook.
191
def __init__(self, name, doc, introduced, deprecated):
281
def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
192
282
"""Create a HookPoint.
194
284
:param name: The name of the hook, for clients to use when registering.
added
removed
breezy/hooks.py
