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
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
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.
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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
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
from bzrlib.lazy_import import lazy_import
40
lazy_import(globals(), """
48
from bzrlib.config import config_dir
49
from bzrlib.trace import log_error, mutter, warning, \
51
from bzrlib.errors import BzrError
52
from bzrlib import plugins
53
from bzrlib.osutils import pathjoin
55
DEFAULT_PLUGIN_PATH = pathjoin(config_dir(), 'plugins')
46
_format_version_tuple,
52
from bzrlib import plugins as _mod_plugins
55
from bzrlib.symbol_versioning import (
61
DEFAULT_PLUGIN_PATH = None
61
"""Return a dictionary of the plugins."""
63
for name, plugin in bzrlib.plugins.__dict__.items():
64
if isinstance(plugin, types.ModuleType):
64
@deprecated_function(deprecated_in((2, 0, 0)))
65
def get_default_plugin_path():
66
"""Get the DEFAULT_PLUGIN_PATH"""
67
global DEFAULT_PLUGIN_PATH
68
if DEFAULT_PLUGIN_PATH is None:
69
DEFAULT_PLUGIN_PATH = osutils.pathjoin(config.config_dir(), 'plugins')
70
return DEFAULT_PLUGIN_PATH
69
73
def disable_plugins():
72
76
Future calls to load_plugins() will be ignored.
74
# TODO: jam 20060131 This should probably also disable
81
def _strip_trailing_sep(path):
82
return path.rstrip("\\/")
85
def set_plugins_path(path=None):
86
"""Set the path for plugins to be loaded from.
88
:param path: The list of paths to search for plugins. By default,
89
path will be determined using get_standard_plugins_path.
90
if path is [], no plugins can be loaded.
93
path = get_standard_plugins_path()
94
_mod_plugins.__path__ = path
98
def _append_new_path(paths, new_path):
99
"""Append a new path if it set and not already known."""
100
if new_path is not None and new_path not in paths:
101
paths.append(new_path)
105
def get_core_plugin_path():
107
bzr_exe = bool(getattr(sys, 'frozen', None))
108
if bzr_exe: # expand path for bzr.exe
109
# We need to use relative path to system-wide plugin
110
# directory because bzrlib from standalone bzr.exe
111
# could be imported by another standalone program
112
# (e.g. bzr-config; or TortoiseBzr/Olive if/when they
113
# will become standalone exe). [bialix 20071123]
114
# __file__ typically is
115
# C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
116
# then plugins directory is
117
# C:\Program Files\Bazaar\plugins
118
# so relative path is ../../../plugins
119
core_path = osutils.abspath(osutils.pathjoin(
120
osutils.dirname(__file__), '../../../plugins'))
121
else: # don't look inside library.zip
122
# search the plugin path before the bzrlib installed dir
123
core_path = os.path.dirname(_mod_plugins.__file__)
127
def get_site_plugin_path():
128
"""Returns the path for the site installed plugins."""
129
if sys.platform == 'win32':
130
# We don't have (yet) a good answer for windows since that is certainly
131
# related to the way we build the installers. -- vila20090821
135
from distutils.sysconfig import get_python_lib
137
# If distutuils is not available, we just don't know where they are
140
site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
144
def get_user_plugin_path():
145
return osutils.pathjoin(config.config_dir(), 'plugins')
148
def get_standard_plugins_path():
149
"""Determine a plugin path suitable for general use."""
150
# Ad-Hoc default: core is not overriden by site but user can overrides both
151
# The rationale is that:
152
# - 'site' comes last, because these plugins should always be available and
153
# are supposed to be in sync with the bzr installed on site.
154
# - 'core' comes before 'site' so that running bzr from sources or a user
155
# installed version overrides the site version.
156
# - 'user' comes first, because... user is always right.
157
# - the above rules clearly defines which plugin version will be loaded if
158
# several exist. Yet, it is sometimes desirable to disable some directory
159
# so that a set of plugins is disabled as once. This can be done via
160
# -site, -core, -user.
162
env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
163
defaults = ['+core', '+site']
165
# The predefined references
166
refs = dict(core=get_core_plugin_path(),
167
site=get_site_plugin_path(),
168
user=get_user_plugin_path())
170
# Unset paths that should be removed
171
for k,v in refs.iteritems():
173
# defaults can never mention removing paths as that will make it
174
# impossible for the user to revoke these removals.
175
if removed in env_paths:
176
env_paths.remove(removed)
181
for p in env_paths + defaults:
182
if p.startswith('+'):
183
# Resolve reference if they are known
187
# Leave them untouched otherwise, user may have paths starting
190
_append_new_path(paths, p)
192
# Get rid of trailing slashes, since Python can't handle them when
193
# it tries to import modules.
194
paths = map(_strip_trailing_sep, paths)
198
def load_plugins(path=None):
81
199
"""Load bzrlib plugins.
83
201
The environment variable BZR_PLUGIN_PATH is considered a delimited
117
262
valid_suffixes = [suffix for suffix, mod_type, flags in imp.get_suffixes()
118
263
if flags in (imp.PY_SOURCE, imp.PY_COMPILED)]
119
264
package_entries = ['__init__'+suffix for suffix in valid_suffixes]
123
mutter('looking for plugins in %s', d)
125
if not os.path.isdir(d):
127
for f in os.listdir(d):
128
path = pathjoin(d, f)
129
if os.path.isdir(path):
130
for entry in package_entries:
131
# This directory should be a package, and thus added to
133
if os.path.isfile(pathjoin(path, entry)):
135
else: # This directory is not a package
138
for suffix_info in imp.get_suffixes():
139
if f.endswith(suffix_info[0]):
140
f = f[:-len(suffix_info[0])]
141
if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
142
f = f[:-len('module')]
146
if getattr(bzrlib.plugins, f, None):
147
mutter('Plugin name %s already loaded', f)
149
mutter('add plugin name %s', f)
152
plugin_names = list(plugin_names)
154
for name in plugin_names:
266
for f in os.listdir(d):
267
path = osutils.pathjoin(d, f)
268
if os.path.isdir(path):
269
for entry in package_entries:
270
# This directory should be a package, and thus added to
272
if os.path.isfile(osutils.pathjoin(path, entry)):
274
else: # This directory is not a package
277
for suffix_info in imp.get_suffixes():
278
if f.endswith(suffix_info[0]):
279
f = f[:-len(suffix_info[0])]
280
if suffix_info[2] == imp.C_EXTENSION and f.endswith('module'):
281
f = f[:-len('module')]
286
continue # We don't load __init__.py again in the plugin dir
287
elif getattr(_mod_plugins, f, None):
288
trace.mutter('Plugin name %s already loaded', f)
290
# trace.mutter('add plugin name %s', f)
293
for name in plugin_names:
295
exec "import bzrlib.plugins.%s" % name in {}
296
except KeyboardInterrupt:
298
except errors.IncompatibleAPI, e:
299
trace.warning("Unable to load plugin %r. It requested API version "
300
"%s of module %s but the minimum exported version is %s, and "
301
"the maximum is %s" %
302
(name, e.wanted, e.api, e.minimum, e.current))
304
trace.warning("%s" % e)
305
## import pdb; pdb.set_trace()
306
if re.search('\.|-| ', name):
307
sanitised_name = re.sub('[-. ]', '_', name)
308
if sanitised_name.startswith('bzr_'):
309
sanitised_name = sanitised_name[len('bzr_'):]
310
trace.warning("Unable to load %r in %r as a plugin because the "
311
"file path isn't a valid module name; try renaming "
312
"it to %r." % (name, d, sanitised_name))
314
trace.warning('Unable to load plugin %r from %r' % (name, d))
315
trace.log_exception_quietly()
316
if 'error' in debug.debug_flags:
317
trace.print_exception(sys.exc_info(), sys.stderr)
321
"""Return a dictionary of the plugins.
323
Each item in the dictionary is a PlugIn object.
326
for name, plugin in _mod_plugins.__dict__.items():
327
if isinstance(plugin, types.ModuleType):
328
result[name] = PlugIn(name, plugin)
332
class PluginsHelpIndex(object):
333
"""A help index that returns help topics for plugins."""
336
self.prefix = 'plugins/'
338
def get_topics(self, topic):
339
"""Search for topic in the loaded plugins.
341
This will not trigger loading of new plugins.
343
:param topic: A topic to search for.
344
:return: A list which is either empty or contains a single
345
RegisteredTopic entry.
349
if topic.startswith(self.prefix):
350
topic = topic[len(self.prefix):]
351
plugin_module_name = 'bzrlib.plugins.%s' % topic
353
module = sys.modules[plugin_module_name]
357
return [ModuleHelpTopic(module)]
360
class ModuleHelpTopic(object):
361
"""A help topic which returns the docstring for a module."""
363
def __init__(self, module):
366
:param module: The module for which help should be generated.
370
def get_help_text(self, additional_see_also=None, verbose=True):
371
"""Return a string with the help for this topic.
373
:param additional_see_also: Additional help topics to be
376
if not self.module.__doc__:
377
result = "Plugin '%s' has no docstring.\n" % self.module.__name__
379
result = self.module.__doc__
380
if result[-1] != '\n':
382
# there is code duplicated here and in bzrlib/help_topic.py's
383
# matching Topic code. This should probably be factored in
384
# to a helper function and a common base class.
385
if additional_see_also is not None:
386
see_also = sorted(set(additional_see_also))
390
result += 'See also: '
391
result += ', '.join(see_also)
395
def get_help_topic(self):
396
"""Return the modules help topic - its __name__ after bzrlib.plugins.."""
397
return self.module.__name__[len('bzrlib.plugins.'):]
400
class PlugIn(object):
401
"""The bzrlib representation of a plugin.
403
The PlugIn object provides a way to manipulate a given plugin module.
406
def __init__(self, name, module):
407
"""Construct a plugin for module."""
412
"""Get the path that this plugin was loaded from."""
413
if getattr(self.module, '__path__', None) is not None:
414
return os.path.abspath(self.module.__path__[0])
415
elif getattr(self.module, '__file__', None) is not None:
416
path = os.path.abspath(self.module.__file__)
417
if path[-4:] in ('.pyc', '.pyo'):
418
pypath = path[:-4] + '.py'
419
if os.path.isfile(pypath):
423
return repr(self.module)
426
return "<%s.%s object at %s, name=%s, module=%s>" % (
427
self.__class__.__module__, self.__class__.__name__, id(self),
428
self.name, self.module)
432
def test_suite(self):
433
"""Return the plugin's test suite."""
434
if getattr(self.module, 'test_suite', None) is not None:
435
return self.module.test_suite()
439
def load_plugin_tests(self, loader):
440
"""Return the adapted plugin's test suite.
442
:param loader: The custom loader that should be used to load additional
446
if getattr(self.module, 'load_tests', None) is not None:
447
return loader.loadTestsFromModule(self.module)
451
def version_info(self):
452
"""Return the plugin's version_tuple or None if unknown."""
453
version_info = getattr(self.module, 'version_info', None)
454
if version_info is not None:
156
plugin_info = imp.find_module(name, [d])
157
mutter('load plugin %r', plugin_info)
159
plugin = imp.load_module('bzrlib.plugins.' + name,
161
setattr(bzrlib.plugins, name, plugin)
163
if plugin_info[0] is not None:
164
plugin_info[0].close()
166
mutter('loaded succesfully')
167
except KeyboardInterrupt:
170
## import pdb; pdb.set_trace()
171
warning('Unable to load plugin %r from %r' % (name, d))
172
log_exception_quietly()
456
if isinstance(version_info, types.StringType):
457
version_info = version_info.split('.')
458
elif len(version_info) == 3:
459
version_info = tuple(version_info) + ('final', 0)
461
# The given version_info isn't even iteratible
462
trace.log_exception_quietly()
463
version_info = (version_info,)
466
def _get__version__(self):
467
version_info = self.version_info()
468
if version_info is None or len(version_info) == 0:
471
version_string = _format_version_tuple(version_info)
472
except (ValueError, TypeError, IndexError), e:
473
trace.log_exception_quietly()
474
# try to return something usefull for bad plugins, in stead of
476
version_string = '.'.join(map(str, version_info))
477
return version_string
479
__version__ = property(_get__version__)
added
removed
bzrlib/plugin.py
