20
20
When load_plugins() is invoked, any python module in any directory in
21
21
$BZR_PLUGIN_PATH will be imported. The module will be imported as
22
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
23
update any bzrlib registries it wants to extend; for example, to add new
24
commands, import bzrlib.commands and add your new command to the plugin_cmds
28
27
BZR_PLUGIN_PATH is also honoured for any plugins imported via
29
'import bzrlib.plugins.PLUGINNAME', as long as set_plugins_path has been
28
'import bzrlib.plugins.PLUGINNAME', as long as set_plugins_path has been
36
from bzrlib import osutils
38
35
from bzrlib.lazy_import import lazy_import
39
36
lazy_import(globals(), """
44
42
from bzrlib import (
45
_format_version_tuple,
51
from bzrlib.i18n import gettext
52
from bzrlib import plugins as _mod_plugins
49
from bzrlib.trace import mutter, warning, log_exception_quietly
56
52
DEFAULT_PLUGIN_PATH = None
58
_plugins_disabled = False
62
# Map from plugin name, to list of string warnings about eg plugin
66
def are_plugins_disabled():
67
return _plugins_disabled
55
def get_default_plugin_path():
56
"""Get the DEFAULT_PLUGIN_PATH"""
57
global DEFAULT_PLUGIN_PATH
58
if DEFAULT_PLUGIN_PATH is None:
59
DEFAULT_PLUGIN_PATH = osutils.pathjoin(config.config_dir(), 'plugins')
60
return DEFAULT_PLUGIN_PATH
64
"""Return a dictionary of the plugins."""
66
for name, plugin in plugins.__dict__.items():
67
if isinstance(plugin, types.ModuleType):
70
72
def disable_plugins():
73
75
Future calls to load_plugins() will be ignored.
75
global _plugins_disabled
76
_plugins_disabled = True
80
def describe_plugins(show_paths=False):
81
"""Generate text description of plugins.
83
Includes both those that have loaded, and those that failed to
86
:param show_paths: If true,
87
:returns: Iterator of text lines (including newlines.)
89
from inspect import getdoc
90
loaded_plugins = plugins()
91
all_names = sorted(list(set(
92
loaded_plugins.keys() + plugin_warnings.keys())))
93
for name in all_names:
94
if name in loaded_plugins:
95
plugin = loaded_plugins[name]
96
version = plugin.__version__
97
if version == 'unknown':
99
yield '%s %s\n' % (name, version)
100
d = getdoc(plugin.module)
102
doc = d.split('\n')[0]
104
doc = '(no description)'
105
yield (" %s\n" % doc)
107
yield (" %s\n" % plugin.path())
110
yield "%s (failed to load)\n" % name
111
if name in plugin_warnings:
112
for line in plugin_warnings[name]:
113
yield " ** " + line + '\n'
117
def _strip_trailing_sep(path):
118
return path.rstrip("\\/")
121
def _get_specific_plugin_paths(paths):
122
"""Returns the plugin paths from a string describing the associations.
124
:param paths: A string describing the paths associated with the plugins.
126
:returns: A list of (plugin name, path) tuples.
128
For example, if paths is my_plugin@/test/my-test:her_plugin@/production/her,
129
[('my_plugin', '/test/my-test'), ('her_plugin', '/production/her')]
132
Note that ':' in the example above depends on the os.
137
for spec in paths.split(os.pathsep):
139
name, path = spec.split('@')
141
raise errors.BzrCommandError(gettext(
142
'"%s" is not a valid <plugin_name>@<plugin_path> description ')
144
specs.append((name, path))
148
def set_plugins_path(path=None):
149
"""Set the path for plugins to be loaded from.
151
:param path: The list of paths to search for plugins. By default,
152
path will be determined using get_standard_plugins_path.
153
if path is [], no plugins can be loaded.
156
path = get_standard_plugins_path()
157
_mod_plugins.__path__ = path
158
PluginImporter.reset()
159
# Set up a blacklist for disabled plugins
160
disabled_plugins = os.environ.get('BZR_DISABLE_PLUGINS', None)
161
if disabled_plugins is not None:
162
for name in disabled_plugins.split(os.pathsep):
163
PluginImporter.blacklist.add('bzrlib.plugins.' + name)
164
# Set up a the specific paths for plugins
165
for plugin_name, plugin_path in _get_specific_plugin_paths(os.environ.get(
166
'BZR_PLUGINS_AT', None)):
167
PluginImporter.specific_paths[
168
'bzrlib.plugins.%s' % plugin_name] = plugin_path
77
# TODO: jam 20060131 This should probably also disable
83
def set_plugins_path():
84
"""Set the path for plugins to be loaded from."""
85
path = os.environ.get('BZR_PLUGIN_PATH',
86
get_default_plugin_path()).split(os.pathsep)
87
# search the plugin path before the bzrlib installed dir
88
path.append(os.path.dirname(plugins.__file__))
89
plugins.__path__ = path
172
def _append_new_path(paths, new_path):
173
"""Append a new path if it set and not already known."""
174
if new_path is not None and new_path not in paths:
175
paths.append(new_path)
179
def get_core_plugin_path():
181
bzr_exe = bool(getattr(sys, 'frozen', None))
182
if bzr_exe: # expand path for bzr.exe
183
# We need to use relative path to system-wide plugin
184
# directory because bzrlib from standalone bzr.exe
185
# could be imported by another standalone program
186
# (e.g. bzr-config; or TortoiseBzr/Olive if/when they
187
# will become standalone exe). [bialix 20071123]
188
# __file__ typically is
189
# C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
190
# then plugins directory is
191
# C:\Program Files\Bazaar\plugins
192
# so relative path is ../../../plugins
193
core_path = osutils.abspath(osutils.pathjoin(
194
osutils.dirname(__file__), '../../../plugins'))
195
else: # don't look inside library.zip
196
# search the plugin path before the bzrlib installed dir
197
core_path = os.path.dirname(_mod_plugins.__file__)
201
def get_site_plugin_path():
202
"""Returns the path for the site installed plugins."""
203
if sys.platform == 'win32':
204
# We don't have (yet) a good answer for windows since that is certainly
205
# related to the way we build the installers. -- vila20090821
209
from distutils.sysconfig import get_python_lib
211
# If distutuils is not available, we just don't know where they are
214
site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
218
def get_user_plugin_path():
219
return osutils.pathjoin(config.config_dir(), 'plugins')
222
def get_standard_plugins_path():
223
"""Determine a plugin path suitable for general use."""
224
# Ad-Hoc default: core is not overriden by site but user can overrides both
225
# The rationale is that:
226
# - 'site' comes last, because these plugins should always be available and
227
# are supposed to be in sync with the bzr installed on site.
228
# - 'core' comes before 'site' so that running bzr from sources or a user
229
# installed version overrides the site version.
230
# - 'user' comes first, because... user is always right.
231
# - the above rules clearly defines which plugin version will be loaded if
232
# several exist. Yet, it is sometimes desirable to disable some directory
233
# so that a set of plugins is disabled as once. This can be done via
234
# -site, -core, -user.
236
env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
237
defaults = ['+core', '+site']
239
# The predefined references
240
refs = dict(core=get_core_plugin_path(),
241
site=get_site_plugin_path(),
242
user=get_user_plugin_path())
244
# Unset paths that should be removed
245
for k,v in refs.iteritems():
247
# defaults can never mention removing paths as that will make it
248
# impossible for the user to revoke these removals.
249
if removed in env_paths:
250
env_paths.remove(removed)
255
for p in env_paths + defaults:
256
if p.startswith('+'):
257
# Resolve references if they are known
261
# Leave them untouched so user can still use paths starting
264
_append_new_path(paths, p)
266
# Get rid of trailing slashes, since Python can't handle them when
267
# it tries to import modules.
268
paths = map(_strip_trailing_sep, paths)
272
def load_plugins(path=None):
273
94
"""Load bzrlib plugins.
275
96
The environment variable BZR_PLUGIN_PATH is considered a delimited
276
set of paths to look through. Each entry is searched for `*.py`
97
set of paths to look through. Each entry is searched for *.py
277
98
files (and whatever other extensions are used in the platform,
280
load_from_path() provides the underlying mechanism and is called with
101
load_from_dirs() provides the underlying mechanism and is called with
281
102
the default directory list to provide the normal behaviour.
283
:param path: The list of paths to search for plugins. By default,
284
path will be determined using get_standard_plugins_path.
285
if path is [], no plugins can be loaded.
330
141
load_from_dirs = load_from_path
333
def _find_plugin_module(dir, name):
334
"""Check if there is a valid python module that can be loaded as a plugin.
336
:param dir: The directory where the search is performed.
337
:param path: An existing file path, either a python file or a package
340
:return: (name, path, description) name is the module name, path is the
341
file to load and description is the tuple returned by
344
path = osutils.pathjoin(dir, name)
345
if os.path.isdir(path):
346
# Check for a valid __init__.py file, valid suffixes depends on -O and
347
# can be .py, .pyc and .pyo
348
for suffix, mode, kind in imp.get_suffixes():
349
if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
350
# We don't recognize compiled modules (.so, .dll, etc)
352
init_path = osutils.pathjoin(path, '__init__' + suffix)
353
if os.path.isfile(init_path):
354
return name, init_path, (suffix, mode, kind)
356
for suffix, mode, kind in imp.get_suffixes():
357
if name.endswith(suffix):
358
# Clean up the module name
359
name = name[:-len(suffix)]
360
if kind == imp.C_EXTENSION and name.endswith('module'):
361
name = name[:-len('module')]
362
return name, path, (suffix, mode, kind)
363
# There is no python module here
364
return None, None, (None, None, None)
367
def record_plugin_warning(plugin_name, warning_message):
368
trace.mutter(warning_message)
369
plugin_warnings.setdefault(plugin_name, []).append(warning_message)
372
def _load_plugin_module(name, dir):
373
"""Load plugin name from dir.
375
:param name: The plugin name in the bzrlib.plugins namespace.
376
:param dir: The directory the plugin is loaded from for error messages.
378
if ('bzrlib.plugins.%s' % name) in PluginImporter.blacklist:
381
exec "import bzrlib.plugins.%s" % name in {}
382
except KeyboardInterrupt:
384
except errors.IncompatibleAPI, e:
386
"Unable to load plugin %r. It requested API version "
387
"%s of module %s but the minimum exported version is %s, and "
388
"the maximum is %s" %
389
(name, e.wanted, e.api, e.minimum, e.current))
390
record_plugin_warning(name, warning_message)
392
trace.warning("%s" % e)
393
if re.search('\.|-| ', name):
394
sanitised_name = re.sub('[-. ]', '_', name)
395
if sanitised_name.startswith('bzr_'):
396
sanitised_name = sanitised_name[len('bzr_'):]
397
trace.warning("Unable to load %r in %r as a plugin because the "
398
"file path isn't a valid module name; try renaming "
399
"it to %r." % (name, dir, sanitised_name))
401
record_plugin_warning(
403
'Unable to load plugin %r from %r' % (name, dir))
404
trace.log_exception_quietly()
405
if 'error' in debug.debug_flags:
406
trace.print_exception(sys.exc_info(), sys.stderr)
409
144
def load_from_dir(d):
410
"""Load the plugins in directory d.
412
d must be in the plugins module path already.
413
This function is called once for each directory in the module path.
145
"""Load the plugins in directory d."""
146
# Get the list of valid python suffixes for __init__.py?
147
# this includes .py, .pyc, and .pyo (depending on if we are running -O)
148
# but it doesn't include compiled modules (.so, .dll, etc)
149
valid_suffixes = [suffix for suffix, mod_type, flags in imp.get_suffixes()
150
if flags in (imp.PY_SOURCE, imp.PY_COMPILED)]
151
package_entries = ['__init__'+suffix for suffix in valid_suffixes]
415
152
plugin_names = set()
416
for p in os.listdir(d):
417
name, path, desc = _find_plugin_module(d, p)
419
if name == '__init__':
420
# We do nothing with the __init__.py file in directories from
421
# the bzrlib.plugins module path, we may want to, one day
423
continue # We don't load __init__.py in the plugins dirs
424
elif getattr(_mod_plugins, name, None) is not None:
425
# The module has already been loaded from another directory
426
# during a previous call.
427
# FIXME: There should be a better way to report masked plugins
429
trace.mutter('Plugin name %s already loaded', name)
153
for f in os.listdir(d):
154
path = osutils.pathjoin(d, f)
155
if os.path.isdir(path):
156
for entry in package_entries:
157
# This directory should be a package, and thus added to
159
if os.path.isfile(osutils.pathjoin(path, entry)):
161
else: # This directory is not a package
164
for suffix_info in imp.get_suffixes():
165
if f.endswith(suffix_info[0]):
166
f = f[:-len(suffix_info[0])]
167
if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
168
f = f[:-len('module')]
431
plugin_names.add(name)
172
if getattr(plugins, f, None):
173
mutter('Plugin name %s already loaded', f)
175
# mutter('add plugin name %s', f)
433
178
for name in plugin_names:
434
_load_plugin_module(name, d)
438
"""Return a dictionary of the plugins.
440
Each item in the dictionary is a PlugIn object.
443
for name, plugin in _mod_plugins.__dict__.items():
444
if isinstance(plugin, types.ModuleType):
445
result[name] = PlugIn(name, plugin)
449
def format_concise_plugin_list():
450
"""Return a string holding a concise list of plugins and their version.
453
for name, a_plugin in sorted(plugins().items()):
454
items.append("%s[%s]" %
455
(name, a_plugin.__version__))
456
return ', '.join(items)
180
exec "import bzrlib.plugins.%s" % name in {}
181
except KeyboardInterrupt:
184
## import pdb; pdb.set_trace()
185
if re.search('\.|-| ', name):
186
warning('Unable to load plugin %r from %r: '
187
'It is not a valid python module name.' % (name, d))
189
warning('Unable to load plugin %r from %r' % (name, d))
190
log_exception_quietly()
193
def load_from_zip(zip_name):
194
"""Load all the plugins in a zip."""
195
valid_suffixes = ('.py', '.pyc', '.pyo') # only python modules/packages
199
index = zip_name.rindex('.zip')
202
archive = zip_name[:index+4]
203
prefix = zip_name[index+5:]
205
mutter('Looking for plugins in %r', zip_name)
207
# use zipfile to get list of files/dirs inside zip
209
z = zipfile.ZipFile(archive)
210
namelist = z.namelist()
212
except zipfile.error:
217
prefix = prefix.replace('\\','/')
218
if prefix[-1] != '/':
221
namelist = [name[ix:]
223
if name.startswith(prefix)]
225
mutter('Names in archive: %r', namelist)
227
for name in namelist:
228
if not name or name.endswith('/'):
231
# '/' is used to separate pathname components inside zip archives
234
head, tail = '', name
236
head, tail = name.rsplit('/',1)
238
# we don't need looking in subdirectories
241
base, suffix = osutils.splitext(tail)
242
if suffix not in valid_suffixes:
245
if base == '__init__':
256
if getattr(plugins, plugin_name, None):
257
mutter('Plugin name %s already loaded', plugin_name)
261
exec "import bzrlib.plugins.%s" % plugin_name in {}
262
mutter('Load plugin %s from zip %r', plugin_name, zip_name)
263
except KeyboardInterrupt:
266
## import pdb; pdb.set_trace()
267
warning('Unable to load plugin %r from %r'
269
log_exception_quietly()
460
272
class PluginsHelpIndex(object):
507
319
result = self.module.__doc__
508
320
if result[-1] != '\n':
510
from bzrlib import help_topics
511
result += help_topics._format_see_also(additional_see_also)
322
# there is code duplicated here and in bzrlib/help_topic.py's
323
# matching Topic code. This should probably be factored in
324
# to a helper function and a common base class.
325
if additional_see_also is not None:
326
see_also = sorted(set(additional_see_also))
330
result += 'See also: '
331
result += ', '.join(see_also)
514
335
def get_help_topic(self):
515
"""Return the module help topic: its basename."""
336
"""Return the modules help topic - its __name__ after bzrlib.plugins.."""
516
337
return self.module.__name__[len('bzrlib.plugins.'):]
519
class PlugIn(object):
520
"""The bzrlib representation of a plugin.
522
The PlugIn object provides a way to manipulate a given plugin module.
525
def __init__(self, name, module):
526
"""Construct a plugin for module."""
531
"""Get the path that this plugin was loaded from."""
532
if getattr(self.module, '__path__', None) is not None:
533
return os.path.abspath(self.module.__path__[0])
534
elif getattr(self.module, '__file__', None) is not None:
535
path = os.path.abspath(self.module.__file__)
536
if path[-4:] in ('.pyc', '.pyo'):
537
pypath = path[:-4] + '.py'
538
if os.path.isfile(pypath):
542
return repr(self.module)
545
return "<%s.%s object at %s, name=%s, module=%s>" % (
546
self.__class__.__module__, self.__class__.__name__, id(self),
547
self.name, self.module)
551
def test_suite(self):
552
"""Return the plugin's test suite."""
553
if getattr(self.module, 'test_suite', None) is not None:
554
return self.module.test_suite()
558
def load_plugin_tests(self, loader):
559
"""Return the adapted plugin's test suite.
561
:param loader: The custom loader that should be used to load additional
565
if getattr(self.module, 'load_tests', None) is not None:
566
return loader.loadTestsFromModule(self.module)
570
def version_info(self):
571
"""Return the plugin's version_tuple or None if unknown."""
572
version_info = getattr(self.module, 'version_info', None)
573
if version_info is not None:
575
if isinstance(version_info, types.StringType):
576
version_info = version_info.split('.')
577
elif len(version_info) == 3:
578
version_info = tuple(version_info) + ('final', 0)
580
# The given version_info isn't even iteratible
581
trace.log_exception_quietly()
582
version_info = (version_info,)
585
def _get__version__(self):
586
version_info = self.version_info()
587
if version_info is None or len(version_info) == 0:
590
version_string = _format_version_tuple(version_info)
591
except (ValueError, TypeError, IndexError), e:
592
trace.log_exception_quietly()
593
# try to return something usefull for bad plugins, in stead of
595
version_string = '.'.join(map(str, version_info))
596
return version_string
598
__version__ = property(_get__version__)
601
class _PluginImporter(object):
602
"""An importer tailored to bzr specific needs.
604
This is a singleton that takes care of:
605
- disabled plugins specified in 'blacklist',
606
- plugins that needs to be loaded from specific directories.
613
self.blacklist = set()
614
self.specific_paths = {}
616
def find_module(self, fullname, parent_path=None):
617
"""Search a plugin module.
619
Disabled plugins raise an import error, plugins with specific paths
620
returns a specific loader.
622
:return: None if the plugin doesn't need special handling, self
625
if not fullname.startswith('bzrlib.plugins.'):
627
if fullname in self.blacklist:
628
raise ImportError('%s is disabled' % fullname)
629
if fullname in self.specific_paths:
633
def load_module(self, fullname):
634
"""Load a plugin from a specific directory."""
635
# We are called only for specific paths
636
plugin_path = self.specific_paths[fullname]
638
if os.path.isdir(plugin_path):
639
for suffix, mode, kind in imp.get_suffixes():
640
if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
641
# We don't recognize compiled modules (.so, .dll, etc)
643
init_path = osutils.pathjoin(plugin_path, '__init__' + suffix)
644
if os.path.isfile(init_path):
645
# We've got a module here and load_module needs specific
647
loading_path = plugin_path
650
kind = imp.PKG_DIRECTORY
653
for suffix, mode, kind in imp.get_suffixes():
654
if plugin_path.endswith(suffix):
655
loading_path = plugin_path
657
if loading_path is None:
658
raise ImportError('%s cannot be loaded from %s'
659
% (fullname, plugin_path))
660
if kind is imp.PKG_DIRECTORY:
663
f = open(loading_path, mode)
665
mod = imp.load_module(fullname, f, loading_path,
666
(suffix, mode, kind))
667
mod.__package__ = fullname
674
# Install a dedicated importer for plugins requiring special handling
675
PluginImporter = _PluginImporter()
676
sys.meta_path.append(PluginImporter)
added
removed
bzrlib/plugin.py
