~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Aaron Bentley
  • Date: 2007-06-11 14:59:52 UTC
  • mto: (2520.5.2 bzr.mpbundle)
  • mto: This revision was merged to the branch mainline in revision 2631.
  • Revision ID: abentley@panoramicfeedback.com-20070611145952-cwt4480gphdhen6l
Get installation started

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2007-2011 Canonical Ltd
 
1
# Copyright (C) 2007 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
"""Support for plugin hooking logic."""
18
 
 
19
 
from __future__ import absolute_import
20
 
 
21
 
from bzrlib import (
22
 
    registry,
23
 
    symbol_versioning,
24
 
    )
25
19
from bzrlib.lazy_import import lazy_import
26
20
lazy_import(globals(), """
27
 
import textwrap
28
 
 
29
21
from bzrlib import (
30
 
    _format_version_tuple,
31
 
    errors,
32
 
    pyutils,
33
 
    )
34
 
from bzrlib.i18n import gettext
 
22
        errors,
 
23
        )
35
24
""")
36
25
 
37
26
 
38
 
class KnownHooksRegistry(registry.Registry):
39
 
    # known_hooks registry contains
40
 
    # tuple of (module, member name) which is the hook point
41
 
    # module where the specific hooks are defined
42
 
    # callable to get the empty specific Hooks for that attribute
43
 
 
44
 
    def register_lazy_hook(self, hook_module_name, hook_member_name,
45
 
            hook_factory_member_name):
46
 
        self.register_lazy((hook_module_name, hook_member_name),
47
 
            hook_module_name, hook_factory_member_name)
48
 
 
49
 
    def iter_parent_objects(self):
50
 
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
51
 
        hook, where 'parent_object' is the object that holds the hook
52
 
        instance.
53
 
 
54
 
        This is useful for resetting/restoring all the hooks to a known state,
55
 
        as is done in bzrlib.tests.TestCase._clear_hooks.
56
 
        """
57
 
        for key in self.keys():
58
 
            yield key, self.key_to_parent_and_attribute(key)
59
 
 
60
 
    def key_to_parent_and_attribute(self, (module_name, member_name)):
61
 
        """Convert a known_hooks key to a (parent_obj, attr) pair.
62
 
 
63
 
        :param key: A tuple (module_name, member_name) as found in the keys of
64
 
            the known_hooks registry.
65
 
        :return: The parent_object of the hook and the name of the attribute on
66
 
            that parent object where the hook is kept.
67
 
        """
68
 
        parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
69
 
            member_name)
70
 
        return pyutils.get_named_object(parent_mod, parent_member), attr
71
 
 
72
 
 
73
 
_builtin_known_hooks = (
74
 
    ('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
75
 
    ('bzrlib.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
76
 
    ('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
77
 
    ('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
78
 
    ('bzrlib.info', 'hooks', 'InfoHooks'),
79
 
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
80
 
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
81
 
    ('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
82
 
    ('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
83
 
    ('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
84
 
    ('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
85
 
    ('bzrlib.status', 'hooks', 'StatusHooks'),
86
 
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
87
 
        'RioVersionInfoBuilderHooks'),
88
 
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
89
 
        'MergeDirectiveHooks'),
90
 
    )
91
 
 
92
 
known_hooks = KnownHooksRegistry()
93
 
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
94
 
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
95
 
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
96
 
 
97
 
 
98
 
def known_hooks_key_to_object((module_name, member_name)):
99
 
    """Convert a known_hooks key to a object.
100
 
 
101
 
    :param key: A tuple (module_name, member_name) as found in the keys of
102
 
        the known_hooks registry.
103
 
    :return: The object this specifies.
104
 
    """
105
 
    return pyutils.get_named_object(module_name, member_name)
106
 
 
107
 
 
108
 
@symbol_versioning.deprecated_function(symbol_versioning.deprecated_in((2, 3)))
109
 
def known_hooks_key_to_parent_and_attribute(key):
110
 
    """See KnownHooksRegistry.key_to_parent_and_attribute."""
111
 
    return known_hooks.key_to_parent_and_attribute(key)
112
 
 
113
 
 
114
27
class Hooks(dict):
115
28
    """A dictionary mapping hook name to a list of callables.
116
 
 
 
29
    
117
30
    e.g. ['FOO'] Is the list of items to be called when the
118
31
    FOO hook is triggered.
119
32
    """
120
33
 
121
 
    def __init__(self, module=None, member_name=None):
122
 
        """Create a new hooks dictionary.
123
 
 
124
 
        :param module: The module from which this hooks dictionary should be loaded
125
 
            (used for lazy hooks)
126
 
        :param member_name: Name under which this hooks dictionary should be loaded.
127
 
            (used for lazy hooks)
