1
# Copyright (C) 2004, 2005, 2007, 2008 Canonical Ltd
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.
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.
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
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
36
from bzrlib import osutils
38
from bzrlib.lazy_import import lazy_import
40
lazy_import(globals(), """
52
from bzrlib import plugins as _mod_plugins
55
from bzrlib.symbol_versioning import deprecated_function, one_three
58
DEFAULT_PLUGIN_PATH = None
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
69
def disable_plugins():
70
"""Disable loading plugins.
72
Future calls to load_plugins() will be ignored.
74
# TODO: jam 20060131 This should probably also disable
80
def _strip_trailing_sep(path):
81
return path.rstrip("\\/")
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':
112
from distutils.sysconfig import get_python_lib
114
# If distutuils is not available, we just won't add that path
117
archless_path = osutils.pathjoin(get_python_lib(), 'bzrlib',
119
if archless_path not in path:
120
path.append(archless_path)
121
_mod_plugins.__path__ = path
126
"""Load bzrlib plugins.
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,
133
load_from_dirs() provides the underlying mechanism and is called with
134
the default directory list to provide the normal behaviour.
138
# People can make sure plugins are loaded, they just won't be twice
142
# scan for all plugins in the path.
143
load_from_path(set_plugins_path())
146
def load_from_path(dirs):
147
"""Load bzrlib plugins found in each dir in dirs.
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.)
153
Plugins are loaded into bzrlib.plugins.NAME, and can be found there
154
for future reference.
156
The python module path for bzrlib.plugins will be modified to be 'dirs'.
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)
167
trace.mutter('looking for plugins in %s', d)
172
# backwards compatability: load_from_dirs was the old name
173
# This was changed in 0.15
174
load_from_dirs = load_from_path
177
def load_from_dir(d):
178
"""Load the plugins in directory d.
180
d must be in the plugins module path already.
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]
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
195
if os.path.isfile(osutils.pathjoin(path, entry)):
197
else: # This directory is not a package
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')]
209
continue # We don't load __init__.py again in the plugin dir
210
elif getattr(_mod_plugins, f, None):
211
trace.mutter('Plugin name %s already loaded', f)
213
# trace.mutter('add plugin name %s', f)
216
for name in plugin_names:
218
exec "import bzrlib.plugins.%s" % name in {}
219
except KeyboardInterrupt:
221
except errors.IncompatibleAPI, e:
222
trace.warning("Unable to load plugin %r. It requested API version "
223
"%s of module %s but the minimum exported version is %s, and "
224
"the maximum is %s" %
225
(name, e.wanted, e.api, e.minimum, e.current))
227
trace.warning("%s" % e)
228
## import pdb; pdb.set_trace()
229
if re.search('\.|-| ', name):
230
sanitised_name = re.sub('[-. ]', '_', name)
231
if sanitised_name.startswith('bzr_'):
232
sanitised_name = sanitised_name[len('bzr_'):]
233
trace.warning("Unable to load %r in %r as a plugin because the "
234
"file path isn't a valid module name; try renaming "
235
"it to %r." % (name, d, sanitised_name))
237
trace.warning('Unable to load plugin %r from %r' % (name, d))
238
trace.log_exception_quietly()
239
if 'error' in debug.debug_flags:
240
trace.print_exception(sys.exc_info(), sys.stderr)
243
@deprecated_function(one_three)
244
def load_from_zip(zip_name):
245
"""Load all the plugins in a zip."""
246
valid_suffixes = ('.py', '.pyc', '.pyo') # only python modules/packages
249
index = zip_name.rindex('.zip')
252
archive = zip_name[:index+4]
253
prefix = zip_name[index+5:]
255
trace.mutter('Looking for plugins in %r', zip_name)
257
# use zipfile to get list of files/dirs inside zip
259
z = zipfile.ZipFile(archive)
260
namelist = z.namelist()
262
except zipfile.error:
267
prefix = prefix.replace('\\','/')
268
if prefix[-1] != '/':
271
namelist = [name[ix:]
273
if name.startswith(prefix)]
275
trace.mutter('Names in archive: %r', namelist)
277
for name in namelist:
278
if not name or name.endswith('/'):
281
# '/' is used to separate pathname components inside zip archives
284
head, tail = '', name
286
head, tail = name.rsplit('/',1)
288
# we don't need looking in subdirectories
291
base, suffix = osutils.splitext(tail)
292
if suffix not in valid_suffixes:
295
if base == '__init__':
306
if getattr(_mod_plugins, plugin_name, None):
307
trace.mutter('Plugin name %s already loaded', plugin_name)
311
exec "import bzrlib.plugins.%s" % plugin_name in {}
312
trace.mutter('Load plugin %s from zip %r', plugin_name, zip_name)
313
except KeyboardInterrupt:
316
## import pdb; pdb.set_trace()
317
trace.warning('Unable to load plugin %r from %r'
319
trace.log_exception_quietly()
320
if 'error' in debug.debug_flags:
321
trace.print_exception(sys.exc_info(), sys.stderr)
325
"""Return a dictionary of the plugins.
327
Each item in the dictionary is a PlugIn object.
330
for name, plugin in _mod_plugins.__dict__.items():
331
if isinstance(plugin, types.ModuleType):
332
result[name] = PlugIn(name, plugin)
336
class PluginsHelpIndex(object):
337
"""A help index that returns help topics for plugins."""
340
self.prefix = 'plugins/'
342
def get_topics(self, topic):
343
"""Search for topic in the loaded plugins.
345
This will not trigger loading of new plugins.
347
:param topic: A topic to search for.
348
:return: A list which is either empty or contains a single
349
RegisteredTopic entry.
353
if topic.startswith(self.prefix):
354
topic = topic[len(self.prefix):]
355
plugin_module_name = 'bzrlib.plugins.%s' % topic
357
module = sys.modules[plugin_module_name]
361
return [ModuleHelpTopic(module)]
364
class ModuleHelpTopic(object):
365
"""A help topic which returns the docstring for a module."""
367
def __init__(self, module):
370
:param module: The module for which help should be generated.
374
def get_help_text(self, additional_see_also=None):
375
"""Return a string with the help for this topic.
377
:param additional_see_also: Additional help topics to be
380
if not self.module.__doc__:
381
result = "Plugin '%s' has no docstring.\n" % self.module.__name__
383
result = self.module.__doc__
384
if result[-1] != '\n':
386
# there is code duplicated here and in bzrlib/help_topic.py's
387
# matching Topic code. This should probably be factored in
388
# to a helper function and a common base class.
389
if additional_see_also is not None:
390
see_also = sorted(set(additional_see_also))
394
result += 'See also: '
395
result += ', '.join(see_also)
399
def get_help_topic(self):
400
"""Return the modules help topic - its __name__ after bzrlib.plugins.."""
401
return self.module.__name__[len('bzrlib.plugins.'):]
404
class PlugIn(object):
405
"""The bzrlib representation of a plugin.
407
The PlugIn object provides a way to manipulate a given plugin module.
410
def __init__(self, name, module):
411
"""Construct a plugin for module."""
416
"""Get the path that this plugin was loaded from."""
417
if getattr(self.module, '__path__', None) is not None:
418
return os.path.abspath(self.module.__path__[0])
419
elif getattr(self.module, '__file__', None) is not None:
420
path = os.path.abspath(self.module.__file__)
421
if path[-4:] in ('.pyc', '.pyo'):
422
pypath = path[:-4] + '.py'
423
if os.path.isfile(pypath):
427
return repr(self.module)
430
return "<%s.%s object at %s, name=%s, module=%s>" % (
431
self.__class__.__module__, self.__class__.__name__, id(self),
432
self.name, self.module)
436
def test_suite(self):
437
"""Return the plugin's test suite."""
438
if getattr(self.module, 'test_suite', None) is not None:
439
return self.module.test_suite()
443
def load_plugin_tests(self, loader):
444
"""Return the adapted plugin's test suite.
446
:param loader: The custom loader that should be used to load additional
450
if getattr(self.module, 'load_tests', None) is not None:
451
return loader.loadTestsFromModule(self.module)
455
def version_info(self):
456
"""Return the plugin's version_tuple or None if unknown."""
457
version_info = getattr(self.module, 'version_info', None)
458
if version_info is not None and len(version_info) == 3:
459
version_info = tuple(version_info) + ('final', 0)
462
def _get__version__(self):
463
version_info = self.version_info()
464
if version_info is None:
466
if version_info[3] == 'final':
467
version_string = '%d.%d.%d' % version_info[:3]
469
version_string = '%d.%d.%d%s%d' % version_info
470
return version_string
472
__version__ = property(_get__version__)
added
removed
bzrlib/plugin.py
