/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: Martin Pool
  • Date: 2008-10-29 06:10:45 UTC
  • mfrom: (3786.1.2 doc-hooks)
  • mto: This revision was merged to the branch mainline in revision 3806.
  • Revision ID: mbp@sourcefrog.net-20081029061045-q8fpbt0v1bdag0mt
Merge and tweak hook documentation

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/plugin.py
 
1
# Copyright (C) 2004, 2005, 2007, 2008 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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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
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
 
59
_loaded = False
 
60
 
 
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
 
 
125
def load_plugins():
 
126
    """Load bzrlib plugins.
 
127
 
 
128
    The environment variable BZR_PLUGIN_PATH is considered a delimited
 
129
    set of paths to look through. Each entry is searched for *.py
 
130
    files (and whatever other extensions are used in the platform,
 
131
    such as *.pyd).
 
132
 
 
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
 
137
    if _loaded:
 
138
        # People can make sure plugins are loaded, they just won't be twice
 
139
        return
 
140
    _loaded = True
 
141
 
 
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)
 
164
    for d in dirs:
 
165
        if not d:
 
166
            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
 
206
            else:
 
207
                continue
 
208
        if getattr(_mod_plugins, f, None):
 
209
            trace.mutter('Plugin name %s already loaded', f)
 
210
        else:
 
211
            # trace.mutter('add plugin name %s', f)
 
212
            plugin_names.add(f)
 
213
    
 
214
    for name in plugin_names:
 
215
        try:
 
216
            exec "import bzrlib.plugins.%s" % name in {}
 
217
        except KeyboardInterrupt:
 
218
            raise
 
219
        except errors.IncompatibleAPI, e:
 
220
            trace.warning("Unable to load plugin %r. It requested API version "
 
221
                "%s of module %s but the minimum exported version is %s, and "
 
222
                "the maximum is %s" %
 
223
                (name, e.wanted, e.api, e.minimum, e.current))
 
224
        except Exception, e:
 
225
            trace.warning("%s" % e)
 
226
            ## import pdb; pdb.set_trace()
 
227
            if re.search('\.|-| ', name):
 
228
                sanitised_name = re.sub('[-. ]', '_', name)
 
229
                if sanitised_name.startswith('bzr_'):
 
230
                    sanitised_name = sanitised_name[len('bzr_'):]
 
231
                trace.warning("Unable to load %r in %r as a plugin because the "
 
232
                        "file path isn't a valid module name; try renaming "
 
233
                        "it to %r." % (name, d, sanitised_name))
 
234
            else:
 
235
                trace.warning('Unable to load plugin %r from %r' % (name, d))
 
236
            trace.log_exception_quietly()
 
237
            if 'error' in debug.debug_flags:
 
238
                trace.print_exception(sys.exc_info(), sys.stderr)
 
239
 
 
240
 
 
241
@deprecated_function(one_three)
 
242
def load_from_zip(zip_name):
 
243
    """Load all the plugins in a zip."""
 
244
    valid_suffixes = ('.py', '.pyc', '.pyo')    # only python modules/packages
 
245
                                                # is allowed
 
246
    try:
 
247
        index = zip_name.rindex('.zip')
 
248
    except ValueError:
 
249
        return
 
250
    archive = zip_name[:index+4]
 
251
    prefix = zip_name[index+5:]
 
252
 
 
253
    trace.mutter('Looking for plugins in %r', zip_name)
 
254
 
 
255
    # use zipfile to get list of files/dirs inside zip
 
256
    try:
 
257
        z = zipfile.ZipFile(archive)
 
258
        namelist = z.namelist()
 
259
        z.close()
 
260
    except zipfile.error:
 
261
        # not a valid zip
 
262
        return
 
263
 
 
264
    if prefix:
 
265
        prefix = prefix.replace('\\','/')
 
266
        if prefix[-1] != '/':
 
267
            prefix += '/'
 
268
        ix = len(prefix)
 
269
        namelist = [name[ix:]
 
270
                    for name in namelist
 
271
                    if name.startswith(prefix)]
 
272
 
 
273
    trace.mutter('Names in archive: %r', namelist)
 
274
    
 
275
    for name in namelist:
 
276
        if not name or name.endswith('/'):
 
277
            continue
 
278
    
 
279
        # '/' is used to separate pathname components inside zip archives
 
280
        ix = name.rfind('/')
 
281
        if ix == -1:
 
282
            head, tail = '', name
 
283
        else:
 
284
            head, tail = name.rsplit('/',1)
 
285
        if '/' in head:
 
286
            # we don't need looking in subdirectories
 
287
            continue
 
288
    
 
289
        base, suffix = osutils.splitext(tail)
 
290
        if suffix not in valid_suffixes:
 
291
            continue
 
292
    
 
293
        if base == '__init__':
 
294
            # package
 
295
            plugin_name = head
 
296
        elif head == '':
 
297
            # module
 
298
            plugin_name = base
 
299
        else:
 
300
            continue
 
301
    
 
302
        if not plugin_name:
 
303
            continue
 
304
        if getattr(_mod_plugins, plugin_name, None):
 
305
            trace.mutter('Plugin name %s already loaded', plugin_name)
 
306
            continue
 
307
    
 
308
        try:
 
309
            exec "import bzrlib.plugins.%s" % plugin_name in {}
 
310
            trace.mutter('Load plugin %s from zip %r', plugin_name, zip_name)
 
311
        except KeyboardInterrupt:
 
312
            raise
 
313
        except Exception, e:
 
314
            ## import pdb; pdb.set_trace()
 
315
            trace.warning('Unable to load plugin %r from %r'
 
316
                    % (name, zip_name))
 
317
            trace.log_exception_quietly()
 
318
            if 'error' in debug.debug_flags:
 
319
                trace.print_exception(sys.exc_info(), sys.stderr)
 
320
 
 
321
 
 
322
def plugins():
 
323
    """Return a dictionary of the plugins.
 