128
 
        """
129
 
        dict.__init__(self)
130
 
        self._callable_names = {}
131
 
        self._lazy_callable_names = {}
132
 
        self._module = module
133
 
        self._member_name = member_name
134
 
 
135
 
    def add_hook(self, name, doc, introduced, deprecated=None):
136
 
        """Add a hook point to this dictionary.
137
 
 
138
 
        :param name: The name of the hook, for clients to use when registering.
139
 
        :param doc: The docs for the hook.
140
 
        :param introduced: When the hook was introduced (e.g. (0, 15)).
141
 
        :param deprecated: When the hook was deprecated, None for
142
 
            not-deprecated.
143
 
        """
144
 
        if name in self:
145
 
            raise errors.DuplicateKey(name)
146
 
        if self._module:
147
 
            callbacks = _lazy_hooks.setdefault(
148
 
                (self._module, self._member_name, name), [])
149
 
        else:
150
 
            callbacks = None
151
 
        hookpoint = HookPoint(name=name, doc=doc, introduced=introduced,
152
 
                              deprecated=deprecated, callbacks=callbacks)
153
 
        self[name] = hookpoint
154
 
 
155
 
    @symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4)))
156
 
    def create_hook(self, hook):
157
 
        """Create a hook which can have callbacks registered for it.
158
 
 
159
 
        :param hook: The hook to create. An object meeting the protocol of
160
 
            bzrlib.hooks.HookPoint. It's name is used as the key for future
161
 
            lookups.
162
 
        """
163
 
        if hook.name in self:
164
 
            raise errors.DuplicateKey(hook.name)
165
 
        self[hook.name] = hook
166
 
 
167
 
    def docs(self):
168
 
        """Generate the documentation for this Hooks instance.
169
 
 
170
 
        This introspects all the individual hooks and returns their docs as well.
171
 
        """
172
 
        hook_names = sorted(self.keys())
173
 
        hook_docs = []
174
 
        name = self.__class__.__name__
175
 
        hook_docs.append(name)
176
 
        hook_docs.append("-"*len(name))
177
 
        hook_docs.append("")
178
 
        for hook_name in hook_names:
179
 
            hook = self[hook_name]
180
 
            try:
181
 
                hook_docs.append(hook.docs())
182
 
            except AttributeError:
183
 
                # legacy hook
184
 
                strings = []
185
 
                strings.append(hook_name)
186
 
                strings.append("~" * len(hook_name))
187
 
                strings.append("")
188
 
                strings.append("An old-style hook. For documentation see the __init__ "
189
 
                    "method of '%s'\n" % (name,))
190
 
                hook_docs.extend(strings)
191
 
        return "\n".join(hook_docs)
192
 
 
193
 
    def get_hook_name(self, a_callable):
194
 
        """Get the name for a_callable for UI display.
195
 
 
196
 
        If no name has been registered, the string 'No hook name' is returned.
197
 
        We use a fixed string rather than repr or the callables module because
198
 
        the code names are rarely meaningful for end users and this is not
199
 
        intended for debugging.
200
 
        """
201
 
        name = self._callable_names.get(a_callable, None)
202
 
        if name is None and a_callable is not None:
203
 
            name = self._lazy_callable_names.get((a_callable.__module__,
204
 
                                                  a_callable.__name__),
205
 
                                                 None)
206
 
        if name is None:
207
 
            return 'No hook name'
208
 
        return name
209
 
 
210
 
 
211
 
    def install_named_hook_lazy(self, hook_name, callable_module,
212
 
        callable_member, name):
213
 
        """Install a_callable in to the hook hook_name lazily, and label it.
214
 
 
215
 
        :param hook_name: A hook name. See the __init__ method for the complete
216
 
            list of hooks.
217
 
        :param callable_module: Name of the module in which the callable is
218
 
            present.
219
 
        :param callable_member: Member name of the callable.
220
 
        :param name: A name to associate the callable with, to show users what
221
 
            is running.
222
 
        """
223
 
        try:
224
 
            hook = self[hook_name]
225
 
        except KeyError:
226
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
227
 
        try:
228
 
            hook_lazy = getattr(hook, "hook_lazy")
229
 
        except AttributeError:
230
 
            raise errors.UnsupportedOperation(self.install_named_hook_lazy,
231
 
                self)
232
 
        else:
233
 
            hook_lazy(callable_module, callable_member, name)
234
 
        if name is not None:
235
 
            self.name_hook_lazy(callable_module, callable_member, name)
236
 
 
237
 
    def install_named_hook(self, hook_name, a_callable, name):
238
 
        """Install a_callable in to the hook hook_name, and label it name.
239
 
 
240
 
        :param hook_name: A hook name. See the __init__ method for the complete
241
 
            list of hooks.
 
34
    def install_hook(self, hook_name, a_callable):
 
