~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/plugin.py

  • Committer: Patch Queue Manager
  • Date: 2016-04-21 04:10:52 UTC
  • mfrom: (6616.1.1 fix-en-user-guide)
  • Revision ID: pqm@pqm.ubuntu.com-20160421041052-clcye7ns1qcl2n7w
(richard-wilbur) Ensure build of English use guide always uses English text
 even when user's locale specifies a different language. (Jelmer Vernooij)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2004, 2005 by Canonical Ltd
2
 
 
 
1
# Copyright (C) 2005-2011 Canonical Ltd
 
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
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
 
 
7
#
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
12
 
 
 
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 
 
17
 
 
18
 
# This module implements plug-in support.
19
 
# Any python module in $BZR_PLUGIN_PATH will be imported upon initialization
20
 
# of bzrlib (and then forgotten about).  In the plugin's main body, it should
21
 
# update any bzrlib registries it wants to extend; for example, to add new
22
 
# commands, import bzrlib.commands and add your new command to the
23
 
# plugin_cmds variable.
24
 
 
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
 
 
17
"""bzr python plugin support.
 
18
 
 
19
When load_plugins() is invoked, any python module in any directory in
 
20
$BZR_PLUGIN_PATH will be imported.  The module will be imported as
 
21
'bzrlib.plugins.$BASENAME(PLUGIN)'.  In the plugin's main body, it should
 
22
update any bzrlib registries it wants to extend.
 
23
 
 
24
See the plugin-api developer documentation for information about writing
 
25
plugins.
 
26
 
 
27
BZR_PLUGIN_PATH is also honoured for any plugins imported via
 
28
'import bzrlib.plugins.PLUGINNAME', as long as set_plugins_path has been
 
29
called.
 
30
"""
 
31
 
 
32
from __future__ import absolute_import
25
33
 
26
34
import os
27
 
import bzrlib
28
 
from bzrlib.config import config_dir
29
 
DEFAULT_PLUGIN_PATH = os.path.join(config_dir(), 'plugins')
30
 
 
31
 
all_plugins = []
 
35
import sys
 
36
 
 
37
from bzrlib import osutils
 
38
 
 
39
from bzrlib.lazy_import import lazy_import
 
40
lazy_import(globals(), """
 
41
import imp
 
42
import re
 
43
import types
 
44
 
 
45
from bzrlib import (
 
46
    _format_version_tuple,
 
47
    config,
 
48
    debug,
 
49
    errors,
 
50
    trace,
 
51
    )
 
52
from bzrlib.i18n import gettext
 
53
from bzrlib import plugins as _mod_plugins
 
54
""")
 
55
 
 
56
 
 
57
DEFAULT_PLUGIN_PATH = None
32
58
_loaded = False
33
 
 
34
 
 
35
 
def load_plugins():
36
 
    """
37
 
    Find all python plugins and load them.
38
 
 
39
 
    Loading a plugin means importing it into the python interpreter.
40
 
    The plugin is expected to make calls to register commands when
41
 
    it's loaded (or perhaps access other hooks in future.)
42
 
 
43
 
    A list of plugs is stored in bzrlib.plugin.all_plugins for future
44
 
    reference.
 
59
_plugins_disabled = False
 
60
 
 
61
 
 
62
plugin_warnings = {}
 
63
# Map from plugin name, to list of string warnings about eg plugin
 
64
# dependencies.
 
65
 
 
66
 
 
67
def are_plugins_disabled():
 
68
    return _plugins_disabled
 
69
 
 
70
 
 
71
def disable_plugins():
 
72
    """Disable loading plugins.
 
73
 
 
74
    Future calls to load_plugins() will be ignored.
 
75
    """
 
76
    global _plugins_disabled
 
77
    _plugins_disabled = True
 
78
    load_plugins([])
 
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
 
 
118
def _strip_trailing_sep(path):
 
119
    return path.rstrip("\\/")
 
120
 
 
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
 
 
149
def set_plugins_path(path=None):
 
150
    """Set the path for plugins to be loaded from.
 
