/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: Gustav Hartvigsson
  • Date: 2021-01-09 21:36:27 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210109213627-h1xwcutzy9m7a99b
Added 'Case Preserving Working Tree Use Cases' from Canonical Wiki

* Addod a page from the Canonical Bazaar wiki
  with information on the scmeatics of case
  perserving filesystems an a case insensitive
  filesystem works.
  
  * Needs re-work, but this will do as it is the
    same inforamoton as what was on the linked
    page in the currint documentation.

Show diffs side-by-side

added added

removed removed

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