35
        """Install a_callable in to the hook hook_name.
 
36
 
 
37
        :param hook_name: A hook name. See the __init__ method of BranchHooks
 
38
            for the complete list of hooks.
242
39
        :param a_callable: The callable to be invoked when the hook triggers.
243
 
            The exact signature will depend on the hook - see the __init__
244
 
            method for details on each hook.
245
 
        :param name: A name to associate a_callable with, to show users what is
246
 
            running.
247
 
        """
248
 
        try:
249
 
            hook = self[hook_name]
250
 
        except KeyError:
251
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
252
 
        try:
253
 
            # list hooks, old-style, not yet deprecated but less useful.
254
 
            hook.append(a_callable)
255
 
        except AttributeError:
256
 
            hook.hook(a_callable, name)
257
 
        if name is not None:
258
 
            self.name_hook(a_callable, name)
259
 
 
260
 
    def uninstall_named_hook(self, hook_name, label):
261
 
        """Uninstall named hooks.
262
 
 
263
 
        :param hook_name: Hook point name
264
 
        :param label: Label of the callable to uninstall
265
 
        """
266
 
        try:
267
 
            hook = self[hook_name]
268
 
        except KeyError:
269
 
            raise errors.UnknownHook(self.__class__.__name__, hook_name)
270
 
        try:
271
 
            uninstall = getattr(hook, "uninstall")
272
 
        except AttributeError:
273
 
            raise errors.UnsupportedOperation(self.uninstall_named_hook, self)
274
 
        else:
275
 
            uninstall(label)
276
 
 
277
 
    def name_hook(self, a_callable, name):
278
 
        """Associate name with a_callable to show users what is running."""
279
 
        self._callable_names[a_callable] = name
280
 
 
281
 
    def name_hook_lazy(self, callable_module, callable_member, callable_name):
282
 
        self._lazy_callable_names[(callable_module, callable_member)]= \
283
 
            callable_name
284
 
 
285
 
 
286
 
class HookPoint(object):
287
 
    """A single hook that clients can register to be called back when it fires.
288
 
 
289
 
    :ivar name: The name of the hook.
290
 
    :ivar doc: The docs for using the hook.
291
 
    :ivar introduced: A version tuple specifying what version the hook was
292
 
        introduced in. None indicates an unknown version.
293
 
    :ivar deprecated: A version tuple specifying what version the hook was
294
 
        deprecated or superseded in. None indicates that the hook is not
295
 
        superseded or deprecated. If the hook is superseded then the doc
296
 
        should describe the recommended replacement hook to register for.
297
 
    """
298
 
 
299
 
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
300
 
        """Create a HookPoint.
301
 
 
302
 
        :param name: The name of the hook, for clients to use when registering.
303
 
        :param doc: The docs for the hook.
304
 
        :param introduced: When the hook was introduced (e.g. (0, 15)).
305
 
        :param deprecated: When the hook was deprecated, None for
306
 
            not-deprecated.
307
 
        """
308
 
        self.name = name
309
 
        self.__doc__ = doc
310
 
        self.introduced = introduced
311
 
        self.deprecated = deprecated
312
 
        if callbacks is None:
313
 
            self._callbacks = []
314
 
        else:
315
 
            self._callbacks = callbacks
316
 
 
317
 
    def docs(self):
318
 
        """Generate the documentation for this HookPoint.
319
 
 
320
 
        :return: A string terminated in \n.
321
 
        """
322
 
        strings = []
323
 
        strings.append(self.name)
324
 
        strings.append('~'*len(self.name))
325
 
        strings.append('')
326
 
        if self.introduced:
327
 
            introduced_string = _format_version_tuple(self.introduced)
328
 
        else:
329
 
            introduced_string = 'unknown'
330
 
        strings.append(gettext('Introduced in: %s') % introduced_string)
331
 
        if self.deprecated:
332
 
            deprecated_string = _format_version_tuple(self.deprecated)
333
 
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
334
 
        strings.append('')
335
 
        strings.extend(textwrap.wrap(self.__doc__,
336
 
            break_long_words=False))
337
 
        strings.append('')
338
 
        return '\n'.join(strings)
339
 
 
340
 
    def __eq__(self, other):
341
 
        return (type(other) == type(self) and other.__dict__ == self.__dict__)
342
 
 
343
 
    def hook_lazy(self, callback_module, callback_member, callback_label):
344
 
        """Lazily register a callback to be called when this HookPoint fires.
345
 
 
346
 
        :param callback_module: Module of the callable to use when this
347
 
            HookPoint fires.
348
 
        :param callback_member: Member name of the callback.
349
 
        :param callback_label: A label to show in the UI while this callback is
350
 
            processing.
351
 
        """
352
 
        obj_getter = registry._LazyObjectGetter(callback_module,
353
 
            callback_member)
354
 
        self._callbacks.append((obj_getter, callback_label))
