← Back to branch summary

~bzr/ubuntu/lucid/bzr/beta-ppa

« back to all changes in this revision

Viewing changes to bzrlib/hooks.py

  • Committer: Martin Pool
  • Date: 2010-07-02 07:29:40 UTC
  • mfrom: (129.1.7 packaging-karmic)
  • Revision ID: mbp@sourcefrog.net-20100702072940-hpzq5elg8wjve8rh
http://bugs.debian.org/452024
http://bugs.debian.org/464688
http://bugs.debian.org/523595
http://bugs.debian.org/526233
http://bugs.debian.org/537708
http://bugs.debian.org/555336
http://bugs.debian.org/555343
https://launchpad.net/bugs/249452
https://launchpad.net/bugs/385074
* PPA rebuild.
* PPA rebuild for Karmic.
* PPA rebuild for Jaunty.
* PPA rebuild for Hardy.
* From postinst, actually remove the example bash completion scripts.
  (LP: #249452)
* New upstream release.
* New upstream release.
* New upstream release.
* Revert change to Build-depends: Dapper does not have python-central.
  Should be python-support..
* Target ppa..
* Target ppa..
* Target ppa..
* Target ppa..
* New upstream release.
* Switch to dpkg-source 3.0 (quilt) format.
* Bump standards version to 3.8.4.
* Remove embedded copy of python-configobj. Closes: #555336
* Remove embedded copy of python-elementtree. Closes: #555343
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* Change section from 'Devel' to 'Vcs'..
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* debian/control: Fix obsolete-relation-form-in-source
  lintian warning. 
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split out docs into bzr-doc package.
* New upstream release.
* Added John Francesco Ferlito to Uploaders.
* Fix install path to quick-reference guide
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to doc paths changing
* New upstream release.
* Fix FTBFS due to path changes, again, again.
* Fix FTBFS due to path changes, again.
* Fix FTBFS due to path changes.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Bump standards version to 3.8.3.
* Remove unused patch system.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix copy and paste tab error in .install file
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
 + Fixes compatibility with Python 2.4. Closes: #537708
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream version.
* Bump standards version to 3.8.2.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add python-pyrex to build-deps to ensure C extensions are always build.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* Split documentation into bzr-doc package. ((LP: #385074)
* Multiple packaging changes to make us more linitan clean.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Fix API compatibility version. (Closes: #526233)
* New upstream release.
  + Fixes default format for upgrade command. (Closes: #464688)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add missing dependency on zlib development library. (Closes:
  #523595)
* Add zlib build-depends.
* Add zlib build-depends.
* Add zlib build-depends.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Move to section vcs.
* Bump standards version to 3.8.1.
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* New upstream release.
* Remove temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* Add temporary patch for missing .c files from distribution
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Recommend ca-certificates. (Closes: #452024)
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Update watch file. bazaar now uses launchpad to host its sources.
* Remove patch for inventory root revision copy, applied upstream.
* New upstream release.
* New upstream release.
* New upstream release
* Force removal of files installed in error to /etc/bash_completion.d/
  (LP: #249452)
* New upstream release.
* New upstream release
* New upstream release.
* Bump standards version.
* Include patch for inventory root revision copy, required for bzr-svn.
* New upstream release.
* Remove unused lintian overrides.
* Correct the package version not to be native.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* New upstream release.
* Final 1.5 release.
* New upstream release.
* New upstream release.
* New upstream release.
* Add myself as a co-maintainer.
* Add a Dm-Upload-Allowed: yes header.
* New upstream bugfix release.
* New upstream release.
* Final 1.3 release.
* New upstream release.
* First release candidate of the upcoming 1.3 release.
* Rebuild to fix the problem caused by a build with a broken python-central.
* New upstream release.
* Rebuild for dapper PPA.
* Apply Lamont's patches to fix build-dependencies on dapper.
  (See: https://bugs.launchpad.net/bzr/+bug/189915)

Show diffs side-by-side

added added

removed removed

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