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; for example, to add new
24
commands, import bzrlib.commands and add your new command to the plugin_cmds
23
update any bzrlib registries it wants to extend.
25
See the plugin-api developer documentation for information about writing
27
28
BZR_PLUGIN_PATH is also honoured for any plugins imported via
28
'import bzrlib.plugins.PLUGINNAME', as long as set_plugins_path has been
29
'import bzrlib.plugins.PLUGINNAME', as long as set_plugins_path has been
36
from bzrlib import osutils
35
38
from bzrlib.lazy_import import lazy_import
36
40
lazy_import(globals(), """
42
45
from bzrlib import (
46
_format_version_tuple,
48
52
from bzrlib import plugins as _mod_plugins
51
from bzrlib.symbol_versioning import deprecated_function, one_three
52
from bzrlib.trace import mutter, warning, log_exception_quietly
55
from bzrlib.symbol_versioning import (
55
61
DEFAULT_PLUGIN_PATH = None
58
def get_default_plugin_path():
59
"""Get the DEFAULT_PLUGIN_PATH"""
60
global DEFAULT_PLUGIN_PATH
61
if DEFAULT_PLUGIN_PATH is None:
62
DEFAULT_PLUGIN_PATH = osutils.pathjoin(config.config_dir(), 'plugins')
63
return DEFAULT_PLUGIN_PATH
63
_plugins_disabled = False
66
def are_plugins_disabled():
67
return _plugins_disabled
66
70
def disable_plugins():
69
73
Future calls to load_plugins() will be ignored.
71
# TODO: jam 20060131 This should probably also disable
75
global _plugins_disabled
76
_plugins_disabled = True
77
80
def _strip_trailing_sep(path):
78
81
return path.rstrip("\\/")
81
def set_plugins_path():
82
"""Set the path for plugins to be loaded from."""
83
path = os.environ.get('BZR_PLUGIN_PATH',
84
get_default_plugin_path()).split(os.pathsep)
84
def _get_specific_plugin_paths(paths):
85
"""Returns the plugin paths from a string describing the associations.
87
:param paths: A string describing the paths associated with the plugins.
89
:returns: A list of (plugin name, path) tuples.
91
For example, if paths is my_plugin@/test/my-test:her_plugin@/production/her,
92
[('my_plugin', '/test/my-test'), ('her_plugin', '/production/her')]
95
Note that ':' in the example above depends on the os.
100
for spec in paths.split(os.pathsep):
102
name, path = spec.split('@')
104
raise errors.BzrCommandError(
105
'"%s" is not a valid <plugin_name>@<plugin_path> description '
107
specs.append((name, path))
111
def set_plugins_path(path=None):
112
"""Set the path for plugins to be loaded from.
114
:param path: The list of paths to search for plugins. By default,
115
path will be determined using get_standard_plugins_path.
116
if path is [], no plugins can be loaded.
119
path = get_standard_plugins_path()
120
_mod_plugins.__path__ = path
121
PluginImporter.reset()
122
# Set up a blacklist for disabled plugins
123
disabled_plugins = os.environ.get('BZR_DISABLE_PLUGINS', None)
124
if disabled_plugins is not None:
125
for name in disabled_plugins.split(os.pathsep):
126
PluginImporter.blacklist.add('bzrlib.plugins.' + name)
127
# Set up a the specific paths for plugins
128
for plugin_name, plugin_path in _get_specific_plugin_paths(os.environ.get(
129
'BZR_PLUGINS_AT', None)):
130
PluginImporter.specific_paths[
131
'bzrlib.plugins.%s' % plugin_name] = plugin_path
135
def _append_new_path(paths, new_path):
136
"""Append a new path if it set and not already known."""
137
if new_path is not None and new_path not in paths:
138
paths.append(new_path)
142
def get_core_plugin_path():
85
144
bzr_exe = bool(getattr(sys, 'frozen', None))
86
145
if bzr_exe: # expand path for bzr.exe
87
146
# We need to use relative path to system-wide plugin
94
153
# then plugins directory is
95
154
# C:\Program Files\Bazaar\plugins
96
155
# so relative path is ../../../plugins
97
path.append(osutils.abspath(osutils.pathjoin(
98
osutils.dirname(__file__), '../../../plugins')))
156
core_path = osutils.abspath(osutils.pathjoin(
157
osutils.dirname(__file__), '../../../plugins'))
158
else: # don't look inside library.zip
159
# search the plugin path before the bzrlib installed dir
160
core_path = os.path.dirname(_mod_plugins.__file__)
164
def get_site_plugin_path():
165
"""Returns the path for the site installed plugins."""
166
if sys.platform == 'win32':
167
# We don't have (yet) a good answer for windows since that is certainly
168
# related to the way we build the installers. -- vila20090821
172
from distutils.sysconfig import get_python_lib
174
# If distutuils is not available, we just don't know where they are
177
site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
181
def get_user_plugin_path():
182
return osutils.pathjoin(config.config_dir(), 'plugins')
185
def get_standard_plugins_path():
186
"""Determine a plugin path suitable for general use."""
187
# Ad-Hoc default: core is not overriden by site but user can overrides both
188
# The rationale is that:
189
# - 'site' comes last, because these plugins should always be available and
190
# are supposed to be in sync with the bzr installed on site.
191
# - 'core' comes before 'site' so that running bzr from sources or a user
192
# installed version overrides the site version.
193
# - 'user' comes first, because... user is always right.
194
# - the above rules clearly defines which plugin version will be loaded if
195
# several exist. Yet, it is sometimes desirable to disable some directory
196
# so that a set of plugins is disabled as once. This can be done via
197
# -site, -core, -user.
199
env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
200
defaults = ['+core', '+site']
202
# The predefined references
203
refs = dict(core=get_core_plugin_path(),
204
site=get_site_plugin_path(),
205
user=get_user_plugin_path())
207
# Unset paths that should be removed
208
for k,v in refs.iteritems():
210
# defaults can never mention removing paths as that will make it
211
# impossible for the user to revoke these removals.
212
if removed in env_paths:
213
env_paths.remove(removed)
218
for p in env_paths + defaults:
219
if p.startswith('+'):
220
# Resolve references if they are known
224
# Leave them untouched so user can still use paths starting
227
_append_new_path(paths, p)
99
229
# Get rid of trailing slashes, since Python can't handle them when
100
230
# it tries to import modules.
101
path = map(_strip_trailing_sep, path)
102
if not bzr_exe: # don't look inside library.zip
103
# search the plugin path before the bzrlib installed dir
104
path.append(os.path.dirname(_mod_plugins.__file__))
105
# search the arch independent path if we can determine that and
106
# the plugin is found nowhere else
107
if sys.platform != 'win32':
109
from distutils.sysconfig import get_python_lib
111
# If distutuils is not available, we just won't add that path
114
archless_path = osutils.pathjoin(get_python_lib(), 'bzrlib',
116
if archless_path not in path:
117
path.append(archless_path)
118
_mod_plugins.__path__ = path
231
paths = map(_strip_trailing_sep, paths)
235
def load_plugins(path=None):
123
236
"""Load bzrlib plugins.
125
238
The environment variable BZR_PLUGIN_PATH is considered a delimited
171
293
load_from_dirs = load_from_path
296
def _find_plugin_module(dir, name):
297
"""Check if there is a valid python module that can be loaded as a plugin.
299
:param dir: The directory where the search is performed.
300
:param path: An existing file path, either a python file or a package
303
:return: (name, path, description) name is the module name, path is the
304
file to load and description is the tuple returned by
307
path = osutils.pathjoin(dir, name)
308
if os.path.isdir(path):
309
# Check for a valid __init__.py file, valid suffixes depends on -O and
310
# can be .py, .pyc and .pyo
311
for suffix, mode, kind in imp.get_suffixes():
312
if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
313
# We don't recognize compiled modules (.so, .dll, etc)
315
init_path = osutils.pathjoin(path, '__init__' + suffix)
316
if os.path.isfile(init_path):
317
return name, init_path, (suffix, mode, kind)
319
for suffix, mode, kind in imp.get_suffixes():
320
if name.endswith(suffix):
321
# Clean up the module name
322
name = name[:-len(suffix)]
323
if kind == imp.C_EXTENSION and name.endswith('module'):
324
name = name[:-len('module')]
325
return name, path, (suffix, mode, kind)
326
# There is no python module here
327
return None, None, (None, None, None)
330
def _load_plugin_module(name, dir):
331
"""Load plugin name from dir.
333
:param name: The plugin name in the bzrlib.plugins namespace.
334
:param dir: The directory the plugin is loaded from for error messages.
336
if ('bzrlib.plugins.%s' % name) in PluginImporter.blacklist:
339
exec "import bzrlib.plugins.%s" % name in {}
340
except KeyboardInterrupt:
342
except errors.IncompatibleAPI, e:
343
trace.warning("Unable to load plugin %r. It requested API version "
344
"%s of module %s but the minimum exported version is %s, and "
345
"the maximum is %s" %
346
(name, e.wanted, e.api, e.minimum, e.current))
348
trace.warning("%s" % e)
349
if re.search('\.|-| ', name):
350
sanitised_name = re.sub('[-. ]', '_', name)
351
if sanitised_name.startswith('bzr_'):
352
sanitised_name = sanitised_name[len('bzr_'):]
353
trace.warning("Unable to load %r in %r as a plugin because the "
354
"file path isn't a valid module name; try renaming "
355
"it to %r." % (name, dir, sanitised_name))
357
trace.warning('Unable to load plugin %r from %r' % (name, dir))
358
trace.log_exception_quietly()
359
if 'error' in debug.debug_flags:
360
trace.print_exception(sys.exc_info(), sys.stderr)
174
363
def load_from_dir(d):
175
"""Load the plugins in directory d."""
176
# Get the list of valid python suffixes for __init__.py?
177
# this includes .py, .pyc, and .pyo (depending on if we are running -O)
178
# but it doesn't include compiled modules (.so, .dll, etc)
179
valid_suffixes = [suffix for suffix, mod_type, flags in imp.get_suffixes()
180
if flags in (imp.PY_SOURCE, imp.PY_COMPILED)]
181
package_entries = ['__init__'+suffix for suffix in valid_suffixes]
364
"""Load the plugins in directory d.
366
d must be in the plugins module path already.
367
This function is called once for each directory in the module path.
182
369
plugin_names = set()
183
for f in os.listdir(d):
184
path = osutils.pathjoin(d, f)
185
if os.path.isdir(path):
186
for entry in package_entries:
187
# This directory should be a package, and thus added to
189
if os.path.isfile(osutils.pathjoin(path, entry)):
191
else: # This directory is not a package
194
for suffix_info in imp.get_suffixes():
195
if f.endswith(suffix_info[0]):
196
f = f[:-len(suffix_info[0])]
197
if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
198
f = f[:-len('module')]
370
for p in os.listdir(d):
371
name, path, desc = _find_plugin_module(d, p)
373
if name == '__init__':
374
# We do nothing with the __init__.py file in directories from
375
# the bzrlib.plugins module path, we may want to, one day
377
continue # We don't load __init__.py in the plugins dirs
378
elif getattr(_mod_plugins, name, None) is not None:
379
# The module has already been loaded from another directory
380
# during a previous call.
381
# FIXME: There should be a better way to report masked plugins
383
trace.mutter('Plugin name %s already loaded', name)
202
if getattr(_mod_plugins, f, None):
203
mutter('Plugin name %s already loaded', f)
205
# mutter('add plugin name %s', f)
385
plugin_names.add(name)
208
387
for name in plugin_names:
210
exec "import bzrlib.plugins.%s" % name in {}
211
except KeyboardInterrupt:
214
## import pdb; pdb.set_trace()
215
if re.search('\.|-| ', name):
216
sanitised_name = re.sub('[-. ]', '_', name)
217
if sanitised_name.startswith('bzr_'):
218
sanitised_name = sanitised_name[len('bzr_'):]
219
warning("Unable to load %r in %r as a plugin because the "
220
"file path isn't a valid module name; try renaming "
221
"it to %r." % (name, d, sanitised_name))
223
warning('Unable to load plugin %r from %r' % (name, d))
224
log_exception_quietly()
225
if 'error' in debug.debug_flags:
226
trace.print_exception(sys.exc_info(), sys.stderr)
229
@deprecated_function(one_three)
230
def load_from_zip(zip_name):
231
"""Load all the plugins in a zip."""
232
valid_suffixes = ('.py', '.pyc', '.pyo') # only python modules/packages
235
index = zip_name.rindex('.zip')
238
archive = zip_name[:index+4]
239
prefix = zip_name[index+5:]
241
mutter('Looking for plugins in %r', zip_name)
243
# use zipfile to get list of files/dirs inside zip
245
z = zipfile.ZipFile(archive)
246
namelist = z.namelist()
248
except zipfile.error:
253
prefix = prefix.replace('\\','/')
254
if prefix[-1] != '/':
257
namelist = [name[ix:]
259
if name.startswith(prefix)]
261
mutter('Names in archive: %r', namelist)
263
for name in namelist:
264
if not name or name.endswith('/'):
267
# '/' is used to separate pathname components inside zip archives
270
head, tail = '', name
272
head, tail = name.rsplit('/',1)
274
# we don't need looking in subdirectories
277
base, suffix = osutils.splitext(tail)
278
if suffix not in valid_suffixes:
281
if base == '__init__':
292
if getattr(_mod_plugins, plugin_name, None):
293
mutter('Plugin name %s already loaded', plugin_name)
297
exec "import bzrlib.plugins.%s" % plugin_name in {}
298
mutter('Load plugin %s from zip %r', plugin_name, zip_name)
299
except KeyboardInterrupt:
302
## import pdb; pdb.set_trace()
303
warning('Unable to load plugin %r from %r'
305
log_exception_quietly()
306
if 'error' in debug.debug_flags:
307
trace.print_exception(sys.exc_info(), sys.stderr)
388
_load_plugin_module(name, d)
311
392
"""Return a dictionary of the plugins.
313
394
Each item in the dictionary is a PlugIn object.
441
522
def version_info(self):
442
523
"""Return the plugin's version_tuple or None if unknown."""
443
524
version_info = getattr(self.module, 'version_info', None)
444
if version_info is not None and len(version_info) == 3:
445
version_info = tuple(version_info) + ('final', 0)
525
if version_info is not None:
527
if isinstance(version_info, types.StringType):
528
version_info = version_info.split('.')
529
elif len(version_info) == 3:
530
version_info = tuple(version_info) + ('final', 0)
532
# The given version_info isn't even iteratible
533
trace.log_exception_quietly()
534
version_info = (version_info,)
446
535
return version_info
448
537
def _get__version__(self):
449
538
version_info = self.version_info()
450
if version_info is None:
539
if version_info is None or len(version_info) == 0:
452
if version_info[3] == 'final':
453
version_string = '%d.%d.%d' % version_info[:3]
455
version_string = '%d.%d.%d%s%d' % version_info
542
version_string = _format_version_tuple(version_info)
543
except (ValueError, TypeError, IndexError), e:
544
trace.log_exception_quietly()
545
# try to return something usefull for bad plugins, in stead of
547
version_string = '.'.join(map(str, version_info))
456
548
return version_string
458
550
__version__ = property(_get__version__)
553
class _PluginImporter(object):
554
"""An importer tailored to bzr specific needs.
556
This is a singleton that takes care of:
557
- disabled plugins specified in 'blacklist',
558
- plugins that needs to be loaded from specific directories.
565
self.blacklist = set()
566
self.specific_paths = {}
568
def find_module(self, fullname, parent_path=None):
569
"""Search a plugin module.
571
Disabled plugins raise an import error, plugins with specific paths
572
returns a specific loader.
574
:return: None if the plugin doesn't need special handling, self
577
if not fullname.startswith('bzrlib.plugins.'):
579
if fullname in self.blacklist:
580
raise ImportError('%s is disabled' % fullname)
581
if fullname in self.specific_paths:
585
def load_module(self, fullname):
586
"""Load a plugin from a specific directory."""
587
# We are called only for specific paths
588
plugin_path = self.specific_paths[fullname]
590
if os.path.isdir(plugin_path):
591
for suffix, mode, kind in imp.get_suffixes():
592
if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
593
# We don't recognize compiled modules (.so, .dll, etc)
595
init_path = osutils.pathjoin(plugin_path, '__init__' + suffix)
596
if os.path.isfile(init_path):
597
# We've got a module here and load_module needs specific
599
loading_path = plugin_path
602
kind = imp.PKG_DIRECTORY
605
for suffix, mode, kind in imp.get_suffixes():
606
if plugin_path.endswith(suffix):
607
loading_path = plugin_path
609
if loading_path is None:
610
raise ImportError('%s cannot be loaded from %s'
611
% (fullname, plugin_path))
612
if kind is imp.PKG_DIRECTORY:
615
f = open(loading_path, mode)
617
mod = imp.load_module(fullname, f, loading_path,
618
(suffix, mode, kind))
619
mod.__package__ = fullname
626
# Install a dedicated importer for plugins requiring special handling
627
PluginImporter = _PluginImporter()
628
sys.meta_path.append(PluginImporter)
added
removed
bzrlib/plugin.py
