14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18
17
"""bzr python plugin support.
20
19
When load_plugins() is invoked, any python module in any directory in
21
20
$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.
21
'brzlib.plugins.$BASENAME(PLUGIN)'. In the plugin's main body, it should
22
update any brzlib registries it wants to extend.
25
24
See the plugin-api developer documentation for information about writing
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 brzlib.plugins.PLUGINNAME', as long as set_plugins_path has been
32
from __future__ import absolute_import
36
from bzrlib import osutils
38
from bzrlib.lazy_import import lazy_import
37
from brzlib import osutils
39
from brzlib.lazy_import import lazy_import
40
40
lazy_import(globals(), """
46
46
_format_version_tuple,
52
from bzrlib import plugins as _mod_plugins
52
from brzlib.i18n import gettext
53
from brzlib import plugins as _mod_plugins
55
from bzrlib.symbol_versioning import (
61
57
DEFAULT_PLUGIN_PATH = None
63
59
_plugins_disabled = False
63
# Map from plugin name, to list of string warnings about eg plugin
66
67
def are_plugins_disabled():
67
68
return _plugins_disabled
81
def describe_plugins(show_paths=False):
82
"""Generate text description of plugins.
84
Includes both those that have loaded, and those that failed to
87
:param show_paths: If true,
88
:returns: Iterator of text lines (including newlines.)
90
from inspect import getdoc
91
loaded_plugins = plugins()
92
all_names = sorted(list(set(
93
loaded_plugins.keys() + plugin_warnings.keys())))
94
for name in all_names:
95
if name in loaded_plugins:
96
plugin = loaded_plugins[name]
97
version = plugin.__version__
98
if version == 'unknown':
100
yield '%s %s\n' % (name, version)
101
d = getdoc(plugin.module)
103
doc = d.split('\n')[0]
105
doc = '(no description)'
106
yield (" %s\n" % doc)
108
yield (" %s\n" % plugin.path())
111
yield "%s (failed to load)\n" % name
112
if name in plugin_warnings:
113
for line in plugin_warnings[name]:
114
yield " ** " + line + '\n'
80
118
def _strip_trailing_sep(path):
81
119
return path.rstrip("\\/")
122
def _get_specific_plugin_paths(paths):
123
"""Returns the plugin paths from a string describing the associations.
125
:param paths: A string describing the paths associated with the plugins.
127
:returns: A list of (plugin name, path) tuples.
129
For example, if paths is my_plugin@/test/my-test:her_plugin@/production/her,
130
[('my_plugin', '/test/my-test'), ('her_plugin', '/production/her')]
133
Note that ':' in the example above depends on the os.
138
for spec in paths.split(os.pathsep):
140
name, path = spec.split('@')
142
raise errors.BzrCommandError(gettext(
143
'"%s" is not a valid <plugin_name>@<plugin_path> description ')
145
specs.append((name, path))
84
149
def set_plugins_path(path=None):
85
150
"""Set the path for plugins to be loaded from.
96
161
disabled_plugins = os.environ.get('BZR_DISABLE_PLUGINS', None)
97
162
if disabled_plugins is not None:
98
163
for name in disabled_plugins.split(os.pathsep):
99
PluginImporter.blacklist.add('bzrlib.plugins.' + name)
164
PluginImporter.blacklist.add('brzlib.plugins.' + name)
100
165
# Set up a the specific paths for plugins
101
specific_plugins = os.environ.get('BZR_PLUGINS_AT', None)
102
if specific_plugins is not None:
103
for spec in specific_plugins.split(os.pathsep):
104
plugin_name, plugin_path = spec.split('@')
166
for plugin_name, plugin_path in _get_specific_plugin_paths(os.environ.get(
167
'BZR_PLUGINS_AT', None)):
105
168
PluginImporter.specific_paths[
106
'bzrlib.plugins.%s' % plugin_name] = plugin_path
169
'brzlib.plugins.%s' % plugin_name] = plugin_path
119
182
bzr_exe = bool(getattr(sys, 'frozen', None))
120
183
if bzr_exe: # expand path for bzr.exe
121
184
# We need to use relative path to system-wide plugin
122
# directory because bzrlib from standalone bzr.exe
185
# directory because brzlib from standalone bzr.exe
123
186
# could be imported by another standalone program
124
187
# (e.g. bzr-config; or TortoiseBzr/Olive if/when they
125
188
# will become standalone exe). [bialix 20071123]
126
189
# __file__ typically is
127
# C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
190
# C:\Program Files\Bazaar\lib\library.zip\brzlib\plugin.pyc
128
191
# then plugins directory is
129
192
# C:\Program Files\Bazaar\plugins
130
193
# so relative path is ../../../plugins
131
194
core_path = osutils.abspath(osutils.pathjoin(
132
195
osutils.dirname(__file__), '../../../plugins'))
133
196
else: # don't look inside library.zip
134
# search the plugin path before the bzrlib installed dir
197
# search the plugin path before the brzlib installed dir
135
198
core_path = os.path.dirname(_mod_plugins.__file__)
149
212
# If distutuils is not available, we just don't know where they are
152
site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
215
site_path = osutils.pathjoin(get_python_lib(), 'brzlib', 'plugins')
210
273
def load_plugins(path=None):
211
"""Load bzrlib plugins.
274
"""Load brzlib plugins.
213
276
The environment variable BZR_PLUGIN_PATH is considered a delimited
214
set of paths to look through. Each entry is searched for *.py
277
set of paths to look through. Each entry is searched for `*.py`
215
278
files (and whatever other extensions are used in the platform,
218
281
load_from_path() provides the underlying mechanism and is called with
219
282
the default directory list to provide the normal behaviour.
235
298
def load_from_path(dirs):
236
"""Load bzrlib plugins found in each dir in dirs.
299
"""Load brzlib plugins found in each dir in dirs.
238
301
Loading a plugin means importing it into the python interpreter.
239
302
The plugin is expected to make calls to register commands when
240
303
it's loaded (or perhaps access other hooks in future.)
242
Plugins are loaded into bzrlib.plugins.NAME, and can be found there
305
Plugins are loaded into brzlib.plugins.NAME, and can be found there
243
306
for future reference.
245
The python module path for bzrlib.plugins will be modified to be 'dirs'.
308
The python module path for brzlib.plugins will be modified to be 'dirs'.
247
310
# Explicitly load the plugins with a specific path
248
311
for fullname, path in PluginImporter.specific_paths.iteritems():
249
name = fullname[len('bzrlib.plugins.'):]
312
name = fullname[len('brzlib.plugins.'):]
250
313
_load_plugin_module(name, path)
252
315
# We need to strip the trailing separators here as well as in the
253
316
# set_plugins_path function because calling code can pass anything in to
254
317
# this function, and since it sets plugins.__path__, it should set it to
255
318
# something that will be valid for Python to use (in case people try to
256
# run "import bzrlib.plugins.PLUGINNAME" after calling this function).
319
# run "import brzlib.plugins.PLUGINNAME" after calling this function).
257
320
_mod_plugins.__path__ = map(_strip_trailing_sep, dirs)
302
365
return None, None, (None, None, None)
368
def record_plugin_warning(plugin_name, warning_message):
369
trace.mutter(warning_message)
370
plugin_warnings.setdefault(plugin_name, []).append(warning_message)
305
373
def _load_plugin_module(name, dir):
306
374
"""Load plugin name from dir.
308
:param name: The plugin name in the bzrlib.plugins namespace.
376
:param name: The plugin name in the brzlib.plugins namespace.
309
377
:param dir: The directory the plugin is loaded from for error messages.
311
if ('bzrlib.plugins.%s' % name) in PluginImporter.blacklist:
379
if ('brzlib.plugins.%s' % name) in PluginImporter.blacklist:
314
exec "import bzrlib.plugins.%s" % name in {}
382
exec "import brzlib.plugins.%s" % name in {}
315
383
except KeyboardInterrupt:
317
385
except errors.IncompatibleAPI, e:
318
trace.warning("Unable to load plugin %r. It requested API version "
387
"Unable to load plugin %r. It requested API version "
319
388
"%s of module %s but the minimum exported version is %s, and "
320
389
"the maximum is %s" %
321
390
(name, e.wanted, e.api, e.minimum, e.current))
391
record_plugin_warning(name, warning_message)
322
392
except Exception, e:
323
393
trace.warning("%s" % e)
324
394
if re.search('\.|-| ', name):
329
399
"file path isn't a valid module name; try renaming "
330
400
"it to %r." % (name, dir, sanitised_name))
332
trace.warning('Unable to load plugin %r from %r' % (name, dir))
402
record_plugin_warning(
404
'Unable to load plugin %r from %r' % (name, dir))
333
405
trace.log_exception_quietly()
334
406
if 'error' in debug.debug_flags:
335
407
trace.print_exception(sys.exc_info(), sys.stderr)
347
419
if name is not None:
348
420
if name == '__init__':
349
421
# We do nothing with the __init__.py file in directories from
350
# the bzrlib.plugins module path, we may want to, one day
422
# the brzlib.plugins module path, we may want to, one day
351
423
# -- vila 20100316.
352
424
continue # We don't load __init__.py in the plugins dirs
353
425
elif getattr(_mod_plugins, name, None) is not None:
450
def format_concise_plugin_list():
451
"""Return a string holding a concise list of plugins and their version.
454
for name, a_plugin in sorted(plugins().items()):
455
items.append("%s[%s]" %
456
(name, a_plugin.__version__))
457
return ', '.join(items)
378
461
class PluginsHelpIndex(object):
379
462
"""A help index that returns help topics for plugins."""
395
478
if topic.startswith(self.prefix):
396
479
topic = topic[len(self.prefix):]
397
plugin_module_name = 'bzrlib.plugins.%s' % topic
480
plugin_module_name = 'brzlib.plugins.%s' % topic
399
482
module = sys.modules[plugin_module_name]
425
508
result = self.module.__doc__
426
509
if result[-1] != '\n':
428
# there is code duplicated here and in bzrlib/help_topic.py's
429
# matching Topic code. This should probably be factored in
430
# to a helper function and a common base class.
431
if additional_see_also is not None:
432
see_also = sorted(set(additional_see_also))
436
result += 'See also: '
437
result += ', '.join(see_also)
511
from brzlib import help_topics
512
result += help_topics._format_see_also(additional_see_also)
441
515
def get_help_topic(self):
442
"""Return the modules help topic - its __name__ after bzrlib.plugins.."""
443
return self.module.__name__[len('bzrlib.plugins.'):]
516
"""Return the module help topic: its basename."""
517
return self.module.__name__[len('brzlib.plugins.'):]
446
520
class PlugIn(object):
447
"""The bzrlib representation of a plugin.
521
"""The brzlib representation of a plugin.
449
523
The PlugIn object provides a way to manipulate a given plugin module.
549
623
:return: None if the plugin doesn't need special handling, self
552
if not fullname.startswith('bzrlib.plugins.'):
626
if not fullname.startswith('brzlib.plugins.'):
554
628
if fullname in self.blacklist:
555
629
raise ImportError('%s is disabled' % fullname)
560
634
def load_module(self, fullname):
561
"""Load a plugin from a specific directory."""
635
"""Load a plugin from a specific directory (or file)."""
562
636
# We are called only for specific paths
563
637
plugin_path = self.specific_paths[fullname]
564
638
loading_path = None
566
639
if os.path.isdir(plugin_path):
567
640
for suffix, mode, kind in imp.get_suffixes():
568
641
if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
571
644
init_path = osutils.pathjoin(plugin_path, '__init__' + suffix)
572
645
if os.path.isfile(init_path):
573
loading_path = init_path
646
# We've got a module here and load_module needs specific
648
loading_path = plugin_path
651
kind = imp.PKG_DIRECTORY
577
654
for suffix, mode, kind in imp.get_suffixes():
581
658
if loading_path is None:
582
659
raise ImportError('%s cannot be loaded from %s'
583
660
% (fullname, plugin_path))
584
f = open(loading_path, mode)
661
if kind is imp.PKG_DIRECTORY:
664
f = open(loading_path, mode)
586
666
mod = imp.load_module(fullname, f, loading_path,
587
667
(suffix, mode, kind))
589
# The plugin can contain modules, so be ready
590
mod.__path__ = [plugin_path]
591
668
mod.__package__ = fullname
597
675
# Install a dedicated importer for plugins requiring special handling
added
removed
brzlib/plugin.py