324
    
 
325
    Each item in the dictionary is a PlugIn object.
 
326
    """
 
327
    result = {}
 
328
    for name, plugin in _mod_plugins.__dict__.items():
 
329
        if isinstance(plugin, types.ModuleType):
 
330
            result[name] = PlugIn(name, plugin)
 
331
    return result
 
332
 
 
333
 
 
334
class PluginsHelpIndex(object):
 
335
    """A help index that returns help topics for plugins."""
 
336
 
 
337
    def __init__(self):
 
338
        self.prefix = 'plugins/'
 
339
 
 
340
    def get_topics(self, topic):
 
341
        """Search for topic in the loaded plugins.
 
342
 
 
343
        This will not trigger loading of new plugins.
 
344
 
 
345
        :param topic: A topic to search for.
 
346
        :return: A list which is either empty or contains a single
 
347
            RegisteredTopic entry.
 
348
        """
 
349
        if not topic:
 
350
            return []
 
351
        if topic.startswith(self.prefix):
 
352
            topic = topic[len(self.prefix):]
 
353
        plugin_module_name = 'bzrlib.plugins.%s' % topic
 
354
        try:
 
355
            module = sys.modules[plugin_module_name]
 
356
        except KeyError:
 
357
            return []
 
358
        else:
 
359
            return [ModuleHelpTopic(module)]
 
360
 
 
361
 
 
362
class ModuleHelpTopic(object):
 
363
    """A help topic which returns the docstring for a module."""
 
364
 
 
365
    def __init__(self, module):
 
366
        """Constructor.
 
367
 
 
368
        :param module: The module for which help should be generated.
 
369
        """
 
370
        self.module = module
 
371
 
 
372
    def get_help_text(self, additional_see_also=None):
 
373
        """Return a string with the help for this topic.
 
374
 
 
375
        :param additional_see_also: Additional help topics to be
 
376
            cross-referenced.
 
377
        """
 
378
        if not self.module.__doc__:
 
379
            result = "Plugin '%s' has no docstring.\n" % self.module.__name__
 
380
        else:
 
381
            result = self.module.__doc__
 
382
        if result[-1] != '\n':
 
383
            result += '\n'
 
384
        # there is code duplicated here and in bzrlib/help_topic.py's 
 
385
        # matching Topic code. This should probably be factored in
 
386
        # to a helper function and a common base class.
 
387
        if additional_see_also is not None:
 
388
            see_also = sorted(set(additional_see_also))
 
389
        else:
 
390
            see_also = None
 
391
        if see_also:
 
392
            result += 'See also: '
 
393
            result += ', '.join(see_also)
 
394
            result += '\n'
 
395
        return result
 
396
 
 
397
    def get_help_topic(self):
 
398
        """Return the modules help topic - its __name__ after bzrlib.plugins.."""
 
399
        return self.module.__name__[len('bzrlib.plugins.'):]
 
400
 
 
401
 
 
402
class PlugIn(object):
 
403
    """The bzrlib representation of a plugin.
 
404
 
 
405
    The PlugIn object provides a way to manipulate a given plugin module.
 
406
    """
 
407
 
 
408
    def __init__(self, name, module):
 
409
        """Construct a plugin for module."""
 
410
        self.name = name
 
411
        self.module = module
 
412
 
 
413
    def path(self):
 
414
        """Get the path that this plugin was loaded from."""
 
415
        if getattr(self.module, '__path__', None) is not None:
 
416
            return os.path.abspath(self.module.__path__[0])
 
417
        elif getattr(self.module, '__file__', None) is not None:
 
418
            path = os.path.abspath(self.module.__file__)
 
419
            if path[-4:] in ('.pyc', '.pyo'):
 
420
                pypath = path[:-4] + '.py'
 
421
                if os.path.isfile(pypath):
 
422
                    path = pypath
 
423
            return path
 
424
        else:
 
425
            return repr(self.module)
 
426
 
 
427
    def __str__(self):
 
428
        return "<%s.%s object at %s, name=%s, module=%s>" % (
 
429
            self.__class__.__module__, self.__class__.__name__, id(self),
 
430
            self.name, self.module)
 
431
 
 
432
    __repr__ = __str__
 
433
 
 
434
    def test_suite(self):
 
435
        """Return the plugin's test suite."""
 
436
        if getattr(self.module, 'test_suite', None) is not None:
 
437
            return self.module.test_suite()
 
438
        else:
 
439
            return None
 
440
 
 
441
    def load_plugin_tests(self, loader):
 
442
        """Return the adapted plugin's test suite.
 
443
 
 
444
        :param loader: The custom loader that should be used to load additional
 
445
            tests.
 
446
 
 
447
        """
 
448
        if getattr(self.module, 'load_tests', None) is not None:
 
449
            return loader.loadTestsFromModule(self.module)
 
450
        else:
 
451
            return None
 
452
 
 
453
    def version_info(self):
 
454
        """Return the plugin's version_tuple or None if unknown."""
 
455
        version_info = getattr(self.module, 'version_info', None)
 
456
        if version_info is not None and len(version_info) == 3:
 
457
            version_info = tuple(version_info) + ('final', 0)
 
458
        return version_info
 
459
 
 
460
    def _get__version__(self):
 
461
        version_info = self.version_info()
 
462
        if version_info is None:
 
463
            return "unknown"
 
464
        if version_info[3] == 'final':
 
465
            version_string = '%d.%d.%d' % version_info[:3]
 
466
        else:
 
467
            version_string = '%d.%d.%d%s%d' % version_info
 
468
        return version_string
 
469
 
 
470
    __version__ = property(_get__version__)