/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

Merge bzr.dev, update to use new hooks.

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-2011 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
16
16
 
17
17
 
18
18
"""Support for plugin hooking logic."""
 
19
 
19
20
from bzrlib import (
20
 
    pyutils,
21
21
    registry,
22
22
    symbol_versioning,
23
23
    )
26
26
import textwrap
27
27
 
28
28
from bzrlib import (
29
 
        _format_version_tuple,
30
 
        errors,
31
 
        )
32
 
from bzrlib.help_topics import help_as_plain_text
 
29
    _format_version_tuple,
 
30
    errors,
 
31
    pyutils,
 
32
    )
 
33
from bzrlib.i18n import gettext
33
34
""")
34
35
 
35
36
 
70
71
 
71
72
_builtin_known_hooks = (
72
73
    ('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
73
 
    ('bzrlib.bzrdir', 'BzrDir.hooks', 'BzrDirHooks'),
 
74
    ('bzrlib.controldir', 'ControlDir.hooks', 'ControlDirHooks'),
74
75
    ('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
 
76
    ('bzrlib.config', 'ConfigHooks', '_ConfigHooks'),
75
77
    ('bzrlib.info', 'hooks', 'InfoHooks'),
76
78
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
77
79
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
116
118
    FOO hook is triggered.
117
119
    """
118
120
 
119
 
    def __init__(self):
 
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
        """
120
129
        dict.__init__(self)
121
130
        self._callable_names = {}
122
 
 
 
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)))
123
156
    def create_hook(self, hook):
124
157
        """Create a hook which can have callbacks registered for it.
125
158
 
165
198
        the code names are rarely meaningful for end users and this is not
166
199
        intended for debugging.
167
200
        """
168
 
        return self._callable_names.get(a_callable, "No hook name")
 
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)
169
236
 
170
237
    def install_named_hook(self, hook_name, a_callable, name):
171
238
        """Install a_callable in to the hook hook_name, and label it name.
172
239
 
173
 
        :param hook_name: A hook name. See the __init__ method of BranchHooks
174
 
            for the complete list of hooks.
 
240
        :param hook_name: A hook name. See the __init__ method for the complete
 
241
            list of hooks.
175
242
        :param a_callable: The callable to be invoked when the hook triggers.
176
243
            The exact signature will depend on the hook - see the __init__
177
 
            method of BranchHooks for details on each hook.
 
244
            method for details on each hook.
178
245
        :param name: A name to associate a_callable with, to show users what is
179
246
            running.
180
247
        """
190
257
        if name is not None:
191
258
            self.name_hook(a_callable, name)
192
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
 
193
277
    def name_hook(self, a_callable, name):
194
278
        """Associate name with a_callable to show users what is running."""
195
279
        self._callable_names[a_callable] = name
196
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
 
197
285
 
198
286
class HookPoint(object):
199
287
    """A single hook that clients can register to be called back when it fires.
208
296
        should describe the recommended replacement hook to register for.
209
297
    """
210
298
 
211
 
    def __init__(self, name, doc, introduced, deprecated):
 
299
    def __init__(self, name, doc, introduced, deprecated=None, callbacks=None):
212
300
        """Create a HookPoint.
213
301
 
214
302
        :param name: The name of the hook, for clients to use when registering.
221
309
        self.__doc__ = doc
222
310
        self.introduced = introduced
223
311
        self.deprecated = deprecated
224
 
        self._callbacks = []
225
 
        self._callback_names = {}
 
312
        if callbacks is None:
 
313
            self._callbacks = []
 
314
        else:
 
315
            self._callbacks = callbacks
226
316
 
227
317
    def docs(self):
228
318
        """Generate the documentation for this HookPoint.
237
327
            introduced_string = _format_version_tuple(self.introduced)
238
328
        else:
239
329
            introduced_string = 'unknown'
240
 
        strings.append('Introduced in: %s' % introduced_string)
 
330
        strings.append(gettext('Introduced in: %s') % introduced_string)
241
331
        if self.deprecated:
242
332
            deprecated_string = _format_version_tuple(self.deprecated)
243
 
            strings.append('Deprecated in: %s' % deprecated_string)
 
333
            strings.append(gettext('Deprecated in: %s') % deprecated_string)
244
334
        strings.append('')
245
335
        strings.extend(textwrap.wrap(self.__doc__,
246
336
            break_long_words=False))
248
338
        return '\n'.join(strings)
249
339
 
250
340
    def __eq__(self, other):
251
 
        return (type(other) == type(self) and 
252
 
            other.__dict__ == self.__dict__)
 
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))
253
355
 
254
356
    def hook(self, callback, callback_label):
255
357
        """Register a callback to be called when this HookPoint fires.
258
360
        :param callback_label: A label to show in the UI while this callback is
259
361
            processing.
260
362
        """
261
 
        self._callbacks.append(callback)
262
 
        if callback_label is not None:
263
 
            self._callback_names[callback] = callback_label
 
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)
264
380
 
265
381
    def __iter__(self):
266
 
        return iter(self._callbacks)
 
382
        return (callback.get_obj() for callback, name in self._callbacks)
267
383
 
268
384
    def __len__(self):
269
385
        return len(self._callbacks)
273
389
        strings.append("<%s(" % type(self).__name__)
274
390
        strings.append(self.name)
275
391
        strings.append("), callbacks=[")
276
 
        for callback in self._callbacks:
277
 
            strings.append(repr(callback))
 
392
        callbacks = self._callbacks
 
393
        for (callback, callback_name) in callbacks:
 
394
            strings.append(repr(callback.get_obj()))
278
395
            strings.append("(")
279
 
            strings.append(self._callback_names[callback])
 
396
            strings.append(callback_name)
280
397
            strings.append("),")
281
 
        if len(self._callbacks) == 1:
 
398
        if len(callbacks) == 1:
282
399
            strings[-1] = ")"
283
400
        strings.append("]>")
284
401
        return ''.join(strings)
323
440
        hooks = known_hooks_key_to_object(hook_key)
324
441
        segments.append(hooks.docs())
325
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))