13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18
18
"""Support for plugin hooking logic."""
19
from bzrlib import registry
20
19
from bzrlib.lazy_import import lazy_import
20
from bzrlib.symbol_versioning import deprecated_method, one_five
21
21
lazy_import(globals(), """
25
25
_format_version_tuple,
28
from bzrlib.help_topics import help_as_plain_text
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
93
32
"""A dictionary mapping hook name to a list of callables.
148
83
return self._callable_names.get(a_callable, "No hook name")
85
@deprecated_method(one_five)
86
def install_hook(self, hook_name, a_callable):
87
"""Install a_callable in to the hook hook_name.
89
:param hook_name: A hook name. See the __init__ method of BranchHooks
90
for the complete list of hooks.
91
:param a_callable: The callable to be invoked when the hook triggers.
92
The exact signature will depend on the hook - see the __init__
93
method of BranchHooks for details on each hook.
95
self.install_named_hook(hook_name, a_callable, None)
150
97
def install_named_hook(self, hook_name, a_callable, name):
151
98
"""Install a_callable in to the hook hook_name, and label it name.
175
122
self._callable_names[a_callable] = name
178
class HookPoint(object):
179
126
"""A single hook that clients can register to be called back when it fires.
181
128
:ivar name: The name of the hook.
182
129
:ivar introduced: A version tuple specifying what version the hook was
183
130
introduced in. None indicates an unknown version.
184
131
:ivar deprecated: A version tuple specifying what version the hook was
185
deprecated or superseded in. None indicates that the hook is not
186
superseded or deprecated. If the hook is superseded then the doc
132
deprecated or superceded in. None indicates that the hook is not
133
superceded or deprecated. If the hook is superceded then the doc
187
134
should describe the recommended replacement hook to register for.
188
135
:ivar doc: The docs for using the hook.
191
138
def __init__(self, name, doc, introduced, deprecated):
192
"""Create a HookPoint.
194
141
:param name: The name of the hook, for clients to use when registering.
195
142
:param doc: The docs for the hook.
196
143
:param introduced: When the hook was introduced (e.g. (0, 15)).
220
167
strings.append('Introduced in: %s' % introduced_string)
221
168
if self.deprecated:
222
169
deprecated_string = _format_version_tuple(self.deprecated)
223
strings.append('Deprecated in: %s' % deprecated_string)
171
deprecated_string = 'Not deprecated'
172
strings.append('Deprecated in: %s' % deprecated_string)
224
173
strings.append('')
225
strings.extend(textwrap.wrap(self.__doc__,
226
break_long_words=False))
174
strings.extend(textwrap.wrap(self.__doc__))
227
175
strings.append('')
228
176
return '\n'.join(strings)
230
def __eq__(self, other):
231
return (type(other) == type(self) and
232
other.__dict__ == self.__dict__)
234
178
def hook(self, callback, callback_label):
235
"""Register a callback to be called when this HookPoint fires.
179
"""Call this hook with callback, using callback_label to describe it.
237
:param callback: The callable to use when this HookPoint fires.
181
:param callback: The callable to use when this Hook fires.
238
182
:param callback_label: A label to show in the UI while this callback is
241
185
self._callbacks.append(callback)
242
if callback_label is not None:
243
self._callback_names[callback] = callback_label
186
self._callback_names[callback] = callback_label
245
188
def __iter__(self):
246
189
return iter(self._callbacks)
249
return len(self._callbacks)
251
191
def __repr__(self):
253
strings.append("<%s(" % type(self).__name__)
193
strings.append("<bzrlib.hooks.Hook(")
254
194
strings.append(self.name)
255
195
strings.append("), callbacks=[")
256
196
for callback in self._callbacks:
262
202
strings[-1] = ")"
263
203
strings.append("]>")
264
204
return ''.join(strings)
275
A hook of type *xxx* of class *yyy* needs to be registered using::
277
yyy.hooks.install_named_hook("xxx", ...)
279
See `Using hooks`_ in the User Guide for examples.
281
.. _Using hooks: ../user-guide/hooks.html
283
The class that contains each hook is given before the hooks it supplies. For
284
instance, BranchHooks as the class is the hooks class for
285
`bzrlib.branch.Branch.hooks`.
287
Each description also indicates whether the hook runs on the client (the
288
machine where bzr was invoked) or the server (the machine addressed by
289
the branch URL). These may be, but are not necessarily, the same machine.
291
Plugins (including hooks) are run on the server if all of these is true:
293
* The connection is via a smart server (accessed with a URL starting with
294
"bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
295
URL when a smart server is available via HTTP).
297
* The hook is either server specific or part of general infrastructure rather
298
than client specific code (such as commit).
302
def hooks_help_text(topic):
303
segments = [_help_prefix]
304
for hook_key in sorted(known_hooks.keys()):
305
hooks = known_hooks_key_to_object(hook_key)
306
segments.append(hooks.docs())
307
return '\n'.join(segments)
added
removed
bzrlib/hooks.py
