/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/plugin.py

  • Committer: Robert Collins
  • Date: 2010-05-06 11:08:10 UTC
  • mto: This revision was merged to the branch mainline in revision 5223.
  • Revision ID: robertc@robertcollins.net-20100506110810-h3j07fh5gmw54s25
Cleaner matcher matching revised unlocking protocol.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2005-2011 Canonical Ltd, 2017 Breezy developers
 
1
# Copyright (C) 2005-2010 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
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
16
16
 
17
 
"""Breezy plugin support.
18
 
 
19
 
Which plugins to load can be configured by setting these environment variables:
20
 
 
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.
24
 
 
25
 
The interfaces this module exports include:
26
 
 
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.
 
17
 
 
18
"""bzr python plugin support.
 
19
 
 
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.
32
24
 
33
25
See the plugin-api developer documentation for information about writing
34
26
plugins.
 
27
 
 
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
 
30
called.
35
31
"""
36
32
 
37
 
from __future__ import absolute_import
38
 
 
39
33
import os
40
 
import re
41
34
import sys
42
35
 
43
 
import breezy
44
 
from . import osutils
45
 
 
46
 
from .lazy_import import lazy_import
 
36
from bzrlib import osutils
 
37
 
 
38
from bzrlib.lazy_import import lazy_import
 
39
 
47
40
lazy_import(globals(), """
48
41
import imp
49
 
import importlib
50
 
from importlib import util as importlib_util
 
42
import re
 
43
import types
51
44
 
52
 
from breezy import (
 
45
from bzrlib import (
 
46
    _format_version_tuple,
53
47
    config,
54
48
    debug,
55
49
    errors,
56
 
    help_topics,
57
50
    trace,
58
51
    )
 
52
from bzrlib import plugins as _mod_plugins
59
53
""")
60
54
 
61
 
 
62
 
_MODULE_PREFIX = "breezy.plugins."
63
 
 
64
 
if __debug__ or sys.version_info > (3,):
65
 
    COMPILED_EXT = ".pyc"
66
 
else:
67
 
    COMPILED_EXT = ".pyo"
68
 
 
69
 
 
70
 
def disable_plugins(state=None):
 
55
from bzrlib.symbol_versioning import (
 
56
    deprecated_function,
 
57
    deprecated_in,
 
58
    )
 
59
 
 
60
 
 
61
DEFAULT_PLUGIN_PATH = None
 
62
_loaded = False
 
63
_plugins_disabled = False
 
64
 
 
65
 
 
66
def are_plugins_disabled():
 
67
    return _plugins_disabled
 
68
 
 
69
 
 
70
def disable_plugins():
71
71
    """Disable loading plugins.
72
72
 
73
73
    Future calls to load_plugins() will be ignored.
74
 
 
75
 
    :param state: The library state object that records loaded plugins.
76
74
    """
77
 
    if state is None:
78
 
        state = breezy.get_global_state()
79
 
    state.plugins = {}
80
 
 
81
 
 
82
 
def load_plugins(path=None, state=None):
83
 
    """Load breezy plugins.
84
 
 
85
 
    The environment variable BRZ_PLUGIN_PATH is considered a delimited
86
 
    set of paths to look through. Each entry is searched for `*.py`
87
 
    files (and whatever other extensions are used in the platform,
88
 
    such as `*.pyd`).
 
75
    global _plugins_disabled
 
76
    _plugins_disabled = True
 
77
    load_plugins([])
 
78
 
 
79
 
 
80
def _strip_trailing_sep(path):
 
81
    return path.rstrip("\\/")
 
82
 
 
83
 
 
84
def set_plugins_path(path=None):
 
85
    """Set the path for plugins to be loaded from.
89
86
 
90
87
    :param path: The list of paths to search for plugins.  By default,
91
 
        it is populated from the __path__ of the breezy.plugins package.
92
 
    :param state: The library state object that records loaded plugins.
 
88
        path will be determined using get_standard_plugins_path.
 
89
        if path is [], no plugins can be loaded.
93
90
    """
94
 
    if state is None:
95
 
        state = breezy.get_global_state()
96
 
    if getattr(state, 'plugins', None) is not None:
97
 
        # People can make sure plugins are loaded, they just won't be twice
98
 
        return
99
 
 
100
91
    if path is None:
101
 
        # Calls back into extend_path() here
102
 
        from breezy.plugins import __path__ as path
103
 
 
104
 
    state.plugin_warnings = {}
105
 
    _load_plugins(state, path)
106
 
    state.plugins = plugins()
107
 
 
108
 
 
109
 
def plugin_name(module_name):
110
 
    """Gives unprefixed name from module_name or None."""
111
 
    if module_name.startswith(_MODULE_PREFIX):
112
 
        parts = module_name.split(".")
113
 
        if len(parts) > 2:
114
 
            return parts[2]
115
 
    return None
116
 
 
117
 
 
118
 
def extend_path(path, name):
119
 
    """Helper so breezy.plugins can be a sort of namespace package.
120
 
 
121
 
    To be used in similar fashion to pkgutil.extend_path:
122
 
 
123
 
        from breezy.plugins import extend_path
124
 
        __path__ = extend_path(__path__, __name__)
125
 
 
126
 
    Inspects the BRZ_PLUGIN* envvars, sys.path, and the filesystem to find
127
 
    plugins. May mutate sys.modules in order to block plugin loading, and may
128
 
    append a new meta path finder to sys.meta_path for plugins@ loading.
129
 
 
130
 
    Returns a list of paths to import from, as an enhanced object that also
131
 
    contains details of the other configuration used.
132
 
    """
133
 
    blocks = _env_disable_plugins()
134
 
    _block_plugins(blocks)
135
 
 
136
 
    extra_details = _env_plugins_at()
137
 
    _install_importer_if_needed(extra_details)
138
 
 
139
 
    paths = _iter_plugin_paths(_env_plugin_path(), path)
140
 
 
141
 
    return _Path(name, blocks, extra_details, paths)
142
 
 
143
 
 
144
 
class _Path(list):
145
 
    """List type to use as __path__ but containing additional details.
146
 
 
147
 
    Python 3 allows any iterable for __path__ but Python 2 is more fussy.
148
 
    """
149
 
 
150
 
    def __init__(self, package_name, blocked, extra, paths):
151
 
        super(_Path, self).__init__(paths)
152
 
        self.package_name = package_name
153
 
        self.blocked_names = blocked
154
 
        self.extra_details = extra
155
 
 
156
 
    def __repr__(self):
157
 
        return "%s(%r, %r, %r, %s)" % (
158
 
            self.__class__.__name__, self.package_name, self.blocked_names,
159
 
            self.extra_details, list.__repr__(self))
160
 
 
161
 
 
162
 
def _expect_identifier(name, env_key, env_value):
163
 
    """Validate given name from envvar is usable as a Python identifier.
164
 
 
165
 
    Returns the name as a native str, or None if it was invalid.
166
 
 
167
 
    Per PEP 3131 this is no longer strictly correct for Python 3, but as MvL
168
 
    didn't include a neat way to check except eval, this enforces ascii.
169
 
    """
170
 
    if re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name) is None:
171
 
        trace.warning("Invalid name '%s' in %s='%s'", name, env_key, env_value)
172
 
        return None
173
 
    return str(name)
174
 
 
175
 
 
176
 
def _env_disable_plugins(key='BRZ_DISABLE_PLUGINS'):
177
 
    """Gives list of names for plugins to disable from environ key."""
178
 
    disabled_names = []
179
 
    env = osutils.path_from_environ(key)
180
 
    if env:
181
 
        for name in env.split(os.pathsep):
182
 
            name = _expect_identifier(name, key, env)
183
 
            if name is not None:
184
 
                disabled_names.append(name)
185
 
    return disabled_names
186
 
 
187
 
 
188
 
def _env_plugins_at(key='BRZ_PLUGINS_AT'):
189
 
    """Gives list of names and paths of specific plugins from environ key."""
190
 
    plugin_details = []
191
 
    env = osutils.path_from_environ(key)
192
 
    if env:
193
 
        for pair in env.split(os.pathsep):
194
 
            if '@' in pair:
195
 
                name, path = pair.split('@', 1)
196
 
            else:
197
 
                path = pair
198
 
                name = osutils.basename(path).split('.', 1)[0]
199
 
            name = _expect_identifier(name, key, env)
200
 
            if name is not None:
201
 
                plugin_details.append((name, path))
202
 
    return plugin_details
203
 
 
204
 
 
205
 
def _env_plugin_path(key='BRZ_PLUGIN_PATH'):
206
 
    """Gives list of paths and contexts for plugins from environ key.
207
 
 
208
 
    Each entry is either a specific path to load plugins from and the value
209
 
    'path', or None and one of the three values 'user', 'core', 'site'.
210
 
    """
211
 
    path_details = []
212
 
    env = osutils.path_from_environ(key)
213
 
    defaults = {"user": not env, "core": True, "site": True}
214
 
    if env:
215
 
        # Add paths specified by user in order
216
 
        for p in env.split(os.pathsep):
217
 
            flag, name = p[:1], p[1:]
218
 
            if flag in ("+", "-") and name in defaults:
219
 
                if flag == "+" and defaults[name] is not None:
220
 
                    path_details.append((None, name))
221
 
                defaults[name] = None
222
 
            else:
223
 
                path_details.append((p, 'path'))
224
 
 
225
 
    # Add any remaining default paths
226
 
    for name in ('user', 'core', 'site'):
227
 
        if defaults[name]:
228
 
            path_details.append((None, name))
229
 
 
230
 
    return path_details
231
 
 
232
 
 
233
 
def _iter_plugin_paths(paths_from_env, core_paths):
234
 
    """Generate paths using paths_from_env and core_paths."""
235
 
    # GZ 2017-06-02: This is kinda horrid, should make better.
236
 
    for path, context in paths_from_env:
237
 
        if context == 'path':
238
 
            yield path
239
 
        elif context == 'user':
240
 
            path = get_user_plugin_path()
241
 
            if os.path.isdir(path):
242
 
                yield path
243
 
        elif context == 'core':