355
 
 
356
 
    def hook(self, callback, callback_label):
357
 
        """Register a callback to be called when this HookPoint fires.
358
 
 
359
 
        :param callback: The callable to use when this HookPoint fires.
360
 
        :param callback_label: A label to show in the UI while this callback is
361
 
            processing.
362
 
        """
363
 
        obj_getter = registry._ObjectGetter(callback)
364
 
        self._callbacks.append((obj_getter, callback_label))
365
 
 
366
 
    def uninstall(self, label):
367
 
        """Uninstall the callback with the specified label.
368
 
 
369
 
        :param label: Label of the entry to uninstall
370
 
        """
371
 
        entries_to_remove = []
372
 
        for entry in self._callbacks:
373
 
            (entry_callback, entry_label) = entry
374
 
            if entry_label == label:
375
 
                entries_to_remove.append(entry)
376
 
        if entries_to_remove == []:
377
 
            raise KeyError("No entry with label %r" % label)
378
 
        for entry in entries_to_remove:
379
 
            self._callbacks.remove(entry)
380
 
 
381
 
    def __iter__(self):
382
 
        return (callback.get_obj() for callback, name in self._callbacks)
383
 
 
384
 
    def __len__(self):
385
 
        return len(self._callbacks)
386
 
 
387
 
    def __repr__(self):
388
 
        strings = []
389
 
        strings.append("<%s(" % type(self).__name__)
390
 
        strings.append(self.name)
391
 
        strings.append("), callbacks=[")
392
 
        callbacks = self._callbacks
393
 
        for (callback, callback_name) in callbacks:
394
 
            strings.append(repr(callback.get_obj()))
395
 
            strings.append("(")
396
 
            strings.append(callback_name)
397
 
            strings.append("),")
398
 
        if len(callbacks) == 1:
399
 
            strings[-1] = ")"
400
 
        strings.append("]>")
401
 
        return ''.join(strings)
402
 
 
403
 
 
404
 
_help_prefix = \
405
 
"""
406
 
Hooks
407
 
=====
408
 
 
409
 
Introduction
410
 
------------
411
 
 
412
 
A hook of type *xxx* of class *yyy* needs to be registered using::
413
 
 
414
 
  yyy.hooks.install_named_hook("xxx", ...)
415
 
 
416
 
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
417
 
 
418
 
The class that contains each hook is given before the hooks it supplies. For
419
 
instance, BranchHooks as the class is the hooks class for
420
 
`bzrlib.branch.Branch.hooks`.
421
 
 
422
 
Each description also indicates whether the hook runs on the client (the
423
 
machine where bzr was invoked) or the server (the machine addressed by
424
 
the branch URL).  These may be, but are not necessarily, the same machine.
425
 
 
426
 
Plugins (including hooks) are run on the server if all of these is true:
427
 
 
428
 
  * The connection is via a smart server (accessed with a URL starting with
429
 
    "bzr://", "bzr+ssh://" or "bzr+http://", or accessed via a "http://"
430
 
    URL when a smart server is available via HTTP).
431
 
 
432
 
  * The hook is either server specific or part of general infrastructure rather
433
 
    than client specific code (such as commit).
434
 
 
435
 
"""
436
 
 
437
 
def hooks_help_text(topic):
438
 
    segments = [_help_prefix]
439
 
    for hook_key in sorted(known_hooks.keys()):
440
 
        hooks = known_hooks_key_to_object(hook_key)
441
 
        segments.append(hooks.docs())
442
 
    return '\n'.join(segments)
443
 
 
444
 
 
445
 
# Lazily registered hooks. Maps (module, name, hook_name) tuples
446
 
# to lists of tuples with objectgetters and names
447
 
_lazy_hooks = {}
448
 
 
449
 
 
450
 
def install_lazy_named_hook(hookpoints_module, hookpoints_name, hook_name,
451
 
    a_callable, name):
452
 
    """Install a callable in to a hook lazily, and label it name.
453
 
 
454
 
    :param hookpoints_module: Module name of the hook points.
455
 
    :param hookpoints_name: Name of the hook points.
456
 
    :param hook_name: A hook name.
457
 
    :param callable: a callable to call for the hook.
458
 
    :param name: A name to associate a_callable with, to show users what is
459
 
        running.
460
 
    """
461
 
    key = (hookpoints_module, hookpoints_name, hook_name)
462
 
    obj_getter = registry._ObjectGetter(a_callable)
463
 
    _lazy_hooks.setdefault(key, []).append((obj_getter, name))
 
40
            The exact signature will depend on the hook - see the __init__ 
 
41
            method of BranchHooks for details on each hook.
 
42
        """
 
43
        try:
 
44
            self[hook_name].append(a_callable)
 
45
        except KeyError:
 
46
            raise errors.UnknownHook(self.__class__.__name__, hook_name)