/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 bzrlib/plugin.py

  • Committer: Jelmer Vernooij
  • Date: 2010-04-10 01:22:00 UTC
  • mto: This revision was merged to the branch mainline in revision 5143.
  • Revision ID: jelmer@samba.org-20100410012200-y089oi8jwvx9khyh
Add test for Repository.get_known_graph_ancestry().

Show diffs side-by-side

added added

removed removed

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