244
 
            for path in _get_core_plugin_paths(core_paths):
245
 
                yield path
246
 
        elif context == 'site':
247
 
            for path in _get_site_plugin_paths(sys.path):
248
 
                if os.path.isdir(path):
249
 
                    yield path
250
 
 
251
 
 
252
 
def _install_importer_if_needed(plugin_details):
253
 
    """Install a meta path finder to handle plugin_details if any."""
254
 
    if plugin_details:
255
 
        finder = _PluginsAtFinder(_MODULE_PREFIX, plugin_details)
256
 
        # For Python 3, must insert before default PathFinder to override.
257
 
        sys.meta_path.insert(2, finder)
258
 
 
259
 
 
260
 
def _load_plugins(state, paths):
261
 
    """Do the importing all plugins from paths."""
262
 
    imported_names = set()
263
 
    for name, path in _iter_possible_plugins(paths):
264
 
        if name not in imported_names:
265
 
            msg = _load_plugin_module(name, path)
266
 
            if msg is not None:
267
 
                state.plugin_warnings.setdefault(name, []).append(msg)
268
 
            imported_names.add(name)
269
 
 
270
 
 
271
 
def _block_plugins(names):
272
 
    """Add names to sys.modules to block future imports."""
273
 
    for name in names:
274
 
        package_name = _MODULE_PREFIX + name
275
 
        if sys.modules.get(package_name) is not None:
276
 
            trace.mutter("Blocked plugin %s already loaded.", name)
277
 
        sys.modules[package_name] = None
278
 
 
279
 
 
280
 
def _get_package_init(package_path):
281
 
    """Get path of __init__ file from package_path or None if not a package."""
282
 
    init_path = osutils.pathjoin(package_path, "__init__.py")
283
 
    if os.path.exists(init_path):
284
 
        return init_path
285
 
    init_path = init_path[:-3] + COMPILED_EXT
286
 
    if os.path.exists(init_path):
287
 
        return init_path
288
 
    return None
289
 
 
290
 
 
291
 
def _iter_possible_plugins(plugin_paths):
292
 
    """Generate names and paths of possible plugins from plugin_paths."""
293
 
    # Inspect any from BRZ_PLUGINS_AT first.
294
 
    for name, path in getattr(plugin_paths, "extra_details", ()):
295
 
        yield name, path
296
 
    # Then walk over files and directories in the paths from the package.
297
 
    for path in plugin_paths:
298
 
        if os.path.isfile(path):
299
 
            if path.endswith(".zip"):
300
 
                trace.mutter("Don't yet support loading plugins from zip.")
301
 
        else:
302
 
            for name, path in _walk_modules(path):
303
 
                yield name, path
304
 
 
305
 
 
306
 
def _walk_modules(path):
307
 
    """Generate name and path of modules and packages on path."""
308
 
    for root, dirs, files in os.walk(path):
309
 
        files.sort()
310
 
        for f in files:
311
 
            if f[:2] != "__":
312
 
                if f.endswith((".py", COMPILED_EXT)):
313
 
                    yield f.rsplit(".", 1)[0], root
314
 
        dirs.sort()
315
 
        for d in dirs:
316
 
            if d[:2] != "__":
317
 
                package_dir = osutils.pathjoin(root, d)
318
 
                fullpath = _get_package_init(package_dir)
319
 
                if fullpath is not None:
320
 
                    yield d, package_dir
321
 
        # Don't descend into subdirectories
322
 
        del dirs[:]
323
 
 
324
 
 
325
 
def describe_plugins(show_paths=False, state=None):
326
 
    """Generate text description of plugins.
327
 
 
328
 
    Includes both those that have loaded, and those that failed to load.
329
 
 
330
 
    :param show_paths: If true, include the plugin path.
331
 
    :param state: The library state object to inspect.
332
 
    :returns: Iterator of text lines (including newlines.)
333
 
    """
334
 
    if state is None:
335
 
        state = breezy.get_global_state()
336
 
    loaded_plugins = getattr(state, 'plugins', {})
337
 
    plugin_warnings = set(getattr(state, 'plugin_warnings', []))
338
 
    all_names = sorted(set(loaded_plugins.keys()).union(plugin_warnings))
339
 
    for name in all_names:
340
 
        if name in loaded_plugins:
341
 
            plugin = loaded_plugins[name]
342
 
            version = plugin.__version__
343
 
            if version == 'unknown':
344
 
                version = ''
345
 
            yield '%s %s\n' % (name, version)
346
 
            d = plugin.module.__doc__
347
 
            if d:
348
 
                doc = d.split('\n')[0]
349
 
            else:
350
 
                doc = '(no description)'
351
 
            yield ("  %s\n" % doc)
352
 
            if show_paths:
353
 
                yield ("   %s\n" % plugin.path())
354
 
        else:
355
 
            yield "%s (failed to load)\n" % name
356
 
        if name in state.plugin_warnings:
357
 
            for line in state.plugin_warnings[name]:
358
 
                yield "  ** " + line + '\n'
359
 
        yield '\n'
360
 
 
361
 
 
362
 
