/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: Gustav Hartvigsson
  • Date: 2021-01-09 21:36:27 UTC
  • Revision ID: gustav.hartvigsson@gmail.com-20210109213627-h1xwcutzy9m7a99b
Added 'Case Preserving Working Tree Use Cases' from Canonical Wiki

* Addod a page from the Canonical Bazaar wiki
  with information on the scmeatics of case
  perserving filesystems an a case insensitive
  filesystem works.
  
  * Needs re-work, but this will do as it is the
    same inforamoton as what was on the linked
    page in the currint documentation.

Show diffs side-by-side

added added

removed removed

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