/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: Martin Pool
  • Date: 2009-03-17 02:18:12 UTC
  • mto: This revision was merged to the branch mainline in revision 4189.
  • Revision ID: mbp@sourcefrog.net-20090317021812-h7big9h995jkh4as
Remove obsolete install_hook tests

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/hooks.py
 
1
# Copyright (C) 2007, 2008 Canonical Ltd
 
2
#
 
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.
 
7
#
 
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.
 
12
#
 
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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
16
 
 
17
 
 
18
"""Support for plugin hooking logic."""
 
19
from bzrlib import registry
 
20
from bzrlib.lazy_import import lazy_import
 
21
from bzrlib.symbol_versioning import deprecated_method
 
22
lazy_import(globals(), """
 
23
import textwrap
 
24
 
 
25
from bzrlib import (
 
26
        _format_version_tuple,
 
27
        errors,
 
28
        )
 
29
from bzrlib.help_topics import help_as_plain_text
 
30
""")
 
31
 
 
32
 
 
33
known_hooks = registry.Registry()
 
34
known_hooks.register_lazy(('bzrlib.branch', 'Branch.hooks'), 'bzrlib.branch',
 
35
    'BranchHooks')
 
36
known_hooks.register_lazy(('bzrlib.commands', 'Command.hooks'),
 
37
    'bzrlib.commands', 'CommandHooks')
 
38
known_hooks.register_lazy(('bzrlib.lock', 'Lock.hooks'), 'bzrlib.lock',
 
39
    'LockHooks')
 
40
known_hooks.register_lazy(('bzrlib.mutabletree', 'MutableTree.hooks'),
 
41
    'bzrlib.mutabletree', 'MutableTreeHooks')
 
42
known_hooks.register_lazy(('bzrlib.smart.client', '_SmartClient.hooks'),
 
43
    'bzrlib.smart.client', 'SmartClientHooks')
 
44
known_hooks.register_lazy(('bzrlib.smart.server', 'SmartTCPServer.hooks'),
 
45
    'bzrlib.smart.server', 'SmartServerHooks')
 
46
 
 
47
 
 
48
def known_hooks_key_to_object((module_name, member_name)):
 
49
    """Convert a known_hooks key to a object.
 
50
 
 
51
    :param key: A tuple (module_name, member_name) as found in the keys of
 
52
        the known_hooks registry.
 
53
    :return: The object this specifies.
 
54
    """
 
55
    return registry._LazyObjectGetter(module_name, member_name).get_obj()
 
56
 
 
57
 
 
58
def known_hooks_key_to_parent_and_attribute((module_name, member_name)):
 
59
    """Convert a known_hooks key to a object.
 
60
 
 
61
    :param key: A tuple (module_name, member_name) as found in the keys of
 
62
        the known_hooks registry.
 
63
    :return: The object this specifies.
 
64
    """
 
65
    member_list = member_name.rsplit('.', 1)
 
66
    if len(member_list) == 2:
 
67
        parent_name, attribute = member_list
 
68
    else:
 
69
        parent_name = None
 
70
        attribute = member_name
 
71
    parent = known_hooks_key_to_object((module_name, parent_name))
 
72
    return parent, attribute
 
73
 
 
74
 
 
75
class Hooks(dict):
 
76
    """A dictionary mapping hook name to a list of callables.
 
77
 
 
78
    e.g. ['FOO'] Is the list of items to be called when the
 
79
    FOO hook is triggered.
 
80
    """
 
81
 
 
82
    def __init__(self):
 
83
        dict.__init__(self)
 
84
        self._callable_names = {}
 
85
 
 
86
    def create_hook(self, hook):
 
87
        """Create a hook which can have callbacks registered for it.
 
88
 
 
89
        :param hook: The hook to create. An object meeting the protocol of
 
90
            bzrlib.hooks.HookPoint. It's name is used as the key for future
 
91
            lookups.
 
92
        """
 
93
        if hook.name in self:
 
94
            raise errors.DuplicateKey(hook.name)
 