151
 
 
152
    :param path: The list of paths to search for plugins.  By default,
 
153
        path will be determined using get_standard_plugins_path.
 
154
        if path is [], no plugins can be loaded.
 
155
    """
 
156
    if path is None:
 
157
        path = get_standard_plugins_path()
 
158
    _mod_plugins.__path__ = path
 
159
    PluginImporter.reset()
 
160
    # Set up a blacklist for disabled plugins
 
161
    disabled_plugins = os.environ.get('BZR_DISABLE_PLUGINS', None)
 
162
    if disabled_plugins is not None:
 
163
        for name in disabled_plugins.split(os.pathsep):
 
164
            PluginImporter.blacklist.add('bzrlib.plugins.' + name)
 
165
    # Set up a the specific paths for plugins
 
166
    for plugin_name, plugin_path in _get_specific_plugin_paths(os.environ.get(
 
167
            'BZR_PLUGINS_AT', None)):
 
168
            PluginImporter.specific_paths[
 
169
                'bzrlib.plugins.%s' % plugin_name] = plugin_path
 
170
    return path
 
171
 
 
172
 
 
173
def _append_new_path(paths, new_path):
 
174
    """Append a new path if it set and not already known."""
 
175
    if new_path is not None and new_path not in paths:
 
176
        paths.append(new_path)
 
177
    return paths
 
178
 
 
179
 
 
180
def get_core_plugin_path():
 
181
    core_path = None
 
182
    bzr_exe = bool(getattr(sys, 'frozen', None))
 
183
    if bzr_exe:    # expand path for bzr.exe
 
184
        # We need to use relative path to system-wide plugin
 
185
        # directory because bzrlib from standalone bzr.exe
 
186
        # could be imported by another standalone program
 
187
        # (e.g. bzr-config; or TortoiseBzr/Olive if/when they
 
188
        # will become standalone exe). [bialix 20071123]
 
189
        # __file__ typically is
 
190
        # C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
 
191
        # then plugins directory is
 
192
        # C:\Program Files\Bazaar\plugins
 
193
        # so relative path is ../../../plugins
 
194
        core_path = osutils.abspath(osutils.pathjoin(
 
195
                osutils.dirname(__file__), '../../../plugins'))
 
196
    else:     # don't look inside library.zip
 
197
        # search the plugin path before the bzrlib installed dir
 
198
        core_path = os.path.dirname(_mod_plugins.__file__)
 
199
    return core_path
 
200
 
 
201
 
 
202
def get_site_plugin_path():
 
203
    """Returns the path for the site installed plugins."""
 
204
    if sys.platform == 'win32':
 
205
        # We don't have (yet) a good answer for windows since that is certainly
 
206
        # related to the way we build the installers. -- vila20090821
 
207
        return None
 
208
    site_path = None
 
209
    try:
 
210
        from distutils.sysconfig import get_python_lib
 
211
    except ImportError:
 
212
        # If distutuils is not available, we just don't know where they are
 
213
        pass
 
214
    else:
 
215
        site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
 
216
    return site_path
 
217
 
 
218
 
 
219
def get_user_plugin_path():
 
220
    return osutils.pathjoin(config.config_dir(), 'plugins')
 
221
 
 
222
 
 
223
def get_standard_plugins_path():
 
224
    """Determine a plugin path suitable for general use."""
 
225
    # Ad-Hoc default: core is not overriden by site but user can overrides both
 
226
    # The rationale is that:
 
227
    # - 'site' comes last, because these plugins should always be available and
 
228
    #   are supposed to be in sync with the bzr installed on site.
 
229
    # - 'core' comes before 'site' so that running bzr from sources or a user
 
230
    #   installed version overrides the site version.
 
231
    # - 'user' comes first, because... user is always right.
 
232
    # - the above rules clearly defines which plugin version will be loaded if
 
233
    #   several exist. Yet, it is sometimes desirable to disable some directory
 
234
    #   so that a set of plugins is disabled as once. This can be done via
 
235
    #   -site, -core, -user.
 
236
 
 
237
    env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
 
238
    defaults = ['+core', '+site']
 
239
 
 
240
    # The predefined references
 
241
    refs = dict(core=get_core_plugin_path(),
 
242
                site=get_site_plugin_path(),
 
243
                user=get_user_plugin_path())
 
244
 
 
245
    # Unset paths that should be removed
 
246
    for k,v in refs.iteritems():
 
247
        removed = '-%s' % k
 
248
        # defaults can never mention removing paths as that will make it
 
249
        # impossible for the user to revoke these removals.
 
250
        if removed in env_paths:
 
251
            env_paths.remove(removed)
 
252
            refs[k] = None
 
253
 
 
254
    # Expand references
 
255
    paths = []
 
256
    for p in env_paths + defaults:
 
257
        if p.startswith('+'):
 
258
            # Resolve references if they are known
 
259
            try:
 
260
                p = refs[p[1:]]
 
261
            except KeyError:
 
262
                # Leave them untouched so user can still use paths starting
 
263
                # with '+'
 
264
                pass
 
265
        _append_new_path(paths, p)
 
266
 
 
267
    # Get rid of trailing slashes, since Python can't handle them when
 
268
    # it tries to import modules.
 
269
    paths = map(_strip_trailing_sep, paths)
 
270
    return paths
 
271
 
 
272
 
 
273
def load_plugins(path=None):
 
274
    """Load bzrlib plugins.
