/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 breezy/hooks.py

  • Committer: Jelmer Vernooij
  • Date: 2017-06-10 12:50:32 UTC
  • mfrom: (6679 work)
  • mto: This revision was merged to the branch mainline in revision 6690.
  • Revision ID: jelmer@jelmer.uk-20170610125032-xb5rd5fjskjallos
Merge trunk.

Show diffs side-by-side

added added

removed removed

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