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')]
208
if getattr(_mod_plugins, f, None):
209
trace.mutter('Plugin name %s already loaded', f)
211
# trace.mutter('add plugin name %s', f)
214
for name in plugin_names:
216
exec "import bzrlib.plugins.%s" % name in {}
217
except KeyboardInterrupt:
219
except errors.IncompatibleAPI, e:
220
trace.warning("Unable to load plugin %r. It requested API version "
221
"%s of module %s but the minimum exported version is %s, and "
222
"the maximum is %s" %
223
(name, e.wanted, e.api, e.minimum, e.current))
225
trace.warning("%s" % e)
226
## import pdb; pdb.set_trace()
227
if re.search('\.|-| ', name):
228
sanitised_name = re.sub('[-. ]', '_', name)
229
if sanitised_name.startswith('bzr_'):
230
sanitised_name = sanitised_name[len('bzr_'):]
231
trace.warning("Unable to load %r in %r as a plugin because the "
232
"file path isn't a valid module name; try renaming "
233
"it to %r." % (name, d, sanitised_name))
235
trace.warning('Unable to load plugin %r from %r' % (name, d))
236
trace.log_exception_quietly()
237
if 'error' in debug.debug_flags:
238
trace.print_exception(sys.exc_info(), sys.stderr)
241
@deprecated_function(one_three)
242
def load_from_zip(zip_name):
243
"""Load all the plugins in a zip."""
244
valid_suffixes = ('.py', '.pyc', '.pyo') # only python modules/packages
247
index = zip_name.rindex('.zip')
250
archive = zip_name[:index+4]
251
prefix = zip_name[index+5:]
253
trace.mutter('Looking for plugins in %r', zip_name)
255
# use zipfile to get list of files/dirs inside zip
257
z = zipfile.ZipFile(archive)
258
namelist = z.namelist()
260
except zipfile.error:
265
prefix = prefix.replace('\\','/')
266
if prefix[-1] != '/':
269
namelist = [name[ix:]
271
if name.startswith(prefix)]
273
trace.mutter('Names in archive: %r', namelist)
275
for name in namelist:
276
if not name or name.endswith('/'):
279
# '/' is used to separate pathname components inside zip archives
282
head, tail = '', name
284
head, tail = name.rsplit('/',1)
286
# we don't need looking in subdirectories
289
base, suffix = osutils.splitext(tail)
290
if suffix not in valid_suffixes:
293
if base == '__init__':
304
if getattr(_mod_plugins, plugin_name, None):
305
trace.mutter('Plugin name %s already loaded', plugin_name)
309
exec "import bzrlib.plugins.%s" % plugin_name in {}
310
trace.mutter('Load plugin %s from zip %r', plugin_name, zip_name)
311
except KeyboardInterrupt:
314
## import pdb; pdb.set_trace()
315
trace.warning('Unable to load plugin %r from %r'
317
trace.log_exception_quietly()
318
if 'error' in debug.debug_flags:
319
trace.print_exception(sys.exc_info(), sys.stderr)
323
"""Return a dictionary of the plugins.
325
Each item in the dictionary is a PlugIn object.
328
for name, plugin in _mod_plugins.__dict__.items():
329
if isinstance(plugin, types.ModuleType):
330
result[name] = PlugIn(name, plugin)
334
class PluginsHelpIndex(object):
335
"""A help index that returns help topics for plugins."""
338
self.prefix = 'plugins/'
340
def get_topics(self, topic):
341
"""Search for topic in the loaded plugins.
343
This will not trigger loading of new plugins.
345
:param topic: A topic to search for.
346
:return: A list which is either empty or contains a single
347
RegisteredTopic entry.
351
if topic.startswith(self.prefix):
352
topic = topic[len(self.prefix):]
353
plugin_module_name = 'bzrlib.plugins.%s' % topic
355
module = sys.modules[plugin_module_name]
359
return [ModuleHelpTopic(module)]
362
class ModuleHelpTopic(object):
363
"""A help topic which returns the docstring for a module."""
365
def __init__(self, module):
368
:param module: The module for which help should be generated.
372
def get_help_text(self, additional_see_also=None):
373
"""Return a string with the help for this topic.
375
:param additional_see_also: Additional help topics to be
378
if not self.module.__doc__:
379
result = "Plugin '%s' has no docstring.\n" % self.module.__name__
381
result = self.module.__doc__
382
if result[-1] != '\n':
384
# there is code duplicated here and in bzrlib/help_topic.py's
385
# matching Topic code. This should probably be factored in
386
# to a helper function and a common base class.
387
if additional_see_also is not None:
388
see_also = sorted(set(additional_see_also))
392
result += 'See also: '
393
result += ', '.join(see_also)
397
def get_help_topic(self):
398
"""Return the modules help topic - its __name__ after bzrlib.plugins.."""
399
return self.module.__name__[len('bzrlib.plugins.'):]
402
class PlugIn(object):
403
"""The bzrlib representation of a plugin.
405
The PlugIn object provides a way to manipulate a given plugin module.
408
def __init__(self, name, module):
409
"""Construct a plugin for module."""
414
"""Get the path that this plugin was loaded from."""
415
if getattr(self.module, '__path__', None) is not None:
416
return os.path.abspath(self.module.__path__[0])
417
elif getattr(self.module, '__file__', None) is not None:
418
path = os.path.abspath(self.module.__file__)
419
if path[-4:] in ('.pyc', '.pyo'):
420
pypath = path[:-4] + '.py'
421
if os.path.isfile(pypath):
425
return repr(self.module)
428
return "<%s.%s object at %s, name=%s, module=%s>" % (
429
self.__class__.__module__, self.__class__.__name__, id(self),
430
self.name, self.module)
434
def test_suite(self):
435
"""Return the plugin's test suite."""
436
if getattr(self.module, 'test_suite', None) is not None:
437
return self.module.test_suite()
441
def load_plugin_tests(self, loader):
442
"""Return the adapted plugin's test suite.
444
:param loader: The custom loader that should be used to load additional
448
if getattr(self.module, 'load_tests', None) is not None:
449
return loader.loadTestsFromModule(self.module)
453
def version_info(self):
454
"""Return the plugin's version_tuple or None if unknown."""
455
version_info = getattr(self.module, 'version_info', None)
456
if version_info is not None and len(version_info) == 3:
457
version_info = tuple(version_info) + ('final', 0)
460
def _get__version__(self):
461
version_info = self.version_info()
462
if version_info is None:
464
if version_info[3] == 'final':
465
version_string = '%d.%d.%d' % version_info[:3]
467
version_string = '%d.%d.%d%s%d' % version_info
468
return version_string
470
__version__ = property(_get__version__)
added
removed
bzrlib/plugin.py
