1
# Copyright (C) 2007-2010 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
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
18
"""Support for plugin hooking logic."""
24
from bzrlib.lazy_import import lazy_import
25
lazy_import(globals(), """
29
_format_version_tuple,
32
from bzrlib.help_topics import help_as_plain_text
36
class KnownHooksRegistry(registry.Registry):
37
# known_hooks registry contains
38
# tuple of (module, member name) which is the hook point
39
# module where the specific hooks are defined
40
# callable to get the empty specific Hooks for that attribute
42
def register_lazy_hook(self, hook_module_name, hook_member_name,
43
hook_factory_member_name):
44
self.register_lazy((hook_module_name, hook_member_name),
45
hook_module_name, hook_factory_member_name)
47
def iter_parent_objects(self):
48
"""Yield (hook_key, (parent_object, attr)) tuples for every registered
49
hook, where 'parent_object' is the object that holds the hook
52
This is useful for resetting/restoring all the hooks to a known state,
53
as is done in bzrlib.tests.TestCase._clear_hooks.
55
for key in self.keys():
56
yield key, self.key_to_parent_and_attribute(key)
58
def key_to_parent_and_attribute(self, (module_name, member_name)):
59
"""Convert a known_hooks key to a (parent_obj, attr) pair.
61
:param key: A tuple (module_name, member_name) as found in the keys of
62
the known_hooks registry.
63
:return: The parent_object of the hook and the name of the attribute on
64
that parent object where the hook is kept.
66
parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
68
return pyutils.get_named_object(parent_mod, parent_member), attr
71
_builtin_known_hooks = (
72
('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
73
('bzrlib.bzrdir', 'BzrDir.hooks', 'BzrDirHooks'),
74
('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
75
('bzrlib.info', 'hooks', 'InfoHooks'),
76
('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
77
('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
78
('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
79
('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
80
('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
81
('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
82
('bzrlib.status', 'hooks', 'StatusHooks'),
83
('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
84
'RioVersionInfoBuilderHooks'),
85
('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
86
'MergeDirectiveHooks'),
89
known_hooks = KnownHooksRegistry()
90
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
91
known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
92
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
95
def known_hooks_key_to_object((module_name, member_name)):
96
"""Convert a known_hooks key to a object.
98
:param key: A tuple (module_name, member_name) as found in the keys of
99
the known_hooks registry.
100
:return: The object this specifies.
102
return pyutils.get_named_object(module_name, member_name)
105
@symbol_versioning.deprecated_function(symbol_versioning.deprecated_in((2, 3)))
106
def known_hooks_key_to_parent_and_attribute(key):
107
"""See KnownHooksRegistry.key_to_parent_and_attribute."""
108
return known_hooks.key_to_parent_and_attribute(key)
112
"""A dictionary mapping hook name to a list of callables.
114
e.g. ['FOO'] Is the list of items to be called when the
115
FOO hook is triggered.
120
self._callable_names = {}
122
def create_hook(self, hook):
123
"""Create a hook which can have callbacks registered for it.
125
:param hook: The hook to create. An object meeting the protocol of
126
bzrlib.hooks.HookPoint. It's name is used as the key for future
129
if hook.name in self:
130
raise errors.DuplicateKey(hook.name)
131
self[hook.name] = hook
134
"""Generate the documentation for this Hooks instance.
136
This introspects all the individual hooks and returns their docs as well.
138
hook_names = sorted(self.keys())
140
name = self.__class__.__name__
141
hook_docs.append(name)
142
hook_docs.append("-"*len(name))
144
for hook_name in hook_names:
145
hook = self[hook_name]
147
hook_docs.append(hook.docs())
148
except AttributeError:
151
strings.append(hook_name)
152
strings.append("~" * len(hook_name))
154
strings.append("An old-style hook. For documentation see the __init__ "
155
"method of '%s'\n" % (name,))
156
hook_docs.extend(strings)
157
return "\n".join(hook_docs)
159
def get_hook_name(self, a_callable):
160
"""Get the name for a_callable for UI display.
162
If no name has been registered, the string 'No hook name' is returned.
163
We use a fixed string rather than repr or the callables module because
164
the code names are rarely meaningful for end users and this is not
165
intended for debugging.
167
return self._callable_names.get(a_callable, "No hook name")
169
def install_named_hook(self, hook_name, a_callable, name):
170
"""Install a_callable in to the hook hook_name, and label it name.
172
:param hook_name: A hook name. See the __init__ method of BranchHooks
173
for the complete list of hooks.
174
:param a_callable: The callable to be invoked when the hook triggers.
175
The exact signature will depend on the hook - see the __init__
176
method of BranchHooks for details on each hook.
177
:param name: A name to associate a_callable with, to show users what is
181
hook = self[hook_name]
183
raise errors.UnknownHook(self.__class__.__name__, hook_name)
185
# list hooks, old-style, not yet deprecated but less useful.
186
hook.append(a_callable)
187
except AttributeError:
188
hook.hook(a_callable, name)
190
self.name_hook(a_callable, name)
192
def name_hook(self, a_callable, name):
193
"""Associate name with a_callable to show users what is running."""
194
self._callable_names[a_callable] = name
197
class HookPoint(object):
198
"""A single hook that clients can register to be called back when it fires.
200
:ivar name: The name of the hook.
201
:ivar doc: The docs for using the hook.
202
:ivar introduced: A version tuple specifying what version the hook was
203
introduced in. None indicates an unknown version.
204
:ivar deprecated: A version tuple specifying what version the hook was
205
deprecated or superseded in. None indicates that the hook is not
206
superseded or deprecated. If the hook is superseded then the doc
207
should describe the recommended replacement hook to register for.
210
def __init__(self, name, doc, introduced, deprecated):
211
"""Create a HookPoint.
213
:param name: The name of the hook, for clients to use when registering.
214
:param doc: The docs for the hook.
215
:param introduced: When the hook was introduced (e.g. (0, 15)).
216
:param deprecated: When the hook was deprecated, None for
221
self.introduced = introduced
222
self.deprecated = deprecated
224
self._callback_names = {}
227
"""Generate the documentation for this HookPoint.
229
:return: A string terminated in \n.
232
strings.append(self.name)
233
strings.append('~'*len(self.name))
236
introduced_string = _format_version_tuple(self.introduced)
238
introduced_string = 'unknown'
239
strings.append('Introduced in: %s' % introduced_string)
241
deprecated_string = _format_version_tuple(self.deprecated)
242
strings.append('Deprecated in: %s' % deprecated_string)
244
strings.extend(textwrap.wrap(self.__doc__,
245
break_long_words=False))
247
return '\n'.join(strings)
249
def __eq__(self, other):
250
return (type(other) == type(self) and
251
other.__dict__ == self.__dict__)
253
def hook(self, callback, callback_label):
254
"""Register a callback to be called when this HookPoint fires.
256
:param callback: The callable to use when this HookPoint fires.
257
:param callback_label: A label to show in the UI while this callback is
260
self._callbacks.append(callback)
261
if callback_label is not None:
262
self._callback_names[callback] = callback_label
265
return iter(self._callbacks)
268
return len(self._callbacks)
272
strings.append("<%s(" % type(self).__name__)
273
strings.append(self.name)
274
strings.append("), callbacks=[")
275
for callback in self._callbacks:
276
strings.append(repr(callback))
278
strings.append(self._callback_names[callback])
280
if len(self._callbacks) == 1:
283
return ''.join(strings)
294
A hook of type *xxx* of class *yyy* needs to be registered using::
296
yyy.hooks.install_named_hook("xxx", ...)
298
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
300
The class that contains each hook is given before the hooks it supplies. For
301
instance, BranchHooks as the class is the hooks class for
302
`bzrlib.branch.Branch.hooks`.
304
Each description also indicates whether the hook runs on the client (the
305
machine where bzr was invoked) or the server (the machine addressed by
306
the branch URL). These may be, but are not necessarily, the same machine.
308
Plugins (including hooks) are run on the server if all of these is true:
310
* The connection is via a smart server (accessed with a URL starting with
311
"bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
312
URL when a smart server is available via HTTP).
314
* The hook is either server specific or part of general infrastructure rather
315
than client specific code (such as commit).
319
def hooks_help_text(topic):
320
segments = [_help_prefix]
321
for hook_key in sorted(known_hooks.keys()):
322
hooks = known_hooks_key_to_object(hook_key)
323
segments.append(hooks.docs())
324
return '\n'.join(segments)
added
removed
bzrlib/hooks.py