95
        self[hook.name] = hook
 
96
 
 
97
    def docs(self):
 
98
        """Generate the documentation for this Hooks instance.
 
99
 
 
100
        This introspects all the individual hooks and returns their docs as well.
 
101
        """
 
102
        hook_names = sorted(self.keys())
 
103
        hook_docs = []
 
104
        name = self.__class__.__name__
 
105
        hook_docs.append(name)
 
106
        hook_docs.append("-"*len(name))
 
107
        hook_docs.append("")
 
108
        for hook_name in hook_names:
 
109
            hook = self[hook_name]
 
110
            try:
 
111
                hook_docs.append(hook.docs())
 
112
            except AttributeError:
 
113
                # legacy hook
 
114
                strings = []
 
115
                strings.append(hook_name)
 
116
                strings.append("~" * len(hook_name))
 
117
                strings.append("")
 
118
                strings.append("An old-style hook. For documentation see the __init__ "
 
119
                    "method of '%s'\n" % (name,))
 
120
                hook_docs.extend(strings)
 
121
        return "\n".join(hook_docs)
 
122
 
 
123
    def get_hook_name(self, a_callable):
 
124
        """Get the name for a_callable for UI display.
 
125
 
 
126
        If no name has been registered, the string 'No hook name' is returned.
 
127
        We use a fixed string rather than repr or the callables module because
 
128
        the code names are rarely meaningful for end users and this is not
 
129
        intended for debugging.
 
130
        """
 
131
        return self._callable_names.get(a_callable, "No hook name")
 
132
 
 
133
    def install_named_hook(self, hook_name, a_callable, name):
 
134
        """Install a_callable in to the hook hook_name, and label it name.
 
135
 
 
136
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
137
            for the complete list of hooks.
 
138
        :param a_callable: The callable to be invoked when the hook triggers.
 
139
            The exact signature will depend on the hook - see the __init__
 
140
            method of BranchHooks for details on each hook.
 
141
        :param name: A name to associate a_callable with, to show users what is
 
142
            running.
 
143
        """
 
144
        try:
 
145
            hook = self[hook_name]
 
146
        except KeyError:
 
147
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
 
148
        try:
 
149
            # list hooks, old-style, not yet deprecated but less useful.
 
150
            hook.append(a_callable)
 
151
        except AttributeError:
 
152
            hook.hook(a_callable, name)
 
153
        if name is not None:
 
154
            self.name_hook(a_callable, name)
 
155
 
 
156
    def name_hook(self, a_callable, name):
 
157
        """Associate name with a_callable to show users what is running."""
 
158
        self._callable_names[a_callable] = name
 
159
 
 
160
 
 
161
class HookPoint(object):
 
162
    """A single hook that clients can register to be called back when it fires.
 
163
 
 
164
    :ivar name: The name of the hook.
 
165
    :ivar introduced: A version tuple specifying what version the hook was
 
166
        introduced in. None indicates an unknown version.
 
167
    :ivar deprecated: A version tuple specifying what version the hook was
 
168
        deprecated or superceded in. None indicates that the hook is not
 
169
        superceded or deprecated. If the hook is superceded then the doc
 
170
        should describe the recommended replacement hook to register for.
 
171
    :ivar doc: The docs for using the hook.
 
172
    """
 
173
 
 
174
    def __init__(self, name, doc, introduced, deprecated):
 
175
        """Create a HookPoint.
 
176
 
 
177
        :param name: The name of the hook, for clients to use when registering.
 
178
        :param doc: The docs for the hook.
 
179
        :param introduced: When the hook was introduced (e.g. (0, 15)).
 
180
        :param deprecated: When the hook was deprecated, None for
 
181
            not-deprecated.
 
182
        """
 
183
        self.name = name
 
184
        self.__doc__ = doc
 
185
        self.introduced = introduced
 
186
        self.deprecated = deprecated
 
187
        self._callbacks = []
 
188
        self._callback_names = {}
 
189
 
 
190
    def docs(self):
 
