/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: Andrew Bennetts
  • Date: 2009-10-21 11:13:40 UTC
  • mto: This revision was merged to the branch mainline in revision 4762.
  • Revision ID: andrew.bennetts@canonical.com-20091021111340-w7x4d5yf83qwjncc
Add test that WSGI glue allows request handlers to access paths above that request's. backing transport, so long as it is within the WSGI app's backing transport.

Show diffs side-by-side

added added

removed removed

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