~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/plugin.py

  • Committer: Vincent Ladeuil
  • Date: 2010-02-11 09:27:55 UTC
  • mfrom: (5017.3.46 test-servers)
  • mto: This revision was merged to the branch mainline in revision 5030.
  • Revision ID: v.ladeuil+lp@free.fr-20100211092755-3vvu4vbwiwjjte3s
Move tests servers from bzrlib.transport to bzrlib.tests.test_server

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
# Copyright (C) 2004, 2005, 2007, 2008, 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
"""bzr python plugin support.
 
19
 
 
20
When load_plugins() is invoked, any python module in any directory in
 
21
$BZR_PLUGIN_PATH will be imported.  The module will be imported as
 
22
'bzrlib.plugins.$BASENAME(PLUGIN)'.  In the plugin's main body, it should
 
23
update any bzrlib registries it wants to extend.
 
24
 
 
25
See the plugin-api developer documentation for information about writing
 
26
plugins.
 
27
 
 
28
BZR_PLUGIN_PATH is also honoured for any plugins imported via
 
29
'import bzrlib.plugins.PLUGINNAME', as long as set_plugins_path has been
 
30
called.
 
31
"""
 
32
 
 
33
import os
 
34
import sys
 
35
 
 
36
from bzrlib import osutils
 
37
 
 
38
from bzrlib.lazy_import import lazy_import
 
39
 
 
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 import plugins as _mod_plugins
 
53
""")
 
54
 
 
55
from bzrlib.symbol_versioning import (
 
56
    deprecated_function,
 
57
    deprecated_in,
 
58
    )
 
59
 
 
60
 
 
61
DEFAULT_PLUGIN_PATH = None
 
62
_loaded = False
 
63
_plugins_disabled = False
 
64
 
 
65
 
 
66
def are_plugins_disabled():
 
67
    return _plugins_disabled
 
68
 
 
69
 
 
70
@deprecated_function(deprecated_in((2, 0, 0)))
 
71
def get_default_plugin_path():
 
72
    """Get the DEFAULT_PLUGIN_PATH"""
 
73
    global DEFAULT_PLUGIN_PATH
 
74
    if DEFAULT_PLUGIN_PATH is None:
 
75
        DEFAULT_PLUGIN_PATH = osutils.pathjoin(config.config_dir(), 'plugins')
 
76
    return DEFAULT_PLUGIN_PATH
 
77
 
 
78
 
 
79
def disable_plugins():
 
80
    """Disable loading plugins.
 
81
 
 
82
    Future calls to load_plugins() will be ignored.
 
83
    """
 
84
    global _plugins_disabled
 
85
    _plugins_disabled = True
 
86
    load_plugins([])
 
87
 
 
88
 
 
89
def _strip_trailing_sep(path):
 
90
    return path.rstrip("\\/")
 
91
 
 
92
 
 
93
def set_plugins_path(path=None):
 
94
    """Set the path for plugins to be loaded from.
 
95
 
 
96
    :param path: The list of paths to search for plugins.  By default,
 
97
        path will be determined using get_standard_plugins_path.
 
98
        if path is [], no plugins can be loaded.
 
