← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/plugin.py

(vila) Revise legal option names to be less drastic. (Vincent Ladeuil)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/plugin.py
1
 
# Copyright (C) 2005-2010 Canonical Ltd
 
1
# Copyright (C) 2005-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
"""bzr python plugin support.
19
18
 
20
19
When load_plugins() is invoked, any python module in any directory in
30
29
called.
31
30
"""
32
31
 
 
32
from __future__ import absolute_import
 
33
 
33
34
import os
34
35
import sys
35
36
 
36
37
from bzrlib import osutils
37
38
 
38
39
from bzrlib.lazy_import import lazy_import
39
 
 
40
40
lazy_import(globals(), """
41
41
import imp
42
42
import re
49
49
    errors,
50
50
    trace,
51
51
    )
 
52
from bzrlib.i18n import gettext
52
53
from bzrlib import plugins as _mod_plugins
53
54
""")
54
55
 
55
 
from bzrlib.symbol_versioning import (
56
 
    deprecated_function,
57
 
    deprecated_in,
58
 
    )
59
 
 
60
56
 
61
57
DEFAULT_PLUGIN_PATH = None
62
58
_loaded = False
63
59
_plugins_disabled = False
64
60
 
65
61
 
 
62
plugin_warnings = {}
 
63
# Map from plugin name, to list of string warnings about eg plugin
 
64
# dependencies.
 
65
 
 
66
 
66
67
def are_plugins_disabled():
67
68
    return _plugins_disabled
68
69
 
77
78
    load_plugins([])
78
79
 
79
80
 
 
81
def describe_plugins(show_paths=False):
 
82
    """Generate text description of plugins.
 
83
 
 
84
    Includes both those that have loaded, and those that failed to 
 
85
    load.
 
86
 
 
87
    :param show_paths: If true,
 
88
    :returns: Iterator of text lines (including newlines.)
 
89
    """
 
90
    from inspect import getdoc
 
91
    loaded_plugins = plugins()
 
92
    all_names = sorted(list(set(
 
93
        loaded_plugins.keys() + plugin_warnings.keys())))
 
94
    for name in all_names:
 
95
        if name in loaded_plugins:
 
96
            plugin = loaded_plugins[name]
 
97
            version = plugin.__version__
 
98
            if version == 'unknown':
 
99
                version = ''
 
100
            yield '%s %s\n' % (name, version)
 
101
            d = getdoc(plugin.module)
 
102
            if d:
 
103
                doc = d.split('\n')[0]
 
104
            else:
 
105
                doc = '(no description)'
 
106
            yield ("  %s\n" % doc)
 
107
            if show_paths:
 
108
                yield ("   %s\n" % plugin.path())
 
109
            del plugin
 
110
        else:
 
111
            yield "%s (failed to load)\n" % name
 
112
        if name in plugin_warnings:
 
113
            for line in plugin_warnings[name]:
 
114
                yield "  ** " + line + '\n'
 
115
        yield '\n'
 
116
 
 
117
 
80
118
def _strip_trailing_sep(path):
81
119
    return path.rstrip("\\/")
82
120
 
83
121
 
 
122
def _get_specific_plugin_paths(paths):
 
123
    """Returns the plugin paths from a string describing the associations.
 
124
 
 
125
    :param paths: A string describing the paths associated with the plugins.
 
126
 
 
127
    :returns: A list of (plugin name, path) tuples.
 
128
 
 
129
    For example, if paths is my_plugin@/test/my-test:her_plugin@/production/her,
 
130
    [('my_plugin', '/test/my-test'), ('her_plugin', '/production/her')] 
 
131
    will be returned.
 
132
 
 
133
    Note that ':' in the example above depends on the os.
 
134
    """
 
135
    if not paths:
 
136
        return []
 
137
    specs = []
 
138
    for spec in paths.split(os.pathsep):
 
139
        try:
 
140
            name, path = spec.split('@')
 
141
        except ValueError:
 
142
            raise errors.BzrCommandError(gettext(
 
143
                '"%s" is not a valid <plugin_name>@<plugin_path> description ')
 
144
                % spec)
 
145
        specs.append((name, path))
 
146
    return specs
 
147
 
 
148
 
84
149
def set_plugins_path(path=None):
85
150
    """Set the path for plugins to be loaded from.
86
151
 
98
163
        for name in disabled_plugins.split(os.pathsep):
99
164
            PluginImporter.blacklist.add('bzrlib.plugins.' + name)
100
165
    # Set up a the specific paths for plugins
101
 
    specific_plugins = os.environ.get('BZR_PLUGINS_AT', None)
102
 
    if specific_plugins is not None:
103
 
        for spec in specific_plugins.split(os.pathsep):
104
 
            plugin_name, plugin_path = spec.split('@')
 
166
    for plugin_name, plugin_path in _get_specific_plugin_paths(os.environ.get(
 
167
            'BZR_PLUGINS_AT', None)):
105
168
            PluginImporter.specific_paths[
106
169
                'bzrlib.plugins.%s' % plugin_name] = plugin_path
107
170
    return path
211
274
    """Load bzrlib plugins.
212
275
 
213
276
    The environment variable BZR_PLUGIN_PATH is considered a delimited
214
 
    set of paths to look through. Each entry is searched for *.py
 
277
    set of paths to look through. Each entry is searched for `*.py`