191
        """Generate the documentation for this HookPoint.
 
192
 
 
193
        :return: A string terminated in \n.
 
194
        """
 
195
        strings = []
 
196
        strings.append(self.name)
 
197
        strings.append('~'*len(self.name))
 
198
        strings.append('')
 
199
        if self.introduced:
 
200
            introduced_string = _format_version_tuple(self.introduced)
 
201
        else:
 
202
            introduced_string = 'unknown'
 
203
        strings.append('Introduced in: %s' % introduced_string)
 
204
        if self.deprecated:
 
205
            deprecated_string = _format_version_tuple(self.deprecated)
 
206
        else:
 
207
            deprecated_string = 'Not deprecated'
 
208
        strings.append('Deprecated in: %s' % deprecated_string)
 
209
        strings.append('')
 
210
        strings.extend(textwrap.wrap(self.__doc__))
 
211
        strings.append('')
 
212
        return '\n'.join(strings)
 
213
 
 
214
    def __eq__(self, other):
 
215
        return (type(other) == type(self) and 
 
216
            other.__dict__ == self.__dict__)
 
217
 
 
218
    def hook(self, callback, callback_label):
 
219
        """Register a callback to be called when this HookPoint fires.
 
220
 
 
221
        :param callback: The callable to use when this HookPoint fires.
 
222
        :param callback_label: A label to show in the UI while this callback is
 
223
            processing.
 
224
        """
 
225
        self._callbacks.append(callback)
 
226
        if callback_label is not None:
 
227
            self._callback_names[callback] = callback_label
 
228
 
 
229
    def __iter__(self):
 
230
        return iter(self._callbacks)
 
231
 
 
232
    def __len__(self):
 
233
        return len(self._callbacks)
 
234
 
 
235
    def __repr__(self):
 
236
        strings = []
 
237
        strings.append("<%s(" % type(self).__name__)
 
238
        strings.append(self.name)
 
239
        strings.append("), callbacks=[")
 
240
        for callback in self._callbacks:
 
241
            strings.append(repr(callback))
 
242
            strings.append("(")
 
243
            strings.append(self._callback_names[callback])
 
244
            strings.append("),")
 
245
        if len(self._callbacks) == 1:
 
246
            strings[-1] = ")"
 
247
        strings.append("]>")
 
248
        return ''.join(strings)
 
249
 
 
250
 
 
251
_help_prefix = \
 
252
"""
 
253
Hooks
 
254
=====
 
255
 
 
256
Introduction
 
257
------------
 
258
 
 
259
A hook of type *xxx* of class *yyy* needs to be registered using::
 
260
 
 
261
  yyy.hooks.install_named_hook("xxx", ...)
 
262
 
 
263
See `Using hooks`_ in the User Guide for examples.
 
264
 
 
265
.. _Using hooks: ../user-guide/index.html#using-hooks
 
266
 
 
267
The class that contains each hook is given before the hooks it supplies. For
 
268
instance, BranchHooks as the class is the hooks class for
 
269
`bzrlib.branch.Branch.hooks`.
 
270
 
 
271
Each description also indicates whether the hook runs on the client (the
 
272
machine where bzr was invoked) or the server (the machine addressed by
 
273
the branch URL).  These may be, but are not necessarily, the same machine.
 
274
 
 
275
Plugins (including hooks) are run on the server if all of these is true:
 
276
 
 
277
  * The connection is via a smart server (accessed with a URL starting with
 
278
    "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
 
279
    URL when a smart server is available via HTTP).
 
280
 
 
281
  * The hook is either server specific or part of general infrastructure rather
 
282
    than client specific code (such as commit).
 
283
 
 
284
"""
 
285
 
 
286
def hooks_help_text(topic):
 
287
    segments = [_help_prefix]
 
288
    for hook_key in sorted(known_hooks.keys()):
 
289
        hooks = known_hooks_key_to_object(hook_key)
 
290
        segments.append(hooks.docs())
 
291
    return '\n'.join(segments)