99
    """
 
100
    if path is None:
 
101
        path = get_standard_plugins_path()
 
102
    _mod_plugins.__path__ = path
 
103
    return path
 
104
 
 
105
 
 
106
def _append_new_path(paths, new_path):
 
107
    """Append a new path if it set and not already known."""
 
108
    if new_path is not None and new_path not in paths:
 
109
        paths.append(new_path)
 
110
    return paths
 
111
 
 
112
 
 
113
def get_core_plugin_path():
 
114
    core_path = None
 
115
    bzr_exe = bool(getattr(sys, 'frozen', None))
 
116
    if bzr_exe:    # expand path for bzr.exe
 
117
        # We need to use relative path to system-wide plugin
 
118
        # directory because bzrlib from standalone bzr.exe
 
119
        # could be imported by another standalone program
 
120
        # (e.g. bzr-config; or TortoiseBzr/Olive if/when they
 
121
        # will become standalone exe). [bialix 20071123]
 
122
        # __file__ typically is
 
123
        # C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
 
124
        # then plugins directory is
 
125
        # C:\Program Files\Bazaar\plugins
 
126
        # so relative path is ../../../plugins
 
127
        core_path = osutils.abspath(osutils.pathjoin(
 
128
                osutils.dirname(__file__), '../../../plugins'))
 
129
    else:     # don't look inside library.zip
 
130
        # search the plugin path before the bzrlib installed dir
 
131
        core_path = os.path.dirname(_mod_plugins.__file__)
 
132
    return core_path
 
133
 
 
134
 
 
135
def get_site_plugin_path():
 
136
    """Returns the path for the site installed plugins."""
 
137
    if sys.platform == 'win32':
 
138
        # We don't have (yet) a good answer for windows since that is certainly
 
139
        # related to the way we build the installers. -- vila20090821
 
140
        return None
 
141
    site_path = None
 
142
    try:
 
143
        from distutils.sysconfig import get_python_lib
 
144
    except ImportError:
 
145
        # If distutuils is not available, we just don't know where they are
 
146
        pass
 
147
    else:
 
148
        site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
 
149
    return site_path
 
150
 
 
151
 
 
152
def get_user_plugin_path():
 
153
    return osutils.pathjoin(config.config_dir(), 'plugins')
 
154
 
 
155
 
 
156
def get_standard_plugins_path():
 
157
    """Determine a plugin path suitable for general use."""
 
158
    # Ad-Hoc default: core is not overriden by site but user can overrides both
 
159
    # The rationale is that:
 
160
    # - 'site' comes last, because these plugins should always be available and
 
161
    #   are supposed to be in sync with the bzr installed on site.
 
162
    # - 'core' comes before 'site' so that running bzr from sources or a user
 
163
    #   installed version overrides the site version.
 
164
    # - 'user' comes first, because... user is always right.
 
165
    # - the above rules clearly defines which plugin version will be loaded if
 
166
    #   several exist. Yet, it is sometimes desirable to disable some directory
 
167
    #   so that a set of plugins is disabled as once. This can be done via
 
168
    #   -site, -core, -user.
 
169
 
 
170
    env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
 
171
    defaults = ['+core', '+site']
 
172
 
 
173
    # The predefined references
 
174
    refs = dict(core=get_core_plugin_path(),
 
175
                site=get_site_plugin_path(),
 
176
                user=get_user_plugin_path())
 
177
 
 
178
    # Unset paths that should be removed
 
179
    for k,v in refs.iteritems():
 
180
        removed = '-%s' % k
 
181
        # defaults can never mention removing paths as that will make it
 
182
        # impossible for the user to revoke these removals.
 
183
        if removed in env_paths:
 
184
            env_paths.remove(removed)
 
185
            refs[k] = None
 
186
 
 
187
    # Expand references
 
188
    paths = []
 
189
    for p in env_paths + defaults:
 
190
        if p.startswith('+'):
 
191
            # Resolve reference if they are known
 
192
            try:
 
193
                p = refs[p[1:]]
 
194
            except KeyError:
 
195
                # Leave them untouched otherwise, user may have paths starting
 
196
                # with '+'...
 
197
                pass
 
198
        _append_new_path(paths, p)
 
199
 
 
200
    # Get rid of trailing slashes, since Python can't handle them when
 
201
    # it tries to import modules.
 
202
    paths = map(_strip_trailing_sep, paths)
 
203
    return paths
 
204
 
 
205
 
 
206
def load_plugins(path=None):
 
207
    """Load bzrlib plugins.
 
208
 
 
209
    The environment variable BZR_PLUGIN_PATH is considered a delimited
 
