1
# Copyright (C) 2005-2011 Canonical Ltd, 2017 Breezy developers
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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
"""Breezy plugin support.
19
Which plugins to load can be configured by setting these environment variables:
21
- BRZ_PLUGIN_PATH: Paths to look for plugins in.
22
- BRZ_DISABLE_PLUGINS: Plugin names to block from being loaded.
23
- BRZ_PLUGINS_AT: Name and paths for plugins to load from specific locations.
25
The interfaces this module exports include:
27
- disable_plugins: Load no plugins and stop future automatic loading.
28
- load_plugins: Load all plugins that can be found in configuration.
29
- describe_plugins: Generate text for each loaded (or failed) plugin.
30
- extend_path: Mechanism by which the plugins package path is set.
31
- plugin_name: Gives unprefixed name of a plugin module.
33
See the plugin-api developer documentation for information about writing
37
from __future__ import absolute_import
46
from .lazy_import import lazy_import
47
lazy_import(globals(), """
49
from importlib import util as importlib_util
64
_MODULE_PREFIX = "breezy.plugins."
66
if __debug__ or sys.version_info > (3,):
72
def disable_plugins(state=None):
73
"""Disable loading plugins.
75
Future calls to load_plugins() will be ignored.
77
:param state: The library state object that records loaded plugins.
80
state = breezy.get_global_state()
84
def load_plugins(path=None, state=None, warn_load_problems=True):
85
"""Load breezy plugins.
87
The environment variable BRZ_PLUGIN_PATH is considered a delimited
88
set of paths to look through. Each entry is searched for `*.py`
89
files (and whatever other extensions are used in the platform,
92
:param path: The list of paths to search for plugins. By default,
93
it is populated from the __path__ of the breezy.plugins package.
94
:param state: The library state object that records loaded plugins.
97
state = breezy.get_global_state()
98
if getattr(state, 'plugins', None) is not None:
99
# People can make sure plugins are loaded, they just won't be twice
103
# Calls back into extend_path() here
104
from breezy.plugins import __path__ as path
106
state.plugin_warnings = {}
107
_load_plugins_from_path(state, path)
108
if (None, 'entrypoints') in _env_plugin_path():
109
_load_plugins_from_entrypoints(state)
110
state.plugins = plugins()
111
if warn_load_problems:
112
for plugin, errors in state.plugin_warnings.items():
114
trace.warning('%s', error)
117
def _load_plugins_from_entrypoints(state):
121
# No pkg_resources, no entrypoints.
124
for ep in pkg_resources.iter_entry_points('breezy.plugin'):
125
fullname = _MODULE_PREFIX + ep.name
126
if fullname in sys.modules:
128
sys.modules[fullname] = ep.load()
131
def plugin_name(module_name):
132
"""Gives unprefixed name from module_name or None."""
133
if module_name.startswith(_MODULE_PREFIX):
134
parts = module_name.split(".")
140
def extend_path(path, name):
141
"""Helper so breezy.plugins can be a sort of namespace package.
143
To be used in similar fashion to pkgutil.extend_path:
145
from breezy.plugins import extend_path
146
__path__ = extend_path(__path__, __name__)
148
Inspects the BRZ_PLUGIN* envvars, sys.path, and the filesystem to find
149
plugins. May mutate sys.modules in order to block plugin loading, and may
150
append a new meta path finder to sys.meta_path for plugins@ loading.
152
Returns a list of paths to import from, as an enhanced object that also
153
contains details of the other configuration used.
155
blocks = _env_disable_plugins()
156
_block_plugins(blocks)
158
extra_details = _env_plugins_at()
159
_install_importer_if_needed(extra_details)
161
paths = _iter_plugin_paths(_env_plugin_path(), path)
163
return _Path(name, blocks, extra_details, paths)
167
"""List type to use as __path__ but containing additional details.
169
Python 3 allows any iterable for __path__ but Python 2 is more fussy.
172
def __init__(self, package_name, blocked, extra, paths):
173
super(_Path, self).__init__(paths)
174
self.package_name = package_name
175
self.blocked_names = blocked
176
self.extra_details = extra
179
return "%s(%r, %r, %r, %s)" % (
180
self.__class__.__name__, self.package_name, self.blocked_names,
181
self.extra_details, list.__repr__(self))
184
def _expect_identifier(name, env_key, env_value):
185
"""Validate given name from envvar is usable as a Python identifier.
187
Returns the name as a native str, or None if it was invalid.
189
Per PEP 3131 this is no longer strictly correct for Python 3, but as MvL
190
didn't include a neat way to check except eval, this enforces ascii.
192
if re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name) is None:
193
trace.warning("Invalid name '%s' in %s='%s'", name, env_key, env_value)
198
def _env_disable_plugins(key='BRZ_DISABLE_PLUGINS'):
199
"""Gives list of names for plugins to disable from environ key."""
201
env = osutils.path_from_environ(key)
203
for name in env.split(os.pathsep):
204
name = _expect_identifier(name, key, env)
206
disabled_names.append(name)
207
return disabled_names
210
def _env_plugins_at(key='BRZ_PLUGINS_AT'):
211
"""Gives list of names and paths of specific plugins from environ key."""
213
env = osutils.path_from_environ(key)
215
for pair in env.split(os.pathsep):
217
name, path = pair.split('@', 1)
220
name = osutils.basename(path).split('.', 1)[0]
221
name = _expect_identifier(name, key, env)
223
plugin_details.append((name, path))
224
return plugin_details
227
def _env_plugin_path(key='BRZ_PLUGIN_PATH'):
228
"""Gives list of paths and contexts for plugins from environ key.
230
Each entry is either a specific path to load plugins from and the value
231
'path', or None and one of the values 'user', 'core', 'entrypoints', 'site'.
234
env = osutils.path_from_environ(key)
239
'entrypoints': False,
242
# Add paths specified by user in order
243
for p in env.split(os.pathsep):
244
flag, name = p[:1], p[1:]
245
if flag in ("+", "-") and name in defaults:
246
if flag == "+" and defaults[name] is not None:
247
path_details.append((None, name))
248
defaults[name] = None
250
path_details.append((p, 'path'))
252
# Add any remaining default paths
253
for name in ('user', 'core', 'entrypoints', 'site'):
255
path_details.append((None, name))
260
def _iter_plugin_paths(paths_from_env, core_paths):
261
"""Generate paths using paths_from_env and core_paths."""
262
# GZ 2017-06-02: This is kinda horrid, should make better.
263
for path, context in paths_from_env:
264
if context == 'path':
266
elif context == 'user':
267
path = get_user_plugin_path()
268
if os.path.isdir(path):
270
elif context == 'core':
271
for path in _get_core_plugin_paths(core_paths):
273
elif context == 'site':
274
for path in _get_site_plugin_paths(sys.path):
275
if os.path.isdir(path):
279
def _install_importer_if_needed(plugin_details):
280
"""Install a meta path finder to handle plugin_details if any."""
282
finder = _PluginsAtFinder(_MODULE_PREFIX, plugin_details)
283
# For Python 3, must insert before default PathFinder to override.
284
sys.meta_path.insert(2, finder)
287
def _load_plugins_from_path(state, paths):
288
"""Do the importing all plugins from paths."""
289
imported_names = set()
290
for name, path in _iter_possible_plugins(paths):
291
if name not in imported_names:
292
msg = _load_plugin_module(name, path)
294
state.plugin_warnings.setdefault(name, []).append(msg)
295
imported_names.add(name)
298
def _block_plugins(names):
299
"""Add names to sys.modules to block future imports."""
301
package_name = _MODULE_PREFIX + name
302
if sys.modules.get(package_name) is not None:
303
trace.mutter("Blocked plugin %s already loaded.", name)
304
sys.modules[package_name] = None
307
def _get_package_init(package_path):
308
"""Get path of __init__ file from package_path or None if not a package."""
309
init_path = osutils.pathjoin(package_path, "__init__.py")
310
if os.path.exists(init_path):
312
init_path = init_path[:-3] + COMPILED_EXT
313
if os.path.exists(init_path):
318
def _iter_possible_plugins(plugin_paths):
319
"""Generate names and paths of possible plugins from plugin_paths."""
320
# Inspect any from BRZ_PLUGINS_AT first.
321
for name, path in getattr(plugin_paths, "extra_details", ()):
323
# Then walk over files and directories in the paths from the package.
324
for path in plugin_paths:
325
if os.path.isfile(path):
326
if path.endswith(".zip"):
327
trace.mutter("Don't yet support loading plugins from zip.")
329
for name, path in _walk_modules(path):
333
def _walk_modules(path):
334
"""Generate name and path of modules and packages on path."""
335
for root, dirs, files in os.walk(path):
339
if f.endswith((".py", COMPILED_EXT)):
340
yield f.rsplit(".", 1)[0], root
344
package_dir = osutils.pathjoin(root, d)
345
fullpath = _get_package_init(package_dir)
346
if fullpath is not None:
348
# Don't descend into subdirectories
352
def describe_plugins(show_paths=False, state=None):
353
"""Generate text description of plugins.
355
Includes both those that have loaded, and those that failed to load.
357
:param show_paths: If true, include the plugin path.
358
:param state: The library state object to inspect.
359
:returns: Iterator of text lines (including newlines.)
362
state = breezy.get_global_state()
363
loaded_plugins = getattr(state, 'plugins', {})
364
plugin_warnings = set(getattr(state, 'plugin_warnings', []))
365
all_names = sorted(set(loaded_plugins.keys()).union(plugin_warnings))
366
for name in all_names:
367
if name in loaded_plugins:
368
plugin = loaded_plugins[name]
369
version = plugin.__version__
370
if version == 'unknown':
372
yield '%s %s\n' % (name, version)
373
d = plugin.module.__doc__
375
doc = d.split('\n')[0]
377
doc = '(no description)'
378
yield (" %s\n" % doc)
380
yield (" %s\n" % plugin.path())
382
yield "%s (failed to load)\n" % name
383
if name in state.plugin_warnings:
384
for line in state.plugin_warnings[name]:
385
yield " ** " + line + '\n'
389
def _get_core_plugin_paths(existing_paths):
390
"""Generate possible locations for plugins based on existing_paths."""
391
if getattr(sys, 'frozen', False):
392
# We need to use relative path to system-wide plugin
393
# directory because breezy from standalone brz.exe
394
# could be imported by another standalone program
395
# (e.g. brz-config; or TortoiseBzr/Olive if/when they
396
# will become standalone exe). [bialix 20071123]
397
# __file__ typically is
398
# C:\Program Files\Bazaar\lib\library.zip\breezy\plugin.pyc
399
# then plugins directory is
400
# C:\Program Files\Bazaar\plugins
401
# so relative path is ../../../plugins
402
yield osutils.abspath(osutils.pathjoin(
403
osutils.dirname(__file__), '../../../plugins'))
404
else: # don't look inside library.zip
405
for path in existing_paths:
409
def _get_site_plugin_paths(sys_paths):
410
"""Generate possible locations for plugins from given sys_paths."""
411
for path in sys_paths:
412
if os.path.basename(path) in ('dist-packages', 'site-packages'):
413
yield osutils.pathjoin(path, 'breezy', 'plugins')
416
def get_user_plugin_path():
417
return osutils.pathjoin(bedding.config_dir(), 'plugins')
420
def record_plugin_warning(warning_message):
421
trace.mutter(warning_message)
422
return warning_message
425
def _load_plugin_module(name, dir):
426
"""Load plugin by name.
428
:param name: The plugin name in the breezy.plugins namespace.
429
:param dir: The directory the plugin is loaded from for error messages.
431
if _MODULE_PREFIX + name in sys.modules:
434
__import__(_MODULE_PREFIX + name)
435
except errors.IncompatibleVersion as e:
437
"Unable to load plugin %r. It supports %s "
438
"versions %r but the current version is %s" %
439
(name, e.api.__name__, e.wanted, e.current))
440
return record_plugin_warning(warning_message)
441
except Exception as e:
442
trace.log_exception_quietly()
443
if 'error' in debug.debug_flags:
444
trace.print_exception(sys.exc_info(), sys.stderr)
445
# GZ 2017-06-02: Move this name checking up a level, no point trying
446
# to import things with bad names.
447
if re.search('\\.|-| ', name):
448
sanitised_name = re.sub('[-. ]', '_', name)
449
if sanitised_name.startswith('brz_'):
450
sanitised_name = sanitised_name[len('brz_'):]
451
trace.warning("Unable to load %r in %r as a plugin because the "
452
"file path isn't a valid module name; try renaming "
453
"it to %r." % (name, dir, sanitised_name))
455
return record_plugin_warning(
456
'Unable to load plugin %r from %r: %s' % (name, dir, e))
460
"""Return a dictionary of the plugins.
462
Each item in the dictionary is a PlugIn object.
465
for fullname in sys.modules:
466
if fullname.startswith(_MODULE_PREFIX):
467
name = fullname[len(_MODULE_PREFIX):]
468
if "." not in name and sys.modules[fullname] is not None:
469
result[name] = PlugIn(name, sys.modules[fullname])
473
def get_loaded_plugin(name):
474
"""Retrieve an already loaded plugin.
476
Returns None if there is no such plugin loaded
479
module = sys.modules[_MODULE_PREFIX + name]
484
return PlugIn(name, module)
487
def format_concise_plugin_list(state=None):
488
"""Return a string holding a concise list of plugins and their version.
491
state = breezy.get_global_state()
493
for name, a_plugin in sorted(getattr(state, 'plugins', {}).items()):
494
items.append("%s[%s]" %
495
(name, a_plugin.__version__))
496
return ', '.join(items)
499
class PluginsHelpIndex(object):
500
"""A help index that returns help topics for plugins."""
503
self.prefix = 'plugins/'
505
def get_topics(self, topic):
506
"""Search for topic in the loaded plugins.
508
This will not trigger loading of new plugins.
510
:param topic: A topic to search for.
511
:return: A list which is either empty or contains a single
512
RegisteredTopic entry.
516
if topic.startswith(self.prefix):
517
topic = topic[len(self.prefix):]
518
plugin_module_name = _MODULE_PREFIX + topic
520
module = sys.modules[plugin_module_name]
524
return [ModuleHelpTopic(module)]
527
class ModuleHelpTopic(object):
528
"""A help topic which returns the docstring for a module."""
530
def __init__(self, module):
533
:param module: The module for which help should be generated.
537
def get_help_text(self, additional_see_also=None, verbose=True):
538
"""Return a string with the help for this topic.
540
:param additional_see_also: Additional help topics to be
543
if not self.module.__doc__:
544
result = "Plugin '%s' has no docstring.\n" % self.module.__name__
546
result = self.module.__doc__
547
if result[-1] != '\n':
549
result += help_topics._format_see_also(additional_see_also)
552
def get_help_topic(self):
553
"""Return the module help topic: its basename."""
554
return self.module.__name__[len(_MODULE_PREFIX):]
557
class PlugIn(object):
558
"""The breezy representation of a plugin.
560
The PlugIn object provides a way to manipulate a given plugin module.
563
def __init__(self, name, module):
564
"""Construct a plugin for module."""
569
"""Get the path that this plugin was loaded from."""
570
if getattr(self.module, '__path__', None) is not None:
571
return os.path.abspath(self.module.__path__[0])
572
elif getattr(self.module, '__file__', None) is not None:
573
path = os.path.abspath(self.module.__file__)
574
if path[-4:] == COMPILED_EXT:
575
pypath = path[:-4] + '.py'
576
if os.path.isfile(pypath):
580
return repr(self.module)
583
return "<%s.%s name=%s, module=%s>" % (
584
self.__class__.__module__, self.__class__.__name__,
585
self.name, self.module)
587
def test_suite(self):
588
"""Return the plugin's test suite."""
589
if getattr(self.module, 'test_suite', None) is not None:
590
return self.module.test_suite()
594
def load_plugin_tests(self, loader):
595
"""Return the adapted plugin's test suite.
597
:param loader: The custom loader that should be used to load additional
600
if getattr(self.module, 'load_tests', None) is not None:
601
return loader.loadTestsFromModule(self.module)
605
def version_info(self):
606
"""Return the plugin's version_tuple or None if unknown."""
607
version_info = getattr(self.module, 'version_info', None)
608
if version_info is not None:
610
if isinstance(version_info, str):
611
version_info = version_info.split('.')
612
elif len(version_info) == 3:
613
version_info = tuple(version_info) + ('final', 0)
615
# The given version_info isn't even iteratible
616
trace.log_exception_quietly()
617
version_info = (version_info,)
621
def __version__(self):
622
version_info = self.version_info()
623
if version_info is None or len(version_info) == 0:
626
version_string = breezy._format_version_tuple(version_info)
627
except (ValueError, TypeError, IndexError):
628
trace.log_exception_quietly()
629
# Try to show something for the version anyway
630
version_string = '.'.join(map(str, version_info))
631
return version_string
634
class _PluginsAtFinder(object):
635
"""Meta path finder to support BRZ_PLUGINS_AT configuration."""
637
def __init__(self, prefix, names_and_paths):
639
self.names_to_path = dict((prefix + n, p) for n, p in names_and_paths)
642
return "<%s %r>" % (self.__class__.__name__, self.prefix)
644
def find_spec(self, fullname, paths, target=None):
645
"""New module spec returning find method."""
646
if fullname not in self.names_to_path:
648
path = self.names_to_path[fullname]
649
if os.path.isdir(path):
650
path = _get_package_init(path)
652
# GZ 2017-06-02: Any reason to block loading of the name from
653
# further down the path like this?
654
raise ImportError("Not loading namespace package %s as %s" % (
656
return importlib_util.spec_from_file_location(fullname, path)
658
def find_module(self, fullname, path):
659
"""Old PEP 302 import hook find_module method."""
660
if fullname not in self.names_to_path:
662
return _LegacyLoader(self.names_to_path[fullname])
665
class _LegacyLoader(object):
666
"""Source loader implementation for Python versions without importlib."""
668
def __init__(self, filepath):
669
self.filepath = filepath
672
return "<%s %r>" % (self.__class__.__name__, self.filepath)
674
def load_module(self, fullname):
675
"""Load a plugin from a specific directory (or file)."""
676
plugin_path = self.filepath
678
if os.path.isdir(plugin_path):
679
init_path = _get_package_init(plugin_path)
680
if init_path is not None:
681
loading_path = plugin_path
684
kind = imp.PKG_DIRECTORY
686
for suffix, mode, kind in imp.get_suffixes():
687
if plugin_path.endswith(suffix):
688
loading_path = plugin_path
690
if loading_path is None:
691
raise ImportError('%s cannot be loaded from %s'
692
% (fullname, plugin_path))
693
if kind is imp.PKG_DIRECTORY:
696
f = open(loading_path, mode)
698
mod = imp.load_module(fullname, f, loading_path,
699
(suffix, mode, kind))
700
mod.__package__ = fullname
added
removed
breezy/plugin.py