def _get_core_plugin_paths(existing_paths):
363
 
    """Generate possible locations for plugins based on existing_paths."""
364
 
    if getattr(sys, 'frozen', False):
 
92
        path = get_standard_plugins_path()
 
93
    _mod_plugins.__path__ = path
 
94
    PluginImporter.reset()
 
95
    # Set up a blacklist for disabled plugins
 
96
    disabled_plugins = os.environ.get('BZR_DISABLE_PLUGINS', None)
 
97
    if disabled_plugins is not None:
 
98
        for name in disabled_plugins.split(os.pathsep):
 
99
            PluginImporter.blacklist.add('bzrlib.plugins.' + name)
 
100
    # 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('@')
 
105
            PluginImporter.specific_paths[
 
106
                'bzrlib.plugins.%s' % plugin_name] = plugin_path
 
107
    return path
 
108
 
 
109
 
 
110
def _append_new_path(paths, new_path):
 
111
    """Append a new path if it set and not already known."""
 
112
    if new_path is not None and new_path not in paths:
 
113
        paths.append(new_path)
 
114
    return paths
 
115
 
 
116
 
 
117
def get_core_plugin_path():
 
118
    core_path = None
 
119
    bzr_exe = bool(getattr(sys, 'frozen', None))
 
120
    if bzr_exe:    # expand path for bzr.exe
365
121
        # We need to use relative path to system-wide plugin
366
 
        # directory because breezy from standalone brz.exe
 
122
        # directory because bzrlib from standalone bzr.exe
367
123
        # could be imported by another standalone program
368
 
        # (e.g. brz-config; or TortoiseBzr/Olive if/when they
 
124
        # (e.g. bzr-config; or TortoiseBzr/Olive if/when they
369
125
        # will become standalone exe). [bialix 20071123]
370
126
        # __file__ typically is
371
 
        # C:\Program Files\Bazaar\lib\library.zip\breezy\plugin.pyc
 
127
        # C:\Program Files\Bazaar\lib\library.zip\bzrlib\plugin.pyc
372
128
        # then plugins directory is
373
129
        # C:\Program Files\Bazaar\plugins
374
130
        # so relative path is ../../../plugins
375
 
        yield osutils.abspath(osutils.pathjoin(
376
 
            osutils.dirname(__file__), '../../../plugins'))
 
131
        core_path = osutils.abspath(osutils.pathjoin(
 
132
                osutils.dirname(__file__), '../../../plugins'))
377
133
    else:     # don't look inside library.zip
378
 
        for path in existing_paths:
379
 
            yield path
380
 
 
381
 
 
382
 
def _get_site_plugin_paths(sys_paths):
383
 
    """Generate possible locations for plugins from given sys_paths."""
384
 
    for path in sys_paths:
385
 
        if os.path.basename(path) in ('dist-packages', 'site-packages'):
386
 
            yield osutils.pathjoin(path, 'breezy', 'plugins')
 
134
        # search the plugin path before the bzrlib installed dir
 
135
        core_path = os.path.dirname(_mod_plugins.__file__)
 
136
    return core_path
 
137
 
 
138
 
 
139
def get_site_plugin_path():
 
140
    """Returns the path for the site installed plugins."""
 
141
    if sys.platform == 'win32':
 
142
        # We don't have (yet) a good answer for windows since that is certainly
 
143
        # related to the way we build the installers. -- vila20090821
 
144
        return None
 
145
    site_path = None
 
146
    try:
 
147
        from distutils.sysconfig import get_python_lib
 
148
    except ImportError:
 
149
        # If distutuils is not available, we just don't know where they are
 
150
        pass
 
151
    else:
 
152
        site_path = osutils.pathjoin(get_python_lib(), 'bzrlib', 'plugins')
 
153
    return site_path
387
154
 
388
155
 
389
156
def get_user_plugin_path():
390
157
    return osutils.pathjoin(config.config_dir(), 'plugins')
391
158
 
392
159
 
393
 
def record_plugin_warning(warning_message):
394
 
    trace.mutter(warning_message)
395
 
    return warning_message
 
160
def get_standard_plugins_path():
 
161
    """Determine a plugin path suitable for general use."""
 
162
    # Ad-Hoc default: core is not overriden by site but user can overrides both
 
163
    # The rationale is that:
 
164
    # - 'site' comes last, because these plugins should always be available and
 
165
    #   are supposed to be in sync with the bzr installed on site.
 
166
    # - 'core' comes before 'site' so that running bzr from sources or a user
 
167
    #   installed version overrides the site version.
 
168
    # - 'user' comes first, because... user is always right.
 
169
    # - the above rules clearly defines which plugin version will be loaded if
 
170
    #   several exist. Yet, it is sometimes desirable to disable some directory
 
171
    #   so that a set of plugins is disabled as once. This can be done via
 
172
    #   -site, -core, -user.
 
173
 
 
174
    env_paths = os.environ.get('BZR_PLUGIN_PATH', '+user').split(os.pathsep)
 
175
    defaults = ['+core', '+site']
 
176
 
 
177
    # The predefined references
 
178
    refs = dict(core=get_core_plugin_path(),
 
179
                site=get_site_plugin_path(),
 
180
                user=get_user_plugin_path())
 
