/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Robert Collins
  • Date: 2009-03-11 20:59:20 UTC
  • mto: This revision was merged to the branch mainline in revision 4116.
  • Revision ID: robertc@robertcollins.net-20090311205920-w7q5yrxy8prc3jjm
Turn test_coding_style into a KnownFailure until it gets fixed as per the list.

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
 
118
57
        """
119
58
        hook_names = sorted(self.keys())
120
59
        hook_docs = []
121
 
        name = self.__class__.__name__
122
 
        hook_docs.append(name)
123
 
        hook_docs.append("-"*len(name))
124
 
        hook_docs.append("")
125
60
        for hook_name in hook_names:
126
61
            hook = self[hook_name]
127
62
            try:
130
65
                # legacy hook
131
66
                strings = []
132
67
                strings.append(hook_name)
133
 
                strings.append("~" * len(hook_name))
 
68
                strings.append("-" * len(hook_name))
134
69
                strings.append("")
135
70
                strings.append("An old-style hook. For documentation see the __init__ "
136
 
                    "method of '%s'\n" % (name,))
 
71
                    "method of '%s'\n" % (self.__class__.__name__,))
137
72
                hook_docs.extend(strings)
138
73
        return "\n".join(hook_docs)
139
74
 
147
82
        """
148
83
        return self._callable_names.get(a_callable, "No hook name")
149
84
 
 
85
    @deprecated_method(one_five)
 
86
    def install_hook(self, hook_name, a_callable):
 
87
        """Install a_callable in to the hook hook_name.
 
88
 
 
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.
 
94
        """
 
95
        self.install_named_hook(hook_name, a_callable, None)
 
96
 
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.
152
99
 
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.
189
136
    """
211
158
        """
212
159
        strings = []
213
160
        strings.append(self.name)
214
 
        strings.append('~'*len(self.name))
 
161
        strings.append('-'*len(self.name))
215
162
        strings.append('')
216
163
        if self.introduced:
217
164
            introduced_string = _format_version_tuple(self.introduced)
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)
 
170
        else:
 
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)
229
177
 
230
 
    def __eq__(self, other):
231
 
        return (type(other) == type(self) and 
232
 
            other.__dict__ == self.__dict__)
233
 
 
234
178
    def hook(self, callback, callback_label):
235
179
        """Register a callback to be called when this HookPoint fires.
236
180
 
239
183
            processing.
240
184
        """
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
244
187
 
245
188
    def __iter__(self):
246
189
        return iter(self._callbacks)
247
190
 
248
 
    def __len__(self):
249
 
        return len(self._callbacks)
250
 
 
251
191
    def __repr__(self):
252
192
        strings = []
253
193
        strings.append("<%s(" % type(self).__name__)
262
202
            strings[-1] = ")"
263
203
        strings.append("]>")
264
204
        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)