45
275
 
46
276
    The environment variable BZR_PLUGIN_PATH is considered a delimited
47
 
    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`
48
278
    files (and whatever other extensions are used in the platform,
49
 
    such as *.pyd).
 
279
    such as `*.pyd`).
 
280
 
 
281
    load_from_path() provides the underlying mechanism and is called with
 
282
    the default directory list to provide the normal behaviour.
 
283
 
 
284
    :param path: The list of paths to search for plugins.  By default,
 
285
        path will be determined using get_standard_plugins_path.
 
286
        if path is [], no plugins can be loaded.
50
287
    """
51
 
 
52
 
    global all_plugins, _loaded
 
288
    global _loaded
53
289
    if _loaded:
54
290
        # People can make sure plugins are loaded, they just won't be twice
55
291
        return
56
 
        #raise BzrError("plugins already initialized")
57
292
    _loaded = True
58
293
 
59
 
    import sys, os, imp
60
 
    
61
 
    from bzrlib.trace import log_error, mutter, log_exception
62
 
    from bzrlib.errors import BzrError
63
 
    from bzrlib import plugins
64
 
 
65
 
    dirs = os.environ.get('BZR_PLUGIN_PATH', DEFAULT_PLUGIN_PATH).split(":")
66
 
    dirs.insert(0, os.path.dirname(plugins.__file__))
67
 
 
68
 
    # The problem with imp.get_suffixes() is that it doesn't include
69
 
    # .pyo which is technically valid
70
 
    # It also means that "testmodule.so" will show up as both test and testmodule
71
 
    # though it is only valid as 'test'
72
 
    # but you should be careful, because "testmodule.py" loads as testmodule.
73
 
    suffixes = imp.get_suffixes()
74
 
    suffixes.append(('.pyo', 'rb', imp.PY_COMPILED))
75
 
    package_entries = ['__init__.py', '__init__.pyc', '__init__.pyo']
 
294
    # scan for all plugins in the path.
 
295
    load_from_path(set_plugins_path(path))
 
296
 
 
297
 
 
298
def load_from_path(dirs):
 
299
    """Load bzrlib plugins found in each dir in dirs.
 
300
 
 
301
    Loading a plugin means importing it into the python interpreter.
 
302
    The plugin is expected to make calls to register commands when
 
303
    it's loaded (or perhaps access other hooks in future.)
 
304
 
 
305
    Plugins are loaded into bzrlib.plugins.NAME, and can be found there
 
306
    for future reference.
 
307
 
 
308
    The python module path for bzrlib.plugins will be modified to be 'dirs'.
 
309
    """
 
310
    # Explicitly load the plugins with a specific path
 
311
    for fullname, path in PluginImporter.specific_paths.iteritems():
 
312
        name = fullname[len('bzrlib.plugins.'):]
 
313
        _load_plugin_module(name, path)
 
314
 
 
315
    # We need to strip the trailing separators here as well as in the
 
316
    # set_plugins_path function because calling code can pass anything in to
 
317
    # this function, and since it sets plugins.__path__, it should set it to
 
318
    # something that will be valid for Python to use (in case people try to
 
319
    # run "import bzrlib.plugins.PLUGINNAME" after calling this function).
 
320
    _mod_plugins.__path__ = map(_strip_trailing_sep, dirs)
76
321
    for d in dirs:
77
 
        # going through them one by one allows different plugins with the same
78
 
        # filename in different directories in the path
79
 
        mutter('looking for plugins in %s' % d)
80
322
        if not d:
81
323
            continue
82
 
        plugin_names = set()
83
 
        if not os.path.isdir(d):
84
 
            continue
85
 
        for f in os.listdir(d):
86
 
            path = os.path.join(d, f)
87
 
            if os.path.isdir(path):
88
 
                for entry in package_entries:
89
 
                    # This directory should be a package, and thus added to
90
 
                    # the list
91
 
                    if os.path.isfile(os.path.join(path, entry)):
92
 
                        break
93
 
                else: # This directory is not a package
94
 
                    continue
 
324
        trace.mutter('looking for plugins in %s', d)
 
325
        if os.path.isdir(d):
 
326
            load_from_dir(d)
 
327
 
 
328
 
 
329
# backwards compatability: load_from_dirs was the old name
 
330
# This was changed in 0.15
 
331
load_from_dirs = load_from_path
 
332
 
 
333
 
 
334
def _find_plugin_module(dir, name):
 
335
    """Check if there is a valid python module that can be loaded as a plugin.
 
336
 
 
337
    :param dir: The directory where the search is performed.
 
338
    :param path: An existing file path, either a python file or a package
 
339
        directory.
 
340
 
 
341
    :return: (name, path, description) name is the module name, path is the
 
342
        file to load and description is the tuple returned by
 
343
        imp.get_suffixes().
 
344
    """
 
345
    path = osutils.pathjoin(dir, name)
 
346
    if os.path.isdir(path):
 
347
        # Check for a valid __init__.py file, valid suffixes depends on -O and
 
348
        # can be .py, .pyc and .pyo
 
349
        for suffix, mode, kind in imp.get_suffixes():
 
350
            if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
 
351
                # We don't recognize compiled modules (.so, .dll, etc)
 
352
                continue
 
353
            init_path = osutils.pathjoin(path, '__init__' + suffix)
 
354
            if os.path.isfile(init_path):
 
355
                return name, init_path, (suffix, mode, kind)
 
356
    else:
 
357
        for suffix, mode, kind in imp.get_suffixes():
 
358
            if name.endswith(suffix):
 
359
                # Clean up the module name
 
360
                name = name[:-len(suffix)]
 
361
                if kind == imp.C_EXTENSION and name.endswith('module'):
 
362
                    name = name[:-len('module')]
 
363
                return name, path, (suffix, mode, kind)
 
364
    # There is no python module here
 
365
    return None, None, (None, None, None)
 
366
 
 
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
 
 
373
def _load_plugin_module(name, dir):
 
374
    """Load plugin name from dir.
 
375
 
 
376
    :param name: The plugin name in the bzrlib.plugins namespace.
 
377
    :param dir: The directory the plugin is loaded from for error messages.
 
378
    """
 
379
    if ('bzrlib.plugins.%s' % name) in PluginImporter.blacklist:
 
380
        return
 
381
    try:
 
382
        exec "import bzrlib.plugins.%s" % name in {}
 
383
    except KeyboardInterrupt:
 
384
        raise
 
385
    except errors.IncompatibleAPI, e:
 
386
        warning_message = (
 
387
            "Unable to load plugin %r. It requested API version "
 
388
            "%s of module %s but the minimum exported version is %s, and "
 
389
            "the maximum is %s" %
 
390
            (name, e.wanted, e.api, e.minimum, e.current))
 
391
        record_plugin_warning(name, warning_message)
 
392
    except Exception, e:
 
393
        trace.warning("%s" % e)
 
394
        if re.search('\.|-| ', name):
 
395
            sanitised_name = re.sub('[-. ]', '_', name)
 
396
            if sanitised_name.startswith('bzr_'):
 
397
                sanitised_name = sanitised_name[len('bzr_'):]
 
398
            trace.warning("Unable to load %r in %r as a plugin because the "
 
399
                    "file path isn't a valid module name; try renaming "
 
400
                    "it to %r." % (name, dir, sanitised_name))
 
401
        else:
 
402
            record_plugin_warning(
 
403
                name,
 
404
                'Unable to load plugin %r from %r' % (name, dir))
 
405
        trace.log_exception_quietly()
 
406
        if 'error' in debug.debug_flags:
 
407
            trace.print_exception(sys.exc_info(), sys.stderr)
 
408
 
 
409
 
 
410
def load_from_dir(d):
 
411
    """Load the plugins in directory d.
 
412
 
 
413
    d must be in the plugins module path already.
 
414
    This function is called once for each directory in the module path.
 
415
    """
 
416
    plugin_names = set()
 
417
    for p in os.listdir(d):
 
418
        name, path, desc = _find_plugin_module(d, p)
 
419
        if name is not None:
 
420
            if name == '__init__':
 
421
                # We do nothing with the __init__.py file in directories from
 
422
                # the bzrlib.plugins module path, we may want to, one day
 
423
                # -- vila 20100316.
 
424
                continue # We don't load __init__.py in the plugins dirs
 
425
            elif getattr(_mod_plugins, name, None) is not None:
 
426
                # The module has already been loaded from another directory
 
427
                # during a previous call.
 
428
                # FIXME: There should be a better way to report masked plugins
 
429
                # -- vila 20100316
 
430
                trace.mutter('Plugin name %s already loaded', name)
95
431
            else:
96
 
                for suffix_info in suffixes:
97
 
                    if f.endswith(suffix_info[0]):
98
 
                        f = f[:-len(suffix_info[0])]
99
 
                        if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
100
 
                            f = f[:-len('module')]
101
 
                        break
102
 
                else:
103
 
                    continue
104
 
            mutter('add plugin name %s' % f)
105
 
            plugin_names.add(f)
106
 
 
107
 
        plugin_names = list(plugin_names)
108
 
        plugin_names.sort()
109
 
        for name in plugin_names:
 
432
                plugin_names.add(name)
 
433
 
 
434
    for name in plugin_names:
 
435
        _load_plugin_module(name, d)
 
436
 
 
437
 
 
438
def plugins():
 
439
    """Return a dictionary of the plugins.
 
440
 
 
441
    Each item in the dictionary is a PlugIn object.
 
442
    """
 
443
    result = {}
 
444
    for name, plugin in _mod_plugins.__dict__.items():
 
445
        if isinstance(plugin, types.ModuleType):
 
446
            result[name] = PlugIn(name, plugin)
 
447
    return result
 
448
 
 
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
 
 
461
class PluginsHelpIndex(object):
 
462
    """A help index that returns help topics for plugins."""
 
463
 
 
464
    def __init__(self):
 
465
        self.prefix = 'plugins/'
 
466
 
 
467
    def get_topics(self, topic):
 
468
        """Search for topic in the loaded plugins.
 
469
 
 
470
        This will not trigger loading of new plugins.
 
471
 
 
472
        :param topic: A topic to search for.
 
473
        :return: A list which is either empty or contains a single
 
474
            RegisteredTopic entry.
 
475
        """
 
476
        if not topic:
 
477
            return []
 
478
        if topic.startswith(self.prefix):
 
479
            topic = topic[len(self.prefix):]
 
480
        plugin_module_name = 'bzrlib.plugins.%s' % topic
 
481
        try:
 
482
            module = sys.modules[plugin_module_name]
 
483
        except KeyError:
 
484
            return []
 
485
        else:
 
486
            return [ModuleHelpTopic(module)]
 
487
 
 
488
 
 
489
class ModuleHelpTopic(object):
 
490
    """A help topic which returns the docstring for a module."""
 
491
 
 
492
    def __init__(self, module):
 
493
        """Constructor.
 
494
 
 
495
        :param module: The module for which help should be generated.
 
496
        """
 
497
        self.module = module
 
498
 
 
499
    def get_help_text(self, additional_see_also=None, verbose=True):
 
500
        """Return a string with the help for this topic.
 
501
 
 
502
        :param additional_see_also: Additional help topics to be
 
503
            cross-referenced.
 
504
        """
 
505
        if not self.module.__doc__:
 
506
            result = "Plugin '%s' has no docstring.\n" % self.module.__name__
 
507
        else:
 
508
            result = self.module.__doc__
 
509
        if result[-1] != '\n':
 
510
            result += '\n'
 
511
        from bzrlib import help_topics
 
512
        result += help_topics._format_see_also(additional_see_also)
 
513
        return result
 
514
 
 
515
    def get_help_topic(self):
 
516
        """Return the module help topic: its basename."""
 
517
        return self.module.__name__[len('bzrlib.plugins.'):]
 
518
 
 
519
 
 
520
class PlugIn(object):
 
521
    """The bzrlib representation of a plugin.
 
522
 
 
523
    The PlugIn object provides a way to manipulate a given plugin module.
 
524
    """
 
525
 
 
526
    def __init__(self, name, module):
 
527
        """Construct a plugin for module."""
 
528
        self.name = name
 
529
        self.module = module
 
530
 
 
531
    def path(self):
 
532
        """Get the path that this plugin was loaded from."""
 
533
        if getattr(self.module, '__path__', None) is not None:
 
534
            return os.path.abspath(self.module.__path__[0])
 
535
        elif getattr(self.module, '__file__', None) is not None:
 
536
            path = os.path.abspath(self.module.__file__)
 
537
            if path[-4:] in ('.pyc', '.pyo'):
 
538
                pypath = path[:-4] + '.py'
 
539
                if os.path.isfile(pypath):
 
540
                    path = pypath
 
541
            return path
 
542
        else:
 
543
            return repr(self.module)
 
544
 
 
545
    def __str__(self):
 
546
        return "<%s.%s object at %s, name=%s, module=%s>" % (
 
547
            self.__class__.__module__, self.__class__.__name__, id(self),
 
548
            self.name, self.module)
 
549
 
 
550
    __repr__ = __str__
 
551
 
 
552
    def test_suite(self):
 
553
        """Return the plugin's test suite."""
 
554
        if getattr(self.module, 'test_suite', None) is not None:
 
555
            return self.module.test_suite()
 
556
        else:
 
557
            return None
 
558
 
 
559
    def load_plugin_tests(self, loader):
 
560
        """Return the adapted plugin's test suite.
 
561
 
 
562
        :param loader: The custom loader that should be used to load additional
 
563
            tests.
 
564
 
 
565
        """
 
566
        if getattr(self.module, 'load_tests', None) is not None:
 
567
            return loader.loadTestsFromModule(self.module)
 
568
        else:
 
569
            return None
 
570
 
 
571
    def version_info(self):
 
572
        """Return the plugin's version_tuple or None if unknown."""
 
573
        version_info = getattr(self.module, 'version_info', None)
 
574
        if version_info is not None:
110
575
            try:
111
 
                plugin_info = imp.find_module(name, [d])
112
 
                mutter('load plugin %r' % (plugin_info,))
113
 
                try:
114
 
                    plugin = imp.load_module('bzrlib.plugins.' + name,
115
 
                                             *plugin_info)
116
 
                    all_plugins.append(plugin)
117
 
                    setattr(bzrlib.plugins, name, plugin)
118
 
                finally:
119
 
                    if plugin_info[0] is not None:
120
 
                        plugin_info[0].close()
121
 
 
122
 
                mutter('loaded succesfully')
123
 
            except:
124
 
                log_error('Unable to load plugin %r from %r' % (name, d))
125
 
                log_exception()
126
 
 
 
576
                if isinstance(version_info, types.StringType):
 
577
                    version_info = version_info.split('.')
 
578
                elif len(version_info) == 3:
 
579
                    version_info = tuple(version_info) + ('final', 0)
 
580
            except TypeError, e:
 
581
                # The given version_info isn't even iteratible
 
582
                trace.log_exception_quietly()
 
583
                version_info = (version_info,)
 
584
        return version_info
 
585
 
 
586
    def _get__version__(self):
 
587
        version_info = self.version_info()
 
588
        if version_info is None or len(version_info) == 0:
 
589
            return "unknown"
 
590
        try:
 
591
            version_string = _format_version_tuple(version_info)
 
592
        except (ValueError, TypeError, IndexError), e:
 
593
            trace.log_exception_quietly()
 
594
            # try to return something usefull for bad plugins, in stead of
 
595
            # stack tracing.
 
596
            version_string = '.'.join(map(str, version_info))
 
597
        return version_string
 
598
 
 
599
    __version__ = property(_get__version__)
 
600
 
 
601
 
 
602
class _PluginImporter(object):
 
603
    """An importer tailored to bzr specific needs.
 
604
 
 
605
    This is a singleton that takes care of:
 
606
    - disabled plugins specified in 'blacklist',
 
607
    - plugins that needs to be loaded from specific directories.
 
608
    """
 
609
 
 
610
    def __init__(self):
 
611
        self.reset()
 
612
 
 
613
    def reset(self):
 
614
        self.blacklist = set()
 
615
        self.specific_paths = {}
 
616
 
 
617
    def find_module(self, fullname, parent_path=None):
 
618
        """Search a plugin module.
 
619
 
 
620
        Disabled plugins raise an import error, plugins with specific paths
 
621
        returns a specific loader.
 
622
 
 
623
        :return: None if the plugin doesn't need special handling, self
 
624
            otherwise.
 
625
        """
 
626
        if not fullname.startswith('bzrlib.plugins.'):
 
627
            return None
 
628
        if fullname in self.blacklist:
 
629
            raise ImportError('%s is disabled' % fullname)
 
630
        if fullname in self.specific_paths:
 
631
            return self
 
632
        return None
 
633
 
 
634
    def load_module(self, fullname):
 
635
        """Load a plugin from a specific directory (or file)."""
 
636
        # We are called only for specific paths
 
637
        plugin_path = self.specific_paths[fullname]
 
638
        loading_path = None
 
639
        if os.path.isdir(plugin_path):
 
640
            for suffix, mode, kind in imp.get_suffixes():
 
641
                if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
 
642
                    # We don't recognize compiled modules (.so, .dll, etc)
 
643
                    continue
 
644
                init_path = osutils.pathjoin(plugin_path, '__init__' + suffix)
 
645
                if os.path.isfile(init_path):
 
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
 
652
                    break
 
653
        else:
 
654
            for suffix, mode, kind in imp.get_suffixes():
 
655
                if plugin_path.endswith(suffix):
 
656
                    loading_path = plugin_path
 
657
                    break
 
658
        if loading_path is None:
 
659
            raise ImportError('%s cannot be loaded from %s'
 
660
                              % (fullname, plugin_path))
 
661
        if kind is imp.PKG_DIRECTORY:
 
662
            f = None
 
663
        else:
 
664
            f = open(loading_path, mode)
 
665
        try:
 
666
            mod = imp.load_module(fullname, f, loading_path,
 
667
                                  (suffix, mode, kind))
 
668
            mod.__package__ = fullname
 
669
            return mod
 
670
        finally:
 
671
            if f is not None:
 
672
                f.close()
 
673
 
 
674
 
 
675
# Install a dedicated importer for plugins requiring special handling
 
676
PluginImporter = _PluginImporter()
 
677
sys.meta_path.append(PluginImporter)