215
278
    files (and whatever other extensions are used in the platform,
216
 
    such as *.pyd).
 
279
    such as `*.pyd`).
217
280
 
218
281
    load_from_path() provides the underlying mechanism and is called with
219
282
    the default directory list to provide the normal behaviour.
302
365
    return None, None, (None, None, None)
303
366
 
304
367
 
 
368
def record_plugin_warning(plugin_name, warning_message):
 
369
    trace.mutter(warning_message)
 
370
    plugin_warnings.setdefault(plugin_name, []).append(warning_message)
 
371
 
 
372
 
305
373
def _load_plugin_module(name, dir):
306
374
    """Load plugin name from dir.
307
375
 
315
383
    except KeyboardInterrupt:
316
384
        raise
317
385
    except errors.IncompatibleAPI, e:
318
 
        trace.warning("Unable to load plugin %r. It requested API version "
 
386
        warning_message = (
 
387
            "Unable to load plugin %r. It requested API version "
319
388
            "%s of module %s but the minimum exported version is %s, and "
320
389
            "the maximum is %s" %
321
390
            (name, e.wanted, e.api, e.minimum, e.current))
 
391
        record_plugin_warning(name, warning_message)
322
392
    except Exception, e:
323
393
        trace.warning("%s" % e)
324
394
        if re.search('\.|-| ', name):
329
399
                    "file path isn't a valid module name; try renaming "
330
400
                    "it to %r." % (name, dir, sanitised_name))
331
401
        else:
332
 
            trace.warning('Unable to load plugin %r from %r' % (name, dir))
 
402
            record_plugin_warning(
 
403
                name,
 
404
                'Unable to load plugin %r from %r' % (name, dir))
333
405
        trace.log_exception_quietly()
334
406
        if 'error' in debug.debug_flags:
335
407
            trace.print_exception(sys.exc_info(), sys.stderr)
375
447
    return result
376
448
 
377
449
 
 
450
def format_concise_plugin_list():
 
451
    """Return a string holding a concise list of plugins and their version.
 
452
    """
 
453
    items = []
 
454
    for name, a_plugin in sorted(plugins().items()):
 
455
        items.append("%s[%s]" %
 
456
            (name, a_plugin.__version__))
 
457
    return ', '.join(items)
 
458
 
 
459
 
 
460
 
378
461
class PluginsHelpIndex(object):
379
462
    """A help index that returns help topics for plugins."""
380
463
 
425
508
            result = self.module.__doc__
426
509
        if result[-1] != '\n':
427
510
            result += '\n'
428
 
        # there is code duplicated here and in bzrlib/help_topic.py's
429
 
        # matching Topic code. This should probably be factored in
430
 
        # to a helper function and a common base class.
431
 
        if additional_see_also is not None:
432
 
            see_also = sorted(set(additional_see_also))
433
 
        else:
434
 
            see_also = None
435
 
        if see_also:
436
 
            result += 'See also: '
437
 
            result += ', '.join(see_also)
438
 
            result += '\n'
 
511
        from bzrlib import help_topics
 
512
        result += help_topics._format_see_also(additional_see_also)
439
513
        return result
440
514
 
441
515
    def get_help_topic(self):
442
 
        """Return the modules help topic - its __name__ after bzrlib.plugins.."""
 
516
        """Return the module help topic: its basename."""
443
517
        return self.module.__name__[len('bzrlib.plugins.'):]
444
518
 
445
519
 
558
632
        return None
559
633
 
560
634
    def load_module(self, fullname):
561
 
        """Load a plugin from a specific directory."""
 
635
        """Load a plugin from a specific directory (or file)."""
562
636
        # We are called only for specific paths
563
637
        plugin_path = self.specific_paths[fullname]
564
638
        loading_path = None
565
 
        package = False
566
639
        if os.path.isdir(plugin_path):
567
640
            for suffix, mode, kind in imp.get_suffixes():
568
641
                if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
570
643
                    continue
571
644
                init_path = osutils.pathjoin(plugin_path, '__init__' + suffix)
572
645
                if os.path.isfile(init_path):
573
 
                    loading_path = init_path
574
 
                    package = True
 
646
                    # We've got a module here and load_module needs specific
 
647
                    # parameters.
 
648
                    loading_path = plugin_path
 
649
                    suffix = ''
 
650
                    mode = ''
 
651
                    kind = imp.PKG_DIRECTORY
575
652
                    break
576
653
        else:
577
654
            for suffix, mode, kind in imp.get_suffixes():
581
658
        if loading_path is None:
582
659
            raise ImportError('%s cannot be loaded from %s'
583
660
                              % (fullname, plugin_path))
584
 
        f = open(loading_path, mode)
 
661
        if kind is imp.PKG_DIRECTORY:
 
662
            f = None
 
663
        else:
 
664
            f = open(loading_path, mode)
585
665
        try:
586
666
            mod = imp.load_module(fullname, f, loading_path,
587
667
                                  (suffix, mode, kind))
588
 
            if package:
589
 
                # The plugin can contain modules, so be ready
590
 
                mod.__path__ = [plugin_path]
591
668
            mod.__package__ = fullname
592
669
            return mod
593
670
        finally:
594
 
            f.close()
 
671
            if f is not None:
 
672
                f.close()
595
673
 
596
674
 
597
675
# Install a dedicated importer for plugins requiring special handling