210
    set of paths to look through. Each entry is searched for *.py
 
211
    files (and whatever other extensions are used in the platform,
 
212
    such as *.pyd).
 
213
 
 
214
    load_from_dirs() provides the underlying mechanism and is called with
 
215
    the default directory list to provide the normal behaviour.
 
216
 
 
217
    :param path: The list of paths to search for plugins.  By default,
 
218
        path will be determined using get_standard_plugins_path.
 
219
        if path is [], no plugins can be loaded.
 
220
    """
 
221
    global _loaded
 
222
    if _loaded:
 
223
        # People can make sure plugins are loaded, they just won't be twice
 
224
        return
 
225
    _loaded = True
 
226
 
 
227
    # scan for all plugins in the path.
 
228
    load_from_path(set_plugins_path(path))
 
229
 
 
230
 
 
231
def load_from_path(dirs):
 
232
    """Load bzrlib plugins found in each dir in dirs.
 
233
 
 
234
    Loading a plugin means importing it into the python interpreter.
 
235
    The plugin is expected to make calls to register commands when
 
236
    it's loaded (or perhaps access other hooks in future.)
 
237
 
 
238
    Plugins are loaded into bzrlib.plugins.NAME, and can be found there
 
239
    for future reference.
 
240
 
 
241
    The python module path for bzrlib.plugins will be modified to be 'dirs'.
 
242
    """
 
243
    # We need to strip the trailing separators here as well as in the
 
244
    # set_plugins_path function because calling code can pass anything in to
 
245
    # this function, and since it sets plugins.__path__, it should set it to
 
246
    # something that will be valid for Python to use (in case people try to
 
247
    # run "import bzrlib.plugins.PLUGINNAME" after calling this function).
 
248
    _mod_plugins.__path__ = map(_strip_trailing_sep, dirs)
 
249
    for d in dirs:
 
250
        if not d:
 
251
            continue
 
252
        trace.mutter('looking for plugins in %s', d)
 
253
        if os.path.isdir(d):
 
254
            load_from_dir(d)
 
255
 
 
256
 
 
257
# backwards compatability: load_from_dirs was the old name
 
258
# This was changed in 0.15
 
259
load_from_dirs = load_from_path
 
260
 
 
261
 
 
262
def load_from_dir(d):
 
263
    """Load the plugins in directory d.
 
264
 
 
265
    d must be in the plugins module path already.
 
