~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/plugin.py

[merge] fix \t in commit messages

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2004, 2005, 2007, 2008 Canonical Ltd
2
 
#
 
1
# Copyright (C) 2004, 2005 by 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
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
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.
 
18
"""bzr python plugin support
 
19
 
 
20
Any python module in $BZR_PLUGIN_PATH will be imported upon initialization of
 
21
bzrlib. The module will be imported as 'bzrlib.plugins.$BASENAME(PLUGIN)'.
 
22
In the plugin's main body, it should update any bzrlib registries it wants to
 
23
extend; for example, to add new commands, import bzrlib.commands and add your
 
24
new command to the plugin_cmds variable.
31
25
"""
32
26
 
 
27
# TODO: Refactor this to make it more testable.  The main problem at the
 
28
# moment is that loading plugins affects the global process state -- for bzr
 
29
# in general use it's a reasonable assumption that all plugins are loaded at
 
30
# startup and then stay loaded, but this is less good for testing.
 
31
 
32
# Several specific issues:
 
33
#  - plugins can't be unloaded and will continue to effect later tests
 
34
#  - load_plugins does nothing if called a second time
 
35
#  - plugin hooks can't be removed
 
36
#
 
37
# Our options are either to remove these restrictions, or work around them by
 
38
# loading the plugins into a different space than the one running the tests.
 
39
# That could be either a separate Python interpreter or perhaps a new
 
40
# namespace inside this interpreter.
 
41
 
 
42
import imp
33
43
import os
34
44
import sys
35
45
 
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
 
import zipfile
45
 
 
46
 