181
 
 
182
    # Unset paths that should be removed
 
183
    for k,v in refs.iteritems():
 
184
        removed = '-%s' % k
 
185
        # defaults can never mention removing paths as that will make it
 
186
        # impossible for the user to revoke these removals.
 
187
        if removed in env_paths:
 
188
            env_paths.remove(removed)
 
189
            refs[k] = None
 
190
 
 
191
    # Expand references
 
192
    paths = []
 
193
    for p in env_paths + defaults:
 
194
        if p.startswith('+'):
 
195
            # Resolve references if they are known
 
196
            try:
 
197
                p = refs[p[1:]]
 
198
            except KeyError:
 
199
                # Leave them untouched so user can still use paths starting
 
200
                # with '+'
 
201
                pass
 
202
        _append_new_path(paths, p)
 
203
 
 
204
    # Get rid of trailing slashes, since Python can't handle them when
 
205
    # it tries to import modules.
 
206
    paths = map(_strip_trailing_sep, paths)
 
207
    return paths
 
208
 
 
209
 
 
210
def load_plugins(path=None):
 
211
    """Load bzrlib plugins.
 
212
 
 
213
    The environment variable BZR_PLUGIN_PATH is considered a delimited
 
214
    set of paths to look through. Each entry is searched for *.py
 
215
    files (and whatever other extensions are used in the platform,
 
216
    such as *.pyd).
 
217
 
 
218
    load_from_path() provides the underlying mechanism and is called with
 
219
    the default directory list to provide the normal behaviour.
 
220
 
 
221
    :param path: The list of paths to search for plugins.  By default,
 
222
        path will be determined using get_standard_plugins_path.
 
223
        if path is [], no plugins can be loaded.
 
224
    """
 
225
    global _loaded
 
226
    if _loaded:
 
227
        # People can make sure plugins are loaded, they just won't be twice
 
228
        return
 
229
    _loaded = True
 
230
 
 
231
    # scan for all plugins in the path.
 
232
    load_from_path(set_plugins_path(path))
 
233
 
 
234
 
 
235
def load_from_path(dirs):
 
236
    """Load bzrlib plugins found in each dir in dirs.
 
237
 
 
238
    Loading a plugin means importing it into the python interpreter.
 
239
    The plugin is expected to make calls to register commands when
 
240
    it's loaded (or perhaps access other hooks in future.)
 
241
 
 
242
    Plugins are loaded into bzrlib.plugins.NAME, and can be found there
 
243
    for future reference.
 
244
 
 
245
    The python module path for bzrlib.plugins will be modified to be 'dirs'.
 
246
    """
 
247
    # Explicitly load the plugins with a specific path
 
248
    for fullname, path in PluginImporter.specific_paths.iteritems():
 
249
        name = fullname[len('bzrlib.plugins.'):]
 
250
        _load_plugin_module(name, path)
 
251
 
 
252
    # We need to strip the trailing separators here as well as in the
 
253
    # set_plugins_path function because calling code can pass anything in to
 
254
    # this function, and since it sets plugins.__path__, it should set it to
 
255
    # something that will be valid for Python to use (in case people try to
 
256
    # run "import bzrlib.plugins.PLUGINNAME" after calling this function).
 
257
    _mod_plugins.__path__ = map(_strip_trailing_sep, dirs)
 
258
    for d in dirs:
 
259
        if not d:
 
260
            continue
 
261
        trace.mutter('looking for plugins in %s', d)
 
262
        if os.path.isdir(d):
 
263
            load_from_dir(d)
 
264
 
 
265
 
 
266
# backwards compatability: load_from_dirs was the old name
 
267
# This was changed in 0.15
 
268
load_from_dirs = load_from_path
 
269
 
 
270
 
 
271
def _find_plugin_module(dir, name):
 
272
    """Check if there is a valid python module that can be loaded as a plugin.
 
273
 
 
274
    :param dir: The directory where the search is performed.
 
275
    :param path: An existing file path, either a python file or a package
 
276
        directory.
 
277
 
 
278
    :return: (name, path, description) name is the module name, path is the
 
279
        file to load and description is the tuple returned by
 
280
        imp.get_suffixes().
 
281
    """
 
282
    path = osutils.pathjoin(dir, name)
 
283
    if os.path.isdir(path):
 
284
        # Check for a valid __init__.py file, valid suffixes depends on -O and
 
285
        # can be .py, .pyc and .pyo
 
286
        for suffix, mode, kind in imp.get_suffixes():
 
287
            if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
 
288
                # We don't recognize compiled modules (.so, .dll, etc)
 
289
                continue
 
290
            init_path = osutils.pathjoin(path, '__init__' + suffix)
 
291
            if os.path.isfile(init_path):
 
292
                return name, init_path, (suffix, mode, kind)
 
293
    else:
 
294
        for suffix, mode, kind in imp.get_suffixes():
 
295
            if name.endswith(suffix):
 
296
                # Clean up the module name
 
297
                name = name[:-len(suffix)]
 
298
                if kind == imp.C_EXTENSION and name.endswith('module'):
 
