← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Jelmer Vernooij
  • Date: 2010-12-20 11:57:14 UTC
  • mto: This revision was merged to the branch mainline in revision 5577.
  • Revision ID: jelmer@samba.org-20101220115714-2ru3hfappjweeg7q
Don't use no-plugins.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/hooks.py
1
 
# Copyright (C) 2007, 2008 Canonical Ltd
 
1
# Copyright (C) 2007-2010 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
 
from bzrlib import registry
 
19
from bzrlib import (
 
20
    pyutils,
 
21
    registry,
 
22
    symbol_versioning,
 
23
    )
20
24
from bzrlib.lazy_import import lazy_import
21
 
from bzrlib.symbol_versioning import deprecated_method
22
25
lazy_import(globals(), """
23
26
import textwrap
24
27
 
30
33
""")
31
34
 
32
35
 
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')
 
36
class KnownHooksRegistry(registry.Registry):
 
37
    # known_hooks registry contains
 
38
    # tuple of (module, member name) which is the hook point
 
39
    # module where the specific hooks are defined
 
40
    # callable to get the empty specific Hooks for that attribute
 
41
 
 
42
    def register_lazy_hook(self, hook_module_name, hook_member_name,
 
43
            hook_factory_member_name):
 
44
        self.register_lazy((hook_module_name, hook_member_name),
 
45
            hook_module_name, hook_factory_member_name)
 
46
 
 
47
    def iter_parent_objects(self):
 
48
        """Yield (hook_key, (parent_object, attr)) tuples for every registered
 
49
        hook, where 'parent_object' is the object that holds the hook
 
50
        instance.
 
51
 
 
52
        This is useful for resetting/restoring all the hooks to a known state,
 
53
        as is done in bzrlib.tests.TestCase._clear_hooks.
 
54
        """
 
55
        for key in self.keys():
 
56
            yield key, self.key_to_parent_and_attribute(key)
 
57
 
 
58
    def key_to_parent_and_attribute(self, (module_name, member_name)):
 
59
        """Convert a known_hooks key to a (parent_obj, attr) pair.
 
60
 
 
61
        :param key: A tuple (module_name, member_name) as found in the keys of
 
62
            the known_hooks registry.
 
63
        :return: The parent_object of the hook and the name of the attribute on
 
64
            that parent object where the hook is kept.
 
65
        """
 
66
        parent_mod, parent_member, attr = pyutils.calc_parent_name(module_name,
 
67
            member_name)
 
68
        return pyutils.get_named_object(parent_mod, parent_member), attr
 
69
 
 
70
 
 
71
_builtin_known_hooks = (
 
72
    ('bzrlib.branch', 'Branch.hooks', 'BranchHooks'),
 
73
    ('bzrlib.bzrdir', 'BzrDir.hooks', 'BzrDirHooks'),
 
74
    ('bzrlib.commands', 'Command.hooks', 'CommandHooks'),
 
75
    ('bzrlib.info', 'hooks', 'InfoHooks'),
 
76
    ('bzrlib.lock', 'Lock.hooks', 'LockHooks'),
 
77
    ('bzrlib.merge', 'Merger.hooks', 'MergeHooks'),
 
78
    ('bzrlib.msgeditor', 'hooks', 'MessageEditorHooks'),
 
79
    ('bzrlib.mutabletree', 'MutableTree.hooks', 'MutableTreeHooks'),
 
80
    ('bzrlib.smart.client', '_SmartClient.hooks', 'SmartClientHooks'),
 
81
    ('bzrlib.smart.server', 'SmartTCPServer.hooks', 'SmartServerHooks'),
 
82
    ('bzrlib.status', 'hooks', 'StatusHooks'),
 
83
    ('bzrlib.version_info_formats.format_rio', 'RioVersionInfoBuilder.hooks',
 
84
        'RioVersionInfoBuilderHooks'),
 
85
    ('bzrlib.merge_directive', 'BaseMergeDirective.hooks',
 
86
        'MergeDirectiveHooks'),
 
87
    )
 
88
 
 
89
known_hooks = KnownHooksRegistry()
 
90
for (_hook_module, _hook_attribute, _hook_class) in _builtin_known_hooks:
 
91
    known_hooks.register_lazy_hook(_hook_module, _hook_attribute, _hook_class)
 
92
del _builtin_known_hooks, _hook_module, _hook_attribute, _hook_class
62
93
 
63
94
 
64
95
def known_hooks_key_to_object((module_name, member_name)):
68
99
        the known_hooks registry.
69
100
    :return: The object this specifies.
70
101
    """
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
 
102
    return pyutils.get_named_object(module_name, member_name)
 
103
 
 
104
 
 
105
@symbol_versioning.deprecated_function(symbol_versioning.deprecated_in((2, 3)))
 
106
def known_hooks_key_to_parent_and_attribute(key):
 
107
    """See KnownHooksRegistry.key_to_parent_and_attribute."""
 
108
    return known_hooks.key_to_parent_and_attribute(key)
89
109
 
90
110
 
91
111
class Hooks(dict):
178
198
    """A single hook that clients can register to be called back when it fires.
179
199
 
180
200
    :ivar name: The name of the hook.
 
201
    :ivar doc: The docs for using the hook.
181
202
    :ivar introduced: A version tuple specifying what version the hook was
182
203
        introduced in. None indicates an unknown version.
183
204
    :ivar deprecated: A version tuple specifying what version the hook was
184
205
        deprecated or superseded in. None indicates that the hook is not
185
206
        superseded or deprecated. If the hook is superseded then the doc
186
207
        should describe the recommended replacement hook to register for.
187
 
    :ivar doc: The docs for using the hook.
188
208
    """
189
209
 
190
210
    def __init__(self, name, doc, introduced, deprecated):
219
239
        strings.append('Introduced in: %s' % introduced_string)
220
240
        if self.deprecated:
221
241
            deprecated_string = _format_version_tuple(self.deprecated)
222
 
        else:
223
 
            deprecated_string = 'Not deprecated'
224
 
        strings.append('Deprecated in: %s' % deprecated_string)
 
242
            strings.append('Deprecated in: %s' % deprecated_string)
225
243
        strings.append('')
226
244
        strings.extend(textwrap.wrap(self.__doc__,
227
245
            break_long_words=False))
277
295
 
278
296
  yyy.hooks.install_named_hook("xxx", ...)
279
297
 
280
 
See `Using hooks`_ in the User Guide for examples.
281
 
 
282
 
.. _Using hooks: ../user-guide/index.html#using-hooks
 
298
See :doc:`Using hooks<../user-guide/hooks>` in the User Guide for examples.
283
299
 
284
300
The class that contains each hook is given before the hooks it supplies. For
285
301
instance, BranchHooks as the class is the hooks class for