/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 breezy/plugin.py

  • Committer: Jelmer Vernooij
  • Date: 2017-06-05 22:01:28 UTC
  • mfrom: (6658 work)
  • mto: This revision was merged to the branch mainline in revision 6666.
  • Revision ID: jelmer@jelmer.uk-20170605220128-xurjonb8cjf5o52j
Merge trunk.

Show diffs side-by-side

added added

removed removed

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