15
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18
"""bzr python plugin support.
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.
25
See the plugin-api developer documentation for information about writing
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
18
"""bzr python plugin support
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.
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.
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
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.
36
from bzrlib import osutils
38
45
from bzrlib.lazy_import import lazy_import
40
46
lazy_import(globals(), """
46
50
from bzrlib import (
47
_format_version_tuple,
53
from bzrlib import plugins as _mod_plugins
56
from bzrlib.symbol_versioning import deprecated_function, one_three
57
from bzrlib.trace import mutter, warning, log_exception_quietly
59
60
DEFAULT_PLUGIN_PATH = None
62
63
def get_default_plugin_path():
63
64
"""Get the DEFAULT_PLUGIN_PATH"""
67
68
return DEFAULT_PLUGIN_PATH
75
"""Return a dictionary of the plugins."""
77
for name, plugin in plugins.__dict__.items():
78
if isinstance(plugin, types.ModuleType):
70
83
def disable_plugins():
71
84
"""Disable loading plugins.
73
86
Future calls to load_plugins() will be ignored.
78
def _strip_trailing_sep(path):
79
return path.rstrip("\\/")
82
def set_plugins_path(path=None):
83
"""Set the path for plugins to be loaded from.
85
:param path: The list of paths to search for plugins. By default,
86
path will be determined using get_standard_plugins_path.
87
if path is [], no plugins can be loaded.
90
path = get_standard_plugins_path()
91
_mod_plugins.__path__ = path
95
def get_standard_plugins_path():
96
"""Determine a plugin path suitable for general use."""
97
path = os.environ.get('BZR_PLUGIN_PATH',
98
get_default_plugin_path()).split(os.pathsep)
99
# Get rid of trailing slashes, since Python can't handle them when
100
# it tries to import modules.
101
path = map(_strip_trailing_sep, path)
102
bzr_exe = bool(getattr(sys, 'frozen', None))
103
if bzr_exe: # expand path for bzr.exe
104
# We need to use relative path to system-wide plugin
105
# directory because bzrlib from standalone bzr.exe
106
# could be imported by another standalone program
107
# (e.g. bzr-config; or TortoiseBzr/Olive if/when they
108
# will become standalone exe). [bialix 20071123]
109
# __file__ typically is
110
# C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
111
# then plugins directory is
112
# C:\Program Files\Bazaar\plugins
113
# so relative path is ../../../plugins
114
path.append(osutils.abspath(osutils.pathjoin(
115
osutils.dirname(__file__), '../../../plugins')))
116
if not bzr_exe: # don't look inside library.zip
117
# search the plugin path before the bzrlib installed dir
118
path.append(os.path.dirname(_mod_plugins.__file__))
119
# search the arch independent path if we can determine that and
120
# the plugin is found nowhere else
121
if sys.platform != 'win32':
123
from distutils.sysconfig import get_python_lib
125
# If distutuils is not available, we just won't add that path
128
archless_path = osutils.pathjoin(get_python_lib(), 'bzrlib',
130
if archless_path not in path:
131
path.append(archless_path)
135
def load_plugins(path=None):
88
# TODO: jam 20060131 This should probably also disable
136
95
"""Load bzrlib plugins.
138
97
The environment variable BZR_PLUGIN_PATH is considered a delimited
199
132
valid_suffixes = [suffix for suffix, mod_type, flags in imp.get_suffixes()
200
133
if flags in (imp.PY_SOURCE, imp.PY_COMPILED)]
201
134
package_entries = ['__init__'+suffix for suffix in valid_suffixes]
203
for f in os.listdir(d):
204
path = osutils.pathjoin(d, f)
205
if os.path.isdir(path):
206
for entry in package_entries:
207
# This directory should be a package, and thus added to
209
if os.path.isfile(osutils.pathjoin(path, entry)):
211
else: # This directory is not a package
214
for suffix_info in imp.get_suffixes():
215
if f.endswith(suffix_info[0]):
216
f = f[:-len(suffix_info[0])]
217
if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
218
f = f[:-len('module')]
223
continue # We don't load __init__.py again in the plugin dir
224
elif getattr(_mod_plugins, f, None):
225
trace.mutter('Plugin name %s already loaded', f)
227
# trace.mutter('add plugin name %s', f)
230
for name in plugin_names:
232
exec "import bzrlib.plugins.%s" % name in {}
233
except KeyboardInterrupt:
235
except errors.IncompatibleAPI, e:
236
trace.warning("Unable to load plugin %r. It requested API version "
237
"%s of module %s but the minimum exported version is %s, and "
238
"the maximum is %s" %
239
(name, e.wanted, e.api, e.minimum, e.current))
241
trace.warning("%s" % e)
242
## import pdb; pdb.set_trace()
243
if re.search('\.|-| ', name):
244
sanitised_name = re.sub('[-. ]', '_', name)
245
if sanitised_name.startswith('bzr_'):
246
sanitised_name = sanitised_name[len('bzr_'):]
247
trace.warning("Unable to load %r in %r as a plugin because the "
248
"file path isn't a valid module name; try renaming "
249
"it to %r." % (name, d, sanitised_name))
251
trace.warning('Unable to load plugin %r from %r' % (name, d))
252
trace.log_exception_quietly()
253
if 'error' in debug.debug_flags:
254
trace.print_exception(sys.exc_info(), sys.stderr)
257
@deprecated_function(one_three)
258
def load_from_zip(zip_name):
259
"""Load all the plugins in a zip."""
138
mutter('looking for plugins in %s', d)
140
if not os.path.isdir(d):
142
for f in os.listdir(d):
143
path = osutils.pathjoin(d, f)
144
if os.path.isdir(path):
145
for entry in package_entries:
146
# This directory should be a package, and thus added to
148
if os.path.isfile(osutils.pathjoin(path, entry)):
150
else: # This directory is not a package
153
for suffix_info in imp.get_suffixes():
154
if f.endswith(suffix_info[0]):
155
f = f[:-len(suffix_info[0])]
156
if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
157
f = f[:-len('module')]
161
if getattr(plugins, f, None):
162
mutter('Plugin name %s already loaded', f)
164
# mutter('add plugin name %s', f)
167
plugin_names = list(plugin_names)
169
for name in plugin_names:
171
plugin_info = imp.find_module(name, [d])
172
# mutter('load plugin %r', plugin_info)
174
plugin = imp.load_module('bzrlib.plugins.' + name,
176
setattr(plugins, name, plugin)
178
if plugin_info[0] is not None:
179
plugin_info[0].close()
180
# mutter('loaded succesfully')
181
except KeyboardInterrupt:
184
## import pdb; pdb.set_trace()
185
warning('Unable to load plugin %r from %r' % (name, d))
186
log_exception_quietly()
189
def load_from_zips(zips):
190
"""Load bzr plugins from zip archives with zipimport.
191
It's similar to load_from_dirs but plugins searched inside archives.
260
196
valid_suffixes = ('.py', '.pyc', '.pyo') # only python modules/packages
263
index = zip_name.rindex('.zip')
266
archive = zip_name[:index+4]
267
prefix = zip_name[index+5:]
269
trace.mutter('Looking for plugins in %r', zip_name)
271
# use zipfile to get list of files/dirs inside zip
273
z = zipfile.ZipFile(archive)
198
for zip_name in zips:
199
if '.zip' not in zip_name:
202
ziobj = zipimport.zipimporter(zip_name)
203
except zipimport.ZipImportError:
206
mutter('Looking for plugins in %r', zip_name)
208
# use zipfile to get list of files/dirs inside zip
209
z = zipfile.ZipFile(ziobj.archive)
274
210
namelist = z.namelist()
276
except zipfile.error:
281
prefix = prefix.replace('\\','/')
282
if prefix[-1] != '/':
285
namelist = [name[ix:]
287
if name.startswith(prefix)]
289
trace.mutter('Names in archive: %r', namelist)
291
for name in namelist:
292
if not name or name.endswith('/'):
295
# '/' is used to separate pathname components inside zip archives
298
head, tail = '', name
300
head, tail = name.rsplit('/',1)
302
# we don't need looking in subdirectories
305
base, suffix = osutils.splitext(tail)
306
if suffix not in valid_suffixes:
309
if base == '__init__':
320
if getattr(_mod_plugins, plugin_name, None):
321
trace.mutter('Plugin name %s already loaded', plugin_name)
325
exec "import bzrlib.plugins.%s" % plugin_name in {}
326
trace.mutter('Load plugin %s from zip %r', plugin_name, zip_name)
327
except KeyboardInterrupt:
330
## import pdb; pdb.set_trace()
331
trace.warning('Unable to load plugin %r from %r'
333
trace.log_exception_quietly()
334
if 'error' in debug.debug_flags:
335
trace.print_exception(sys.exc_info(), sys.stderr)
339
"""Return a dictionary of the plugins.
341
Each item in the dictionary is a PlugIn object.
344
for name, plugin in _mod_plugins.__dict__.items():
345
if isinstance(plugin, types.ModuleType):
346
result[name] = PlugIn(name, plugin)
350
class PluginsHelpIndex(object):
351
"""A help index that returns help topics for plugins."""
354
self.prefix = 'plugins/'
356
def get_topics(self, topic):
357
"""Search for topic in the loaded plugins.
359
This will not trigger loading of new plugins.
361
:param topic: A topic to search for.
362
:return: A list which is either empty or contains a single
363
RegisteredTopic entry.
367
if topic.startswith(self.prefix):
368
topic = topic[len(self.prefix):]
369
plugin_module_name = 'bzrlib.plugins.%s' % topic
371
module = sys.modules[plugin_module_name]
375
return [ModuleHelpTopic(module)]
378
class ModuleHelpTopic(object):
379
"""A help topic which returns the docstring for a module."""
381
def __init__(self, module):
384
:param module: The module for which help should be generated.
388
def get_help_text(self, additional_see_also=None):
389
"""Return a string with the help for this topic.
391
:param additional_see_also: Additional help topics to be
394
if not self.module.__doc__:
395
result = "Plugin '%s' has no docstring.\n" % self.module.__name__
397
result = self.module.__doc__
398
if result[-1] != '\n':
400
# there is code duplicated here and in bzrlib/help_topic.py's
401
# matching Topic code. This should probably be factored in
402
# to a helper function and a common base class.
403
if additional_see_also is not None:
404
see_also = sorted(set(additional_see_also))
408
result += 'See also: '
409
result += ', '.join(see_also)
413
def get_help_topic(self):
414
"""Return the modules help topic - its __name__ after bzrlib.plugins.."""
415
return self.module.__name__[len('bzrlib.plugins.'):]
418
class PlugIn(object):
419
"""The bzrlib representation of a plugin.
421
The PlugIn object provides a way to manipulate a given plugin module.
424
def __init__(self, name, module):
425
"""Construct a plugin for module."""
430
"""Get the path that this plugin was loaded from."""
431
if getattr(self.module, '__path__', None) is not None:
432
return os.path.abspath(self.module.__path__[0])
433
elif getattr(self.module, '__file__', None) is not None:
434
path = os.path.abspath(self.module.__file__)
435
if path[-4:] in ('.pyc', '.pyo'):
436
pypath = path[:-4] + '.py'
437
if os.path.isfile(pypath):
441
return repr(self.module)
444
return "<%s.%s object at %s, name=%s, module=%s>" % (
445
self.__class__.__module__, self.__class__.__name__, id(self),
446
self.name, self.module)
450
def test_suite(self):
451
"""Return the plugin's test suite."""
452
if getattr(self.module, 'test_suite', None) is not None:
453
return self.module.test_suite()
457
def load_plugin_tests(self, loader):
458
"""Return the adapted plugin's test suite.
460
:param loader: The custom loader that should be used to load additional
464
if getattr(self.module, 'load_tests', None) is not None:
465
return loader.loadTestsFromModule(self.module)
469
def version_info(self):
470
"""Return the plugin's version_tuple or None if unknown."""
471
version_info = getattr(self.module, 'version_info', None)
472
if version_info is not None:
214
prefix = ziobj.prefix.replace('\\','/')
216
namelist = [name[ix:]
218
if name.startswith(prefix)]
220
mutter('Names in archive: %r', namelist)
222
for name in namelist:
223
if not name or name.endswith('/'):
226
# '/' is used to separate pathname components inside zip archives
229
head, tail = '', name
231
head, tail = name.rsplit('/',1)
233
# we don't need looking in subdirectories
236
base, suffix = osutils.splitext(tail)
237
if suffix not in valid_suffixes:
240
if base == '__init__':
251
if getattr(plugins, plugin_name, None):
252
mutter('Plugin name %s already loaded', plugin_name)
474
if isinstance(version_info, types.StringType):
475
version_info = version_info.split('.')
476
elif len(version_info) == 3:
477
version_info = tuple(version_info) + ('final', 0)
479
# The given version_info isn't even iteratible
480
trace.log_exception_quietly()
481
version_info = (version_info,)
484
def _get__version__(self):
485
version_info = self.version_info()
486
if version_info is None or len(version_info) == 0:
489
version_string = _format_version_tuple(version_info)
490
except (ValueError, TypeError, IndexError), e:
491
trace.log_exception_quietly()
492
# try to return something usefull for bad plugins, in stead of
494
version_string = '.'.join(map(str, version_info))
495
return version_string
497
__version__ = property(_get__version__)
256
plugin = ziobj.load_module(plugin_name)
257
setattr(plugins, plugin_name, plugin)
258
mutter('Load plugin %s from zip %r', plugin_name, zip_name)
259
except zipimport.ZipImportError, e:
260
mutter('Unable to load plugin %r from %r: %s',
261
plugin_name, zip_name, str(e))
263
except KeyboardInterrupt:
266
## import pdb; pdb.set_trace()
267
warning('Unable to load plugin %r from %r'
269
log_exception_quietly()
added
removed
bzrlib/plugin.py