266
    """
 
267
    # Get the list of valid python suffixes for __init__.py?
 
268
    # this includes .py, .pyc, and .pyo (depending on if we are running -O)
 
269
    # but it doesn't include compiled modules (.so, .dll, etc)
 
270
    valid_suffixes = [suffix for suffix, mod_type, flags in imp.get_suffixes()
 
271
                              if flags in (imp.PY_SOURCE, imp.PY_COMPILED)]
 
272
    package_entries = ['__init__'+suffix for suffix in valid_suffixes]
 
273
    plugin_names = set()
 
274
    for f in os.listdir(d):
 
275
        path = osutils.pathjoin(d, f)
 
276
        if os.path.isdir(path):
 
277
            for entry in package_entries:
 
278
                # This directory should be a package, and thus added to
 
279
                # the list
 
280
                if os.path.isfile(osutils.pathjoin(path, entry)):
 
281
                    break
 
282
            else: # This directory is not a package
 
283
                continue
 
284
        else:
 
285
            for suffix_info in imp.get_suffixes():
 
286
                if f.endswith(suffix_info[0]):
 
287
                    f = f[:-len(suffix_info[0])]
 
288
                    if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
 
289
                        f = f[:-len('module')]
 
290
                    break
 
291
            else:
 
292
                continue
 
293
        if f == '__init__':
 
294
            continue # We don't load __init__.py again in the plugin dir
 
295
        elif getattr(_mod_plugins, f, None):
 
296
            trace.mutter('Plugin name %s already loaded', f)
 
297
        else:
 
298
            # trace.mutter('add plugin name %s', f)
 
299
            plugin_names.add(f)
 
300
 
 
301
    for name in plugin_names:
 
302
        try:
 
303
            exec "import bzrlib.plugins.%s" % name in {}
 
304
        except KeyboardInterrupt:
 
305
            raise
 
306
        except errors.IncompatibleAPI, e:
 
307
            trace.warning("Unable to load plugin %r. It requested API version "
 
308
                "%s of module %s but the minimum exported version is %s, and "
 
309
                "the maximum is %s" %
 
310
                (name, e.wanted, e.api, e.minimum, e.current))
 
311
        except Exception, e:
 
312
            trace.warning("%s" % e)
 
313
            ## import pdb; pdb.set_trace()
 
314
            if re.search('\.|-| ', name):
 
315
                sanitised_name = re.sub('[-. ]', '_', name)
 
316
                if sanitised_name.startswith('bzr_'):
 
317
                    sanitised_name = sanitised_name[len('bzr_'):]
 
318
                trace.warning("Unable to load %r in %r as a plugin because the "
 
319
                        "file path isn't a valid module name; try renaming "
 
320
                        "it to %r." % (name, d, sanitised_name))
 
321
            else:
 
322
                trace.warning('Unable to load plugin %r from %r' % (name, d))
 
323
            trace.log_exception_quietly()
 
324
            if 'error' in debug.debug_flags:
 
325
                trace.print_exception(sys.exc_info(), sys.stderr)
 
326
 
 
327
 
 
328
def plugins():
 
329
    """Return a dictionary of the plugins.
 
330
 
 
331
    Each item in the dictionary is a PlugIn object.
 
332
    """
 
333
    result = {}
 
334
    for name, plugin in _mod_plugins.__dict__.items():
 
335
        if isinstance(plugin, types.ModuleType):
 
336
            result[name] = PlugIn(name, plugin)
 
337
    return result
 
338
 
 
339
 
 
340
class PluginsHelpIndex(object):
 
341
    """A help index that returns help topics for plugins."""
 
342
 
 
343
    def __init__(self):
 
344
        self.prefix = 'plugins/'
 
345
 
 
346
    def get_topics(self, topic):
 
347
        """Search for topic in the loaded plugins.
 
348
 
 
349
        This will not trigger loading of new plugins.
 
350
 
 
351
        :param topic: A topic to search for.
 
352
        :return: A list which is either empty or contains a single
 
353
            RegisteredTopic entry.
 
354
        """
 
355
        if not topic:
 
356
            return []
 
357
        if topic.startswith(self.prefix):
 
358
            topic = topic[len(self.prefix):]
 
359
        plugin_module_name = 'bzrlib.plugins.%s' % topic
 
360
        try:
 
361
            module = sys.modules[plugin_module_name]
 
362
        except KeyError:
 
363
            return []
 
364
        else:
 
365
            return [ModuleHelpTopic(module)]
 
366
 
 
367
 
 
368
class ModuleHelpTopic(object):
 
369
    """A help topic which returns the docstring for a module."""
 
370
 
 
371
    def __init__(self, module):
 
372
        """Constructor.
 
373
 
 
374
        :param module: The module for which help should be generated.
 
375
        """
 
376
        self.module = module
 
377
 
 
378
    def get_help_text(self, additional_see_also=None, verbose=True):
 
379
        """Return a string with the help for this topic.
 
380
 
 
381
        :param additional_see_also: Additional help topics to be
 
382
            cross-referenced.
 