from bzrlib import (
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 deprecated_function, one_three
56
 
 
57
 
 
58
 
DEFAULT_PLUGIN_PATH = None
 
46
import bzrlib
 
47
from bzrlib.config import config_dir
 
48
from bzrlib.trace import log_error, mutter, log_exception, warning, \
 
49
        log_exception_quietly
 
50
from bzrlib.errors import BzrError
 
51
from bzrlib import plugins
 
52
 
 
53
DEFAULT_PLUGIN_PATH = os.path.join(config_dir(), 'plugins')
 
54
 
 
55
all_plugins = []
59
56
_loaded = False
60
57
 
61
 
def get_default_plugin_path():
62
 
    """Get the DEFAULT_PLUGIN_PATH"""
63
 
    global DEFAULT_PLUGIN_PATH
64
 
    if DEFAULT_PLUGIN_PATH is None:
65
 
        DEFAULT_PLUGIN_PATH = osutils.pathjoin(config.config_dir(), 'plugins')
66
 
    return DEFAULT_PLUGIN_PATH
67
 
 
68
 
 
69
 
def disable_plugins():
70
 
    """Disable loading plugins.
71
 
 
72
 
    Future calls to load_plugins() will be ignored.
73
 
    """
74
 
    # TODO: jam 20060131 This should probably also disable
75
 
    #       load_from_dirs()
76
 
    global _loaded
77
 
    _loaded = True
78
 
 
79
 
 
80
 
def _strip_trailing_sep(path):
81
 
    return path.rstrip("\\/")
82
 
 
83
 
 
84
 
def set_plugins_path():
85
 
    """Set the path for plugins to be loaded from."""
86
 
    path = os.environ.get('BZR_PLUGIN_PATH',
87
 
                          get_default_plugin_path()).split(os.pathsep)
88
 
    bzr_exe = bool(getattr(sys, 'frozen', None))
89
 
    if bzr_exe:    # expand path for bzr.exe
90
 
        # We need to use relative path to system-wide plugin
91
 
        # directory because bzrlib from standalone bzr.exe
92
 
        # could be imported by another standalone program
93
 
        # (e.g. bzr-config; or TortoiseBzr/Olive if/when they
94
 
        # will become standalone exe). [bialix 20071123]
95
 
        # __file__ typically is
96
 
        # C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
97
 
        # then plugins directory is
98
 
        # C:\Program Files\Bazaar\plugins
99
 
        # so relative path is ../../../plugins
100
 
        path.append(osutils.abspath(osutils.pathjoin(
101
 
            osutils.dirname(__file__), '../../../plugins')))
102
 
    # Get rid of trailing slashes, since Python can't handle them when
103
 
    # it tries to import modules.
104
 
    path = map(_strip_trailing_sep, path)
105
 
    if not bzr_exe:     # don't look inside library.zip
106
 
        # search the plugin path before the bzrlib installed dir
107
 
        path.append(os.path.dirname(_mod_plugins.__file__))
108
 
    # search the arch independent path if we can determine that and
109
 
    # the plugin is found nowhere else
110
 
    if sys.platform != 'win32':
111
 
        try:
112
 
            from distutils.sysconfig import get_python_lib
113
 
        except ImportError:
114
 
            # If distutuils is not available, we just won't add that path
115
 
            pass
116
 
        else:
117
 
            archless_path = osutils.pathjoin(get_python_lib(), 'bzrlib',
118
 
                    'plugins')
119
 
            if archless_path not in path:
120
 
                path.append(archless_path)
121
 
    _mod_plugins.__path__ = path
122
 
    return path
123
 
 
124
58
 
125
59
def load_plugins():
126
 
    """Load bzrlib plugins.
 
60
    """Find all python plugins and load them.
 
61
 
 
62
    Loading a plugin means importing it into the python interpreter.
 
63
    The plugin is expected to make calls to register commands when
 
64
    it's loaded (or perhaps access other hooks in future.)
 
65
 
 
66
    A list of plugs is stored in bzrlib.plugin.all_plugins for future
 
67
    reference.
127
68
 
128
69
    The environment variable BZR_PLUGIN_PATH is considered a delimited
129
70
    set of paths to look through. Each entry is searched for *.py
130
71
    files (and whatever other extensions are used in the platform,
131
72
    such as *.pyd).
 
73
    """
132
74
 
133
 
    load_from_dirs() provides the underlying mechanism and is called with
134
 
    the default directory list to provide the normal behaviour.
135
 
    """
136
 
    global _loaded
 
75
    global all_plugins, _loaded
137
76
    if _loaded:
138
77
        # People can make sure plugins are loaded, they just won't be twice
139
78
        return
 
79
        #raise BzrError("plugins already initialized")
140
80
    _loaded = True
141
81
 
142
 
    # scan for all plugins in the path.
143
 
    load_from_path(set_plugins_path())
144
 
 
145
 
 
146
 
def load_from_path(dirs):
147
 
    """Load bzrlib plugins found in each dir in dirs.
148
 
 
149
 
    Loading a plugin means importing it into the python interpreter.
150
 
    The plugin is expected to make calls to register commands when
151
 
    it's loaded (or perhaps access other hooks in future.)
152
 
 
153
 
    Plugins are loaded into bzrlib.plugins.NAME, and can be found there
154
 
    for future reference.
155
 
 
156
 
    The python module path for bzrlib.plugins will be modified to be 'dirs'.
157
 
    """
158
 
    # We need to strip the trailing separators here as well as in the
159
 
    # set_plugins_path function because calling code can pass anything in to
160
 
    # this function, and since it sets plugins.__path__, it should set it to
161
 
    # something that will be valid for Python to use (in case people try to
162
 
    # run "import bzrlib.plugins.PLUGINNAME" after calling this function).
163
 
    _mod_plugins.__path__ = map(_strip_trailing_sep, dirs)
 
82
    dirs = os.environ.get('BZR_PLUGIN_PATH', DEFAULT_PLUGIN_PATH).split(":")
 
83
    dirs.insert(0, os.path.dirname(plugins.__file__))
 
84
 
 
85
    # The problem with imp.get_suffixes() is that it doesn't include
 
86
    # .pyo which is technically valid
 
87
    # It also means that "testmodule.so" will show up as both test and testmodule
 
88
    # though it is only valid as 'test'
 
89
    # but you should be careful, because "testmodule.py" loads as testmodule.
 
90
    suffixes = imp.get_suffixes()
 
91
    suffixes.append(('.pyo', 'rb', imp.PY_COMPILED))
 
92
    package_entries = ['__init__.py', '__init__.pyc', '__init__.pyo']
164
93
    for d in dirs:
 
94
        # going through them one by one allows different plugins with the same
 
95
        # filename in different directories in the path
 
96
        mutter('looking for plugins in %s', d)
165
97
        if not d:
166
98
            continue
167
 
        trace.mutter('looking for plugins in %s', d)
168
 
        if os.path.isdir(d):
169
 
            load_from_dir(d)
170
 
 
171
 
 
172
 
# backwards compatability: load_from_dirs was the old name
173
 
# This was changed in 0.15
174
 
load_from_dirs = load_from_path
175
 
 
176
 
 
177
 
def load_from_dir(d):
178
 
    """Load the plugins in directory d.
179
 
    
180
 
    d must be in the plugins module path already.
181
 
    """
182
 
    # Get the list of valid python suffixes for __init__.py?
183
 
    # this includes .py, .pyc, and .pyo (depending on if we are running -O)
184
 
    # but it doesn't include compiled modules (.so, .dll, etc)
185
 
    valid_suffixes = [suffix for suffix, mod_type, flags in imp.get_suffixes()
186
 
                              if flags in (imp.PY_SOURCE, imp.PY_COMPILED)]
187
 
    package_entries = ['__init__'+suffix for suffix in valid_suffixes]
188
 
    plugin_names = set()
189
 
    for f in os.listdir(d):
190
 
        path = osutils.pathjoin(d, f)
191
 
        if os.path.isdir(path):
192
 
            for entry in package_entries:
193
 
                # This directory should be a package, and thus added to
194
 
                # the list
195
 
                if os.path.isfile(osutils.pathjoin(path, entry)):
196
 
                    break
197
 
            else: # This directory is not a package
198
 
                continue
199
 
        else:
200
 
            for suffix_info in imp.get_suffixes():
201
 
                if f.endswith(suffix_info[0]):
202
 
                    f = f[:-len(suffix_info[0])]
203
 
                    if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
204
 
                        f = f[:-len('module')]
205
 
                    break
 
99
        plugin_names = set()
 
100
        if not os.path.isdir(d):
 
101
            continue
 
102
        for f in os.listdir(d):
 
103
            path = os.path.join(d, f)
 
104
            if os.path.isdir(path):
 
105
                for entry in package_entries:
 
106
                    # This directory should be a package, and thus added to
 
107
                    # the list
 
108
                    if os.path.isfile(os.path.join(path, entry)):
 
109
                        break
 
110
                else: # This directory is not a package
 
111
                    continue
206
112
            else:
207
 
                continue
208
 
        if f == '__init__':
209
 
            continue # We don't load __init__.py again in the plugin dir
210
 
        elif getattr(_mod_plugins, f, None):
211
 
            trace.mutter('Plugin name %s already loaded', f)
212
 
        else:
213
 
            # trace.mutter('add plugin name %s', f)
 
113
                for suffix_info in suffixes:
 
114
                    if f.endswith(suffix_info[0]):
 
115
                        f = f[:-len(suffix_info[0])]
 
116
                        if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
 
117
                            f = f[:-len('module')]
 
118
                        break
 
119
                else:
 
120
                    continue
 
121
            mutter('add plugin name %s', f)
214
122
            plugin_names.add(f)
215
 
    
216
 
    for name in plugin_names:
217
 
        try:
218
 
            exec "import bzrlib.plugins.%s" % name in {}
219
 
        except KeyboardInterrupt:
220
 
            raise
221
 
        except errors.IncompatibleAPI, e:
222
 
            trace.warning("Unable to load plugin %r. It requested API version "
223
 
                "%s of module %s but the minimum exported version is %s, and "
224
 
                "the maximum is %s" %
225
 
                (name, e.wanted, e.api, e.minimum, e.current))
226
 
        except Exception, e:
227
 
            trace.warning("%s" % e)
228
 
            ## import pdb; pdb.set_trace()
229
 
            if re.search('\.|-| ', name):
230
 
                sanitised_name = re.sub('[-. ]', '_', name)
231
 
                if sanitised_name.startswith('bzr_'):
232
 
                    sanitised_name = sanitised_name[len('bzr_'):]
233
 
                trace.warning("Unable to load %r in %r as a plugin because the "
234
 
                        "file path isn't a valid module name; try renaming "
235
 
                        "it to %r." % (name, d, sanitised_name))
236
 
            else:
237
 
                trace.warning('Unable to load plugin %r from %r' % (name, d))
238
 
            trace.log_exception_quietly()
239
 
            if 'error' in debug.debug_flags:
240
 
                trace.print_exception(sys.exc_info(), sys.stderr)
241
 
 
242
 
 
243
 
@deprecated_function(one_three)
244
 
def load_from_zip(zip_name):
245
 
    """Load all the plugins in a zip."""
246
 
    valid_suffixes = ('.py', '.pyc', '.pyo')    # only python modules/packages
247
 
                                                # is allowed
248
 
    try:
249
 
        index = zip_name.rindex('.zip')
250
 
    except ValueError:
251
 
        return
252
 
    archive = zip_name[:index+4]
253
 
    prefix = zip_name[index+5:]
254
 
 
255
 
    trace.mutter('Looking for plugins in %r', zip_name)
256
 
 
257
 
    # use zipfile to get list of files/dirs inside zip
258
 
    try:
259
 
        z = zipfile.ZipFile(archive)
260
 
        namelist = z.namelist()
261
 
        z.close()
262
 
    except zipfile.error:
263
 
        # not a valid zip
264
 
        return
265
 
 
266
 
    if prefix:
267
 
        prefix = prefix.replace('\\','/')
268
 
        if prefix[-1] != '/':
269
 
            prefix += '/'
270
 
        ix = len(prefix)
271
 
        namelist = [name[ix:]
272
 
                    for name in namelist
273
 
                    if name.startswith(prefix)]
274
 
 
275
 
    trace.mutter('Names in archive: %r', namelist)
276
 
    
277
 
    for name in namelist:
278
 
        if not name or name.endswith('/'):
279
 
            continue
280
 
    
281
 
        # '/' is used to separate pathname components inside zip archives
282
 
        ix = name.rfind('/')
283
 
        if ix == -1:
284
 
            head, tail = '', name
285
 
        else:
286
 
            head, tail = name.rsplit('/',1)
287
 
        if '/' in head:
288
 
            # we don't need looking in subdirectories
289
 
            continue
290
 
    
291
 
        base, suffix = osutils.splitext(tail)
292
 
        if suffix not in valid_suffixes:
293
 
            continue
294
 
    
295
 
        if base == '__init__':
296
 
            # package
297
 
            plugin_name = head
298
 
        elif head == '':
299
 
            # module
300
 
            plugin_name = base
301
 
        else:
302
 
            continue
303
 
    
304
 
        if not plugin_name:
305
 
            continue
306
 
        if getattr(_mod_plugins, plugin_name, None):
307
 
            trace.mutter('Plugin name %s already loaded', plugin_name)
308
 
            continue
309
 
    
310
 
        try:
311
 
            exec "import bzrlib.plugins.%s" % plugin_name in {}
312
 
            trace.mutter('Load plugin %s from zip %r', plugin_name, zip_name)
313
 
        except KeyboardInterrupt:
314
 
            raise
315
 
        except Exception, e:
316
 
            ## import pdb; pdb.set_trace()
317
 
            trace.warning('Unable to load plugin %r from %r'
318
 
                    % (name, zip_name))
319
 
            trace.log_exception_quietly()
320
 
            if 'error' in debug.debug_flags:
321
 
                trace.print_exception(sys.exc_info(), sys.stderr)
322
 
 
323
 
 
324
 
def plugins():
325
 
    """Return a dictionary of the plugins.
326
 
    
327
 
    Each item in the dictionary is a PlugIn object.
328
 
    """
329
 
    result = {}
330
 
    for name, plugin in _mod_plugins.__dict__.items():
331
 
        if isinstance(plugin, types.ModuleType):
332
 
            result[name] = PlugIn(name, plugin)
333
 
    return result
334
 
 
335
 
 
336
 
class PluginsHelpIndex(object):
337
 
    """A help index that returns help topics for plugins."""
338
 
 
339
 
    def __init__(self):
340
 
        self.prefix = 'plugins/'
341
 
 
342
 
    def get_topics(self, topic):
343
 
        """Search for topic in the loaded plugins.
344
 
 
345
 
        This will not trigger loading of new plugins.
346
 
 
347
 
        :param topic: A topic to search for.
348
 
        :return: A list which is either empty or contains a single
349
 
            RegisteredTopic entry.
350
 
        """
351
 
        if not topic:
352
 
            return []
353
 
        if topic.startswith(self.prefix):
354
 
            topic = topic[len(self.prefix):]
355
 
        plugin_module_name = 'bzrlib.plugins.%s' % topic
356
 
        try:
357
 
            module = sys.modules[plugin_module_name]
358
 
        except KeyError:
359
 
            return []
360
 
        else:
361
 
            return [ModuleHelpTopic(module)]
362
 
 
363
 
 
364
 
class ModuleHelpTopic(object):
365
 
    """A help topic which returns the docstring for a module."""
366
 
 
367
 
    def __init__(self, module):
368
 
        """Constructor.
369
 
 
370
 
        :param module: The module for which help should be generated.
371
 
        """
372
 
        self.module = module
373
 
 
374
 
    def get_help_text(self, additional_see_also=None):
375
 
        """Return a string with the help for this topic.
376
 
 
377
 
        :param additional_see_also: Additional help topics to be
378
 
            cross-referenced.
379
 
        """
380
 
        if not self.module.__doc__:
381
 
            result = "Plugin '%s' has no docstring.\n" % self.module.__name__
382
 
        else:
383
 
            result = self.module.__doc__
384
 
        if result[-1] != '\n':
385
 
            result += '\n'
386
 
        # there is code duplicated here and in bzrlib/help_topic.py's 
387
 
        # matching Topic code. This should probably be factored in
388
 
        # to a helper function and a common base class.
389
 
        if additional_see_also is not None:
390
 
            see_also = sorted(set(additional_see_also))
391
 
        else:
392
 
            see_also = None
393
 
        if see_also:
394
 
            result += 'See also: '
395
 
            result += ', '.join(see_also)
396
 
            result += '\n'
397
 
        return result
398
 
 
399
 
    def get_help_topic(self):
400
 
        """Return the modules help topic - its __name__ after bzrlib.plugins.."""
401
 
        return self.module.__name__[len('bzrlib.plugins.'):]
402
 
 
403
 
 
404
 
class PlugIn(object):
405
 
    """The bzrlib representation of a plugin.
406
 
 
407
 
    The PlugIn object provides a way to manipulate a given plugin module.
408
 
    """
409
 
 
410
 
    def __init__(self, name, module):
411
 
        """Construct a plugin for module."""
412
 
        self.name = name
413
 
        self.module = module
414
 
 
415
 
    def path(self):
416
 
        """Get the path that this plugin was loaded from."""
417
 
        if getattr(self.module, '__path__', None) is not None:
418
 
            return os.path.abspath(self.module.__path__[0])
419
 
        elif getattr(self.module, '__file__', None) is not None:
420
 
            path = os.path.abspath(self.module.__file__)
421
 
            if path[-4:] in ('.pyc', '.pyo'):
422
 
                pypath = path[:-4] + '.py'
423
 
                if os.path.isfile(pypath):
424
 
                    path = pypath
425
 
            return path
426
 
        else:
427
 
            return repr(self.module)
428
 
 
429
 
    def __str__(self):
430
 
        return "<%s.%s object at %s, name=%s, module=%s>" % (
431
 
            self.__class__.__module__, self.__class__.__name__, id(self),
432
 
            self.name, self.module)
433
 
 
434
 
    __repr__ = __str__
435
 
 
436
 
    def test_suite(self):
437
 
        """Return the plugin's test suite."""
438
 
        if getattr(self.module, 'test_suite', None) is not None:
439
 
            return self.module.test_suite()
440
 
        else:
441
 
            return None
442
 
 
443
 
    def load_plugin_tests(self, loader):
444
 
        """Return the adapted plugin's test suite.
445
 
 
446
 
        :param loader: The custom loader that should be used to load additional
447
 
            tests.
448
 
 
449
 
        """
450
 
        if getattr(self.module, 'load_tests', None) is not None:
451
 
            return loader.loadTestsFromModule(self.module)
452
 
        else:
453
 
            return None
454
 
 
455
 
    def version_info(self):
456
 
        """Return the plugin's version_tuple or None if unknown."""
457
 
        version_info = getattr(self.module, 'version_info', None)
458
 
        if version_info is not None and len(version_info) == 3:
459
 
            version_info = tuple(version_info) + ('final', 0)
460
 
        return version_info
461
 
 
462
 
    def _get__version__(self):
463
 
        version_info = self.version_info()
464
 
        if version_info is None:
465
 
            return "unknown"
466
 
        if version_info[3] == 'final':
467
 
            version_string = '%d.%d.%d' % version_info[:3]
468
 
        else:
469
 
            version_string = '%d.%d.%d%s%d' % version_info
470
 
        return version_string
471
 
 
472
 
    __version__ = property(_get__version__)
 
123
 
 
124
        plugin_names = list(plugin_names)
 
125
        plugin_names.sort()
 
126
        for name in plugin_names:
 
127
            try:
 
128
                plugin_info = imp.find_module(name, [d])
 
129
                mutter('load plugin %r', plugin_info)
 
130
                try:
 
131
                    plugin = imp.load_module('bzrlib.plugins.' + name,
 
132
                                             *plugin_info)
 
133
                    all_plugins.append(plugin)
 
134
                    setattr(bzrlib.plugins, name, plugin)
 
135
                finally:
 
136
                    if plugin_info[0] is not None:
 
137
                        plugin_info[0].close()
 
138
 
 
139
                mutter('loaded succesfully')
 
140
            except KeyboardInterrupt:
 
141
                raise
 
142
            except Exception, e:
 
143
                ## import pdb; pdb.set_trace()
 
144
                warning('Unable to load plugin %r from %r' % (name, d))
 
145
                log_exception_quietly()