299
                    name = name[:-len('module')]
 
300
                return name, path, (suffix, mode, kind)
 
301
    # There is no python module here
 
302
    return None, None, (None, None, None)
396
303
 
397
304
 
398
305
def _load_plugin_module(name, dir):
399
 
    """Load plugin by name.
 
306
    """Load plugin name from dir.
400
307
 
401
 
    :param name: The plugin name in the breezy.plugins namespace.
 
308
    :param name: The plugin name in the bzrlib.plugins namespace.
402
309
    :param dir: The directory the plugin is loaded from for error messages.
403
310
    """
404
 
    if _MODULE_PREFIX + name in sys.modules:
 
311
    if ('bzrlib.plugins.%s' % name) in PluginImporter.blacklist:
405
312
        return
406
313
    try:
407
 
        __import__(_MODULE_PREFIX + name)
408
 
    except errors.IncompatibleVersion as e:
409
 
        warning_message = (
410
 
            "Unable to load plugin %r. It supports %s "
411
 
            "versions %r but the current version is %s" %
412
 
            (name, e.api.__name__, e.wanted, e.current))
413
 
        return record_plugin_warning(warning_message)
414
 
    except Exception as e:
415
 
        trace.log_exception_quietly()
416
 
        if 'error' in debug.debug_flags:
417
 
            trace.print_exception(sys.exc_info(), sys.stderr)
418
 
        # GZ 2017-06-02: Move this name checking up a level, no point trying
419
 
        # to import things with bad names.
420
 
        if re.search('\\.|-| ', name):
 
314
        exec "import bzrlib.plugins.%s" % name in {}
 
315
    except KeyboardInterrupt:
 
316
        raise
 
317
    except errors.IncompatibleAPI, e:
 
318
        trace.warning("Unable to load plugin %r. It requested API version "
 
319
            "%s of module %s but the minimum exported version is %s, and "
 
320
            "the maximum is %s" %
 
321
            (name, e.wanted, e.api, e.minimum, e.current))
 
322
    except Exception, e:
 
323
        trace.warning("%s" % e)
 
324
        if re.search('\.|-| ', name):
421
325
            sanitised_name = re.sub('[-. ]', '_', name)
422
 
            if sanitised_name.startswith('brz_'):
423
 
                sanitised_name = sanitised_name[len('brz_'):]
 
326
            if sanitised_name.startswith('bzr_'):
 
327
                sanitised_name = sanitised_name[len('bzr_'):]
424
328
            trace.warning("Unable to load %r in %r as a plugin because the "
425
329
                    "file path isn't a valid module name; try renaming "
426
330
                    "it to %r." % (name, dir, sanitised_name))
427
331
        else:
428
 
            return record_plugin_warning(
429
 
                'Unable to load plugin %r from %r: %s' % (name, dir, e))
 
332
            trace.warning('Unable to load plugin %r from %r' % (name, dir))
 
333
        trace.log_exception_quietly()
 
334
        if 'error' in debug.debug_flags:
 
335
            trace.print_exception(sys.exc_info(), sys.stderr)
 
336
 
 
337
 
 
338
def load_from_dir(d):
 
339
    """Load the plugins in directory d.
 
340
 
 
341
    d must be in the plugins module path already.
 
342
    This function is called once for each directory in the module path.
 
343
    """
 
344
    plugin_names = set()
 
345
    for p in os.listdir(d):
 
346
        name, path, desc = _find_plugin_module(d, p)
 
347
        if name is not None:
 
348
            if name == '__init__':
 
349
                # We do nothing with the __init__.py file in directories from
 
350
                # the bzrlib.plugins module path, we may want to, one day
 
351
                # -- vila 20100316.
 
352
                continue # We don't load __init__.py in the plugins dirs
 
353
            elif getattr(_mod_plugins, name, None) is not None:
 
354
                # The module has already been loaded from another directory
 
355
                # during a previous call.
 
356
                # FIXME: There should be a better way to report masked plugins
 
357
                # -- vila 20100316
 
358
                trace.mutter('Plugin name %s already loaded', name)
 
359
            else:
 
360
                plugin_names.add(name)
 
361
 
 
362
    for name in plugin_names:
 
363
        _load_plugin_module(name, d)
430
364
 
431
365
 
432
366
def plugins():
435
369
    Each item in the dictionary is a PlugIn object.
436
370
    """
437
371
    result = {}
438
 
    for fullname in sys.modules:
439
 
        if fullname.startswith(_MODULE_PREFIX):
440
 
            name = fullname[len(_MODULE_PREFIX):]
441
 
            if not "." in name and sys.modules[fullname] is not None:
442
 
                result[name] = PlugIn(name, sys.modules[fullname])
 
372
    for name, plugin in _mod_plugins.__dict__.items():
 
373
        if isinstance(plugin, types.ModuleType):
 
374
            result[name] = PlugIn(name, plugin)
443
375
    return result
444
376
 
445
377
 
446
 
def get_loaded_plugin(name):
447
 
    """Retrieve an already loaded plugin.
448
 
 
449
 
    Returns None if there is no such plugin loaded
450
 
    """
451
 
    try:
452
 
        module = sys.modules[_MODULE_PREFIX + name]
453
 
    except KeyError:
454
 
        return None
455
 
    if module is None:
456
 
        return None
457
 
    return PlugIn(name, module)
458
 
 
459
 
 
460
 
def format_concise_plugin_list(state=None):
461
 
    """Return a string holding a concise list of plugins and their version.
462
 
    """
463
 
    if state is None:
464
 
        state = breezy.get_global_state()
465
 
    items = []
466
 
    for name, a_plugin in sorted(getattr(state, 'plugins', {}).items()):
467
 
        items.append("%s[%s]" %
468
 
            (name, a_plugin.__version__))
469
 
    return ', '.join(items)
470
 
 
471
 
 
472
378
class PluginsHelpIndex(object):
473
379
    """A help index that returns help topics for plugins."""
474
380
 
488
394
            return []
489
395
        if topic.startswith(self.prefix):
490
396
            topic = topic[len(self.prefix):]
491
 
        plugin_module_name = _MODULE_PREFIX + topic
 
397
        plugin_module_name = 'bzrlib.plugins.%s' % topic
492
398
        try:
493
399
            module = sys.modules[plugin_module_name]
494
400
        except KeyError:
519
425
            result = self.module.__doc__
520
426
        if result[-1] != '\n':
521
427
            result += '\n'
522
 
        result += help_topics._format_see_also(additional_see_also)
 
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))
 
433
        else:
 
434
            see_also = None
 
435
        if see_also:
 
436
            result += 'See also: '
 
437
            result += ', '.join(see_also)
 
438
            result += '\n'
523
439
        return result
524
440
 
525
441
    def get_help_topic(self):
526
 
        """Return the module help topic: its basename."""
527
 
        return self.module.__name__[len(_MODULE_PREFIX):]
 
442
        """Return the modules help topic - its __name__ after bzrlib.plugins.."""
 
443
        return self.module.__name__[len('bzrlib.plugins.'):]
528
444
 
529
445
 
530
446
class PlugIn(object):
531
 
    """The breezy representation of a plugin.
 
447
    """The bzrlib representation of a plugin.
532
448
 
533
449
    The PlugIn object provides a way to manipulate a given plugin module.
534
450
    """
544
460
            return os.path.abspath(self.module.__path__[0])
545
461
        elif getattr(self.module, '__file__', None) is not None:
546
462
            path = os.path.abspath(self.module.__file__)
547
 
            if path[-4:] == COMPILED_EXT:
 
463
            if path[-4:] in ('.pyc', '.pyo'):
548
464
                pypath = path[:-4] + '.py'
549
465
                if os.path.isfile(pypath):
550
466
                    path = pypath
552
468
        else:
553
469
            return repr(self.module)
554
470
 
555
 
    def __repr__(self):
556
 
        return "<%s.%s name=%s, module=%s>" % (
557
 
            self.__class__.__module__, self.__class__.__name__,
 
471
    def __str__(self):
 
472
        return "<%s.%s object at %s, name=%s, module=%s>" % (
 
473
            self.__class__.__module__, self.__class__.__name__, id(self),
558
474
            self.name, self.module)
559
475
 
 
476
    __repr__ = __str__
 
477
 
560
478
    def test_suite(self):
561
479
        """Return the plugin's test suite."""
562
480
        if getattr(self.module, 'test_suite', None) is not None:
569
487
 
570
488
        :param loader: The custom loader that should be used to load additional
571
489
            tests.
 
490
 