383
        """
 
384
        if not self.module.__doc__:
 
385
            result = "Plugin '%s' has no docstring.\n" % self.module.__name__
 
386
        else:
 
387
            result = self.module.__doc__
 
388
        if result[-1] != '\n':
 
389
            result += '\n'
 
390
        # there is code duplicated here and in bzrlib/help_topic.py's
 
391
        # matching Topic code. This should probably be factored in
 
392
        # to a helper function and a common base class.
 
393
        if additional_see_also is not None:
 
394
            see_also = sorted(set(additional_see_also))
 
395
        else:
 
396
            see_also = None
 
397
        if see_also:
 
398
            result += 'See also: '
 
399
            result += ', '.join(see_also)
 
400
            result += '\n'
 
401
        return result
 
402
 
 
403
    def get_help_topic(self):
 
404
        """Return the modules help topic - its __name__ after bzrlib.plugins.."""
 
405
        return self.module.__name__[len('bzrlib.plugins.'):]
 
406
 
 
407
 
 
408
class PlugIn(object):
 
409
    """The bzrlib representation of a plugin.
 
410
 
 
411
    The PlugIn object provides a way to manipulate a given plugin module.
 
412
    """
 
413
 
 
414
    def __init__(self, name, module):
 
415
        """Construct a plugin for module."""
 
416
        self.name = name
 
417
        self.module = module
 
418
 
 
419
    def path(self):
 
420
        """Get the path that this plugin was loaded from."""
 
421
        if getattr(self.module, '__path__', None) is not None:
 
422
            return os.path.abspath(self.module.__path__[0])
 
423
        elif getattr(self.module, '__file__', None) is not None:
 
424
            path = os.path.abspath(self.module.__file__)
 
425
            if path[-4:] in ('.pyc', '.pyo'):
 
426
                pypath = path[:-4] + '.py'
 
427
                if os.path.isfile(pypath):
 
428
                    path = pypath
 
429
            return path
 
430
        else:
 
431
            return repr(self.module)
 
432
 
 
433
    def __str__(self):
 
434
        return "<%s.%s object at %s, name=%s, module=%s>" % (
 
435
            self.__class__.__module__, self.__class__.__name__, id(self),
 
436
            self.name, self.module)
 
437
 
 
438
    __repr__ = __str__
 
439
 
 
440
    def test_suite(self):
 
441
        """Return the plugin's test suite."""
 
442
        if getattr(self.module, 'test_suite', None) is not None:
 
443
            return self.module.test_suite()
 
444
        else:
 
445
            return None
 
446
 
 
447
    def load_plugin_tests(self, loader):
 
448
        """Return the adapted plugin's test suite.
 
449
 
 
450
        :param loader: The custom loader that should be used to load additional
 
451
            tests.
 
452
 
 
453
        """
 
454
        if getattr(self.module, 'load_tests', None) is not None:
 
455
            return loader.loadTestsFromModule(self.module)
 
456
        else:
 
457
            return None
 
458
 
 
459
    def version_info(self):
 
460
        """Return the plugin's version_tuple or None if unknown."""
 
461
        version_info = getattr(self.module, 'version_info', None)
 
462
        if version_info is not None:
 
463
            try:
 
464
                if isinstance(version_info, types.StringType):
 
465
                    version_info = version_info.split('.')
 
466
                elif len(version_info) == 3:
 
467
                    version_info = tuple(version_info) + ('final', 0)
 
468
            except TypeError, e:
 
469
                # The given version_info isn't even iteratible
 
470
                trace.log_exception_quietly()
 
471
                version_info = (version_info,)
 
472
        return version_info
 
473
 
 
474
    def _get__version__(self):
 
475
        version_info = self.version_info()
 
476
        if version_info is None or len(version_info) == 0:
 
477
            return "unknown"
 
478
        try:
 
479
            version_string = _format_version_tuple(version_info)
 
480
        except (ValueError, TypeError, IndexError), e:
 
481
            trace.log_exception_quietly()
 
482
            # try to return something usefull for bad plugins, in stead of
 
483
            # stack tracing.
 
484
            version_string = '.'.join(map(str, version_info))
 
485
        return version_string
 
486
 
 
487
    __version__ = property(_get__version__)