← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Martin Pool
  • Date: 2009-03-12 07:26:03 UTC
  • mto: This revision was merged to the branch mainline in revision 4144.
  • Revision ID: mbp@sourcefrog.net-20090312072603-2encofaehyg1iplv
Transport activity now shows scheme and direction

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/hooks.py
1
 
# Copyright (C) 2007-2010 Canonical Ltd
 
1
# Copyright (C) 2007, 2008 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
12
12
#
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
16
16
 
17
17
 
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(), """
22
22
import textwrap
23
23
 
25
25
        _format_version_tuple,
26
26
        errors,
27
27
        )
28
 
from bzrlib.help_topics import help_as_plain_text
29
28
""")
30
29
 
31
30
 
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',
38
 
    'BranchHooks')
39
 
known_hooks.register_lazy(('bzrlib.bzrdir', 'BzrDir.hooks'), 'bzrlib.bzrdir',
40
 
    'BzrDirHooks')
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',
46
 
    'LockHooks')
47
 
known_hooks.register_lazy(('bzrlib.merge', 'Merger.hooks'), 'bzrlib.merge',
48
 
    'MergeHooks')
49
 
known_hooks.register_lazy(('bzrlib.msgeditor', 'hooks'), 'bzrlib.msgeditor',
50
 
    'MessageEditorHooks')
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')
63
 
 
64
 
 
65
 
def known_hooks_key_to_object((module_name, member_name)):
66
 
    """Convert a known_hooks key to a object.
67
 
 
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.
71
 
    """
72
 
    return registry._LazyObjectGetter(module_name, member_name).get_obj()
73
 
 
74
 
 
75
 
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
76
 
    """Convert a known_hooks key to a object.
77
 
 
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.
81
 
    """
82
 
    member_list = member_name.rsplit('.', 1)
83
 
    if len(member_list) == 2:
84
 
        parent_name, attribute = member_list
85
 
    else:
86
 
        parent_name = None
87
 
        attribute = member_name
88
 
    parent = known_hooks_key_to_object((module_name, parent_name))
89
 
    return parent, attribute
90
 
 
91
 
 
92
31
class Hooks(dict):
93
32
    """A dictionary mapping hook name to a list of callables.
94
33
 
120
59
        hook_docs = []
121
60
        name = self.__class__.__name__
122
61
        hook_docs.append(name)
123
 
        hook_docs.append("-"*len(name))
 
62
        hook_docs.append("="*len(name))
124
63
        hook_docs.append("")
125
64
        for hook_name in hook_names:
126
65
            hook = self[hook_name]
130
69
                # legacy hook
131
70
                strings = []
132
71
                strings.append(hook_name)
133
 
                strings.append("~" * len(hook_name))
 
72
                strings.append("-" * len(hook_name))
134
73
                strings.append("")
135
74
                strings.append("An old-style hook. For documentation see the __init__ "
136
75
                    "method of '%s'\n" % (name,))
147
86
        """
148
87
        return self._callable_names.get(a_callable, "No hook name")
149
88
 
 
89
    @deprecated_method(one_five)
 
90
    def install_hook(self, hook_name, a_callable):
 
91
        """Install a_callable in to the hook hook_name.
 
92
 
 
93
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
94
            for the complete list of hooks.
 
95
        :param a_callable: The callable to be invoked when the hook triggers.
 
96
            The exact signature will depend on the hook - see the __init__
 
97
            method of BranchHooks for details on each hook.
 
98
        """
 
99
        self.install_named_hook(hook_name, a_callable, None)
 
100
 
150
101
    def install_named_hook(self, hook_name, a_callable, name):
151
102
        """Install a_callable in to the hook hook_name, and label it name.
152
103
 
182
133
    :ivar introduced: A version tuple specifying what version the hook was
183
134
        introduced in. None indicates an unknown version.
184
135
    :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
 
136
        deprecated or superceded in. None indicates that the hook is not
 
137
        superceded or deprecated. If the hook is superceded then the doc
187
138
        should describe the recommended replacement hook to register for.
188
139
    :ivar doc: The docs for using the hook.
189
140
    """
211
162
        """
212
163
        strings = []
213
164
        strings.append(self.name)
214
 
        strings.append('~'*len(self.name))
 
165
        strings.append('-'*len(self.name))
215
166
        strings.append('')
216
167
        if self.introduced:
217
168
            introduced_string = _format_version_tuple(self.introduced)
220
171
        strings.append('Introduced in: %s' % introduced_string)
221
172
        if self.deprecated:
222
173
            deprecated_string = _format_version_tuple(self.deprecated)
223
 
            strings.append('Deprecated in: %s' % deprecated_string)
 
174
        else:
 
175
            deprecated_string = 'Not deprecated'
 
176
        strings.append('Deprecated in: %s' % deprecated_string)
224
177
        strings.append('')
225
 
        strings.extend(textwrap.wrap(self.__doc__,
226
 
            break_long_words=False))
 
178
        strings.extend(textwrap.wrap(self.__doc__))
227
179
        strings.append('')
228
180
        return '\n'.join(strings)
229
181
 
230
 
    def __eq__(self, other):
231
 
        return (type(other) == type(self) and 
232
 
            other.__dict__ == self.__dict__)
233
 
 
234
182
    def hook(self, callback, callback_label):
235
183
        """Register a callback to be called when this HookPoint fires.
236
184
 
239
187
            processing.
240
188
        """
241
189
        self._callbacks.append(callback)
242
 
        if callback_label is not None:
243
 
            self._callback_names[callback] = callback_label
 
190
        self._callback_names[callback] = callback_label
244
191
 
245
192
    def __iter__(self):
246
193
        return iter(self._callbacks)
247
194
 
248
 
    def __len__(self):
249
 
        return len(self._callbacks)
250
 
 
251
195
    def __repr__(self):
252
196
        strings = []
253
197
        strings.append("<%s(" % type(self).__name__)
262
206
            strings[-1] = ")"
263
207
        strings.append("]>")
264
208
        return ''.join(strings)
265
 
 
266
 
 
267
 
_help_prefix = \
268
 
"""
269
 
Hooks
270
 
=====
271
 
 
272
 
Introduction
273
 
------------
274
 
 
275
 
A hook of type *xxx* of class *yyy* needs to be registered using::
276
 
 
277
 
  yyy.hooks.install_named_hook("xxx", ...)
278
 
 
279
 
See `Using hooks`_ in the User Guide for examples.
280
 
 
281
 
.. _Using hooks: ../user-guide/hooks.html
282
 
 
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`.
286
 
 
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.
290
 
 
291
 
Plugins (including hooks) are run on the server if all of these is true:
292
 
 
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).
296
 
 
297
 
  * The hook is either server specific or part of general infrastructure rather
298
 
    than client specific code (such as commit).
299
 
 
300
 
"""
301
 
 
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)