572
491
        """
573
492
        if getattr(self.module, 'load_tests', None) is not None:
574
493
            return loader.loadTestsFromModule(self.module)
580
499
        version_info = getattr(self.module, 'version_info', None)
581
500
        if version_info is not None:
582
501
            try:
583
 
                if isinstance(version_info, str):
 
502
                if isinstance(version_info, types.StringType):
584
503
                    version_info = version_info.split('.')
585
504
                elif len(version_info) == 3:
586
505
                    version_info = tuple(version_info) + ('final', 0)
587
 
            except TypeError:
 
506
            except TypeError, e:
588
507
                # The given version_info isn't even iteratible
589
508
                trace.log_exception_quietly()
590
509
                version_info = (version_info,)
591
510
        return version_info
592
511
 
593
 
    @property
594
 
    def __version__(self):
 
512
    def _get__version__(self):
595
513
        version_info = self.version_info()
596
514
        if version_info is None or len(version_info) == 0:
597
515
            return "unknown"
598
516
        try:
599
 
            version_string = breezy._format_version_tuple(version_info)
600
 
        except (ValueError, TypeError, IndexError):
 
517
            version_string = _format_version_tuple(version_info)
 
518
        except (ValueError, TypeError, IndexError), e:
601
519
            trace.log_exception_quietly()
602
 
            # Try to show something for the version anyway
 
520
            # try to return something usefull for bad plugins, in stead of
 
521
            # stack tracing.
603
522
            version_string = '.'.join(map(str, version_info))
604
523
        return version_string
605
524
 
606
 
 
607
 
class _PluginsAtFinder(object):
608
 
    """Meta path finder to support BRZ_PLUGINS_AT configuration."""
609
 
 
610
 
    def __init__(self, prefix, names_and_paths):
611
 
        self.prefix = prefix
612
 
        self.names_to_path = dict((prefix + n, p) for n, p in names_and_paths)
613
 
 
614
 
    def __repr__(self):
615
 
        return "<%s %r>" % (self.__class__.__name__, self.prefix)
616
 
 
617
 
    def find_spec(self, fullname, paths, target=None):
618
 
        """New module spec returning find method."""
619
 
        if fullname not in self.names_to_path:
620
 
            return None
621
 
        path = self.names_to_path[fullname]
622
 
        if os.path.isdir(path):
623
 
            path = _get_package_init(path)
624
 
            if path is None:
625
 
                # GZ 2017-06-02: Any reason to block loading of the name from
626
 
                # further down the path like this?
627
 
                raise ImportError("Not loading namespace package %s as %s" % (
628
 
                    path, fullname))
629
 
        return importlib_util.spec_from_file_location(fullname, path)
630
 
 
631
 
    def find_module(self, fullname, path):
632
 
        """Old PEP 302 import hook find_module method."""
633
 
        if fullname not in self.names_to_path:
634
 
            return None
635
 
        return _LegacyLoader(self.names_to_path[fullname])
636
 
 
637
 
 
638
 
class _LegacyLoader(object):
639
 
    """Source loader implementation for Python versions without importlib."""
640
 
 
641
 
    def __init__(self, filepath):
642
 
        self.filepath = filepath
643
 
 
644
 
    def __repr__(self):
645
 
        return "<%s %r>" % (self.__class__.__name__, self.filepath)
 
525
    __version__ = property(_get__version__)
 
526
 
 
527
 
 
528
class _PluginImporter(object):
 
529
    """An importer tailored to bzr specific needs.
 
530
 
 
531
    This is a singleton that takes care of:
 
532
    - disabled plugins specified in 'blacklist',
 
533
    - plugins that needs to be loaded from specific directories.
 
534
    """
 
535
 
 
536
    def __init__(self):
 
537
        self.reset()
 
538
 
 
539
    def reset(self):
 
540
        self.blacklist = set()
 
541
        self.specific_paths = {}
 
542
 
 
543
    def find_module(self, fullname, parent_path=None):
 
544
        """Search a plugin module.
 
545
 
 
546
        Disabled plugins raise an import error, plugins with specific paths
 
547
        returns a specific loader.
 
548
 
 
549
        :return: None if the plugin doesn't need special handling, self
 
550
            otherwise.
 
551
        """
 
552
        if not fullname.startswith('bzrlib.plugins.'):
 
553
            return None
 
554
        if fullname in self.blacklist:
 
555
            raise ImportError('%s is disabled' % fullname)
 
556
        if fullname in self.specific_paths:
 
557
            return self
 
558
        return None
646
559
 
647
560
    def load_module(self, fullname):
648
 
        """Load a plugin from a specific directory (or file)."""
649
 
        plugin_path = self.filepath
 
561
        """Load a plugin from a specific directory."""
 
562
        # We are called only for specific paths
 
563
        plugin_path = self.specific_paths[fullname]
650
564
        loading_path = None
 
565
        package = False
651
566
        if os.path.isdir(plugin_path):
652
 
            init_path = _get_package_init(plugin_path)
653
 
            if init_path is not None:
654
 
                loading_path = plugin_path
655
 
                suffix = ''
656
 
                mode = ''
657
 
                kind = imp.PKG_DIRECTORY
 
567
            for suffix, mode, kind in imp.get_suffixes():
 
568
                if kind not in (imp.PY_SOURCE, imp.PY_COMPILED):
 
569
                    # We don't recognize compiled modules (.so, .dll, etc)
 
570
                    continue
 
571
                init_path = osutils.pathjoin(plugin_path, '__init__' + suffix)
 
572
                if os.path.isfile(init_path):
 
573
                    loading_path = init_path
 
574
                    package = True
 
575
                    break
658
576
        else:
659
577
            for suffix, mode, kind in imp.get_suffixes():
660
578
                if plugin_path.endswith(suffix):
663
581
        if loading_path is None:
664
582
            raise ImportError('%s cannot be loaded from %s'
665
583
                              % (fullname, plugin_path))
666
 
        if kind is imp.PKG_DIRECTORY:
667
 
            f = None
668
 
        else:
669
 
            f = open(loading_path, mode)
 
584
        f = open(loading_path, mode)
670
585
        try:
671
586
            mod = imp.load_module(fullname, f, loading_path,
672
587
                                  (suffix, mode, kind))
 
588
            if package:
 
589
                # The plugin can contain modules, so be ready
 
590
                mod.__path__ = [plugin_path]
673
591
            mod.__package__ = fullname
674
592
            return mod
675
593
        finally:
676
 
            if f is not None:
677
 
                f.close()
 
594
            f.close()
 
595
 
 
596
 
 
597
# Install a dedicated importer for plugins requiring special handling
 
598
PluginImporter = _PluginImporter()
 
599
sys.meta_path.append(PluginImporter)