/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/commands.py

  • Committer: Martin
  • Date: 2010-05-03 20:55:05 UTC
  • mto: This revision was merged to the branch mainline in revision 5204.
  • Revision ID: gzlist@googlemail.com-20100503205505-okdad5rbf12osway
Include OverflowError in error types bencode translates, as Python 2.4 raises that rather than IndexError in some situations

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2006 Canonical Ltd
 
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
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 
 
17
 
 
18
 
# TODO: probably should say which arguments are candidates for glob
19
 
# expansion on windows and do that at the command level.
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
 
20
17
 
21
18
# TODO: Define arguments by objects, rather than just using names.
22
19
# Those objects can specify the expected type of the argument, which
25
22
 
26
23
# TODO: Specific "examples" property on commands for consistent formatting.
27
24
 
28
 
# TODO: "--profile=cum", to change sort order.  Is there any value in leaving
29
 
# the profile output behind so it can be interactively examined?
30
 
 
31
25
import os
32
26
import sys
33
27
 
35
29
lazy_import(globals(), """
36
30
import codecs
37
31
import errno
 
32
import threading
38
33
from warnings import warn
39
34
 
40
35
import bzrlib
41
36
from bzrlib import (
 
37
    cleanup,
 
38
    cmdline,
42
39
    debug,
43
40
    errors,
44
41
    option,
45
42
    osutils,
46
43
    trace,
 
44
    ui,
47
45
    win32utils,
48
46
    )
49
47
""")
50
48
 
 
49
from bzrlib.hooks import HookPoint, Hooks
 
50
# Compatibility - Option used to be in commands.
 
51
from bzrlib.option import Option
 
52
from bzrlib.plugin import disable_plugins, load_plugins
51
53
from bzrlib import registry
52
 
# Compatibility
53
 
from bzrlib.option import Option
54
 
 
55
 
 
56
 
plugin_cmds = {}
 
54
from bzrlib.symbol_versioning import (
 
55
    deprecated_function,
 
56
    deprecated_in,
 
57
    deprecated_method,
 
58
    )
 
59
 
 
60
 
 
61
class CommandInfo(object):
 
62
    """Information about a command."""
 
63
 
 
64
    def __init__(self, aliases):
 
65
        """The list of aliases for the command."""
 
66
        self.aliases = aliases
 
67
 
 
68
    @classmethod
 
69
    def from_command(klass, command):
 
70
        """Factory to construct a CommandInfo from a command."""
 
71
        return klass(command.aliases)
 
72
 
 
73
 
 
74
class CommandRegistry(registry.Registry):
 
75
    """Special registry mapping command names to command classes.
 
76
    
 
77
    :ivar overridden_registry: Look in this registry for commands being
 
78
        overridden by this registry.  This can be used to tell plugin commands
 
79
        about the builtin they're decorating.
 
80
    """
 
81
 
 
82
    def __init__(self):
 
83
        registry.Registry.__init__(self)
 
84
        self.overridden_registry = None
 
85
        # map from aliases to the real command that implements the name
 
86
        self._alias_dict = {}
 
87
 
 
88
    def get(self, command_name):
 
89
        real_name = self._alias_dict.get(command_name, command_name)
 
90
        return registry.Registry.get(self, real_name)
 
91
 
 
92
    @staticmethod
 
93
    def _get_name(command_name):
 
94
        if command_name.startswith("cmd_"):
 
95
            return _unsquish_command_name(command_name)
 
96
        else:
 
97
            return command_name
 
98
 
 
99
    def register(self, cmd, decorate=False):
 
100
        """Utility function to help register a command
 
101
 
 
102
        :param cmd: Command subclass to register
 
103
        :param decorate: If true, allow overriding an existing command
 
104
            of the same name; the old command is returned by this function.
 
105
            Otherwise it is an error to try to override an existing command.
 
106
        """
 
107
        k = cmd.__name__
 
108
        k_unsquished = self._get_name(k)
 
109
        try:
 
110
            previous = self.get(k_unsquished)
 
111
        except KeyError:
 
112
            previous = None
 
113
            if self.overridden_registry:
 
114
                try:
 
115
                    previous = self.overridden_registry.get(k_unsquished)
 
116
                except KeyError:
 
117
                    pass
 
118
        info = CommandInfo.from_command(cmd)
 
119
        try:
 
120
            registry.Registry.register(self, k_unsquished, cmd,
 
121
                                       override_existing=decorate, info=info)
 
122
        except KeyError:
 
123
            trace.warning('Two plugins defined the same command: %r' % k)
 
124
            trace.warning('Not loading the one in %r' %
 
125
                sys.modules[cmd.__module__])
 
126
            trace.warning('Previously this command was registered from %r' %
 
127
                sys.modules[previous.__module__])
 
128
        for a in cmd.aliases:
 
129
            self._alias_dict[a] = k_unsquished
 
130
        return previous
 
131
 
 
132
    def register_lazy(self, command_name, aliases, module_name):
 
133
        """Register a command without loading its module.
 
134
 
 
135
        :param command_name: The primary name of the command.
 
136
        :param aliases: A list of aliases for the command.
 
137
        :module_name: The module that the command lives in.
 
138
        """
 
139
        key = self._get_name(command_name)
 
140
        registry.Registry.register_lazy(self, key, module_name, command_name,
 
141
                                        info=CommandInfo(aliases))
 
142
        for a in aliases:
 
143
            self._alias_dict[a] = key
 
144
 
 
145
 
 
146
plugin_cmds = CommandRegistry()
 
147
builtin_command_registry = CommandRegistry()
 
148
plugin_cmds.overridden_registry = builtin_command_registry
57
149
 
58
150
 
59
151
def register_command(cmd, decorate=False):
60
 
    """Utility function to help register a command
 
152
    """Register a plugin command.
61
153
 
62
 
    :param cmd: Command subclass to register
63
 
    :param decorate: If true, allow overriding an existing command
64
 
        of the same name; the old command is returned by this function.
65
 
        Otherwise it is an error to try to override an existing command.
 
154
    Should generally be avoided in favor of lazy registration. 
66
155
    """
67
156
    global plugin_cmds
68
 
    k = cmd.__name__
69
 
    if k.startswith("cmd_"):
70
 
        k_unsquished = _unsquish_command_name(k)
71
 
    else:
72
 
        k_unsquished = k
73
 
    if k_unsquished not in plugin_cmds:
74
 
        plugin_cmds[k_unsquished] = cmd
75
 
        ## trace.mutter('registered plugin command %s', k_unsquished)
76
 
        if decorate and k_unsquished in builtin_command_names():
77
 
            return _builtin_commands()[k_unsquished]
78
 
    elif decorate:
79
 
        result = plugin_cmds[k_unsquished]
80
 
        plugin_cmds[k_unsquished] = cmd
81
 
        return result
82
 
    else:
83
 
        trace.log_error('Two plugins defined the same command: %r' % k)
84
 
        trace.log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
85
 
        trace.log_error('Previously this command was registered from %r' %
86
 
                        sys.modules[plugin_cmds[k_unsquished].__module__])
 
157
    return plugin_cmds.register(cmd, decorate)
87
158
 
88
159
 
89
160
def _squish_command_name(cmd):
94
165
    return cmd[4:].replace('_','-')
95
166
 
96
167
 
 
168
@deprecated_function(deprecated_in((2, 2, 0)))
97
169
def _builtin_commands():
 
170
    """Return a dict of {name: cmd_class} for builtin commands.
 
171
 
 
172
    :deprecated: Use the builtin_command_registry registry instead
 
173
    """
 
174
    # return dict(name: cmd_class)
 
175
    return dict(builtin_command_registry.items())
 
176
 
 
177
 
 
178
def _register_builtin_commands():
 
179
    if builtin_command_registry.keys():
 
180
        # only load once
 
181
        return
98
182
    import bzrlib.builtins
 
183
    for cmd_class in _scan_module_for_commands(bzrlib.builtins).values():
 
184
        builtin_command_registry.register(cmd_class)
 
185
    bzrlib.builtins._register_lazy_builtins()
 
186
 
 
187
 
 
188
def _scan_module_for_commands(module):
99
189
    r = {}
100
 
    builtins = bzrlib.builtins.__dict__
101
 
    for name in builtins:
 
190
    for name, obj in module.__dict__.iteritems():
102
191
        if name.startswith("cmd_"):
103
192
            real_name = _unsquish_command_name(name)
104
 
            r[real_name] = builtins[name]
 
193
            r[real_name] = obj
105
194
    return r
106
 
            
 
195
 
 
196
 
 
197
def _list_bzr_commands(names):
 
198
    """Find commands from bzr's core and plugins.
 
199
    
 
200
    This is not the public interface, just the default hook called by all_command_names.
 
201
    """
 
202
    # to eliminate duplicates
 
203
    names.update(builtin_command_names())
 
204
    names.update(plugin_command_names())
 
205
    return names
 
206
 
 
207
 
 
208
def all_command_names():
 
209
    """Return a set of all command names."""
 
210
    names = set()
 
211
    for hook in Command.hooks['list_commands']:
 
212
        names = hook(names)
 
213
        if names is None:
 
214
            raise AssertionError(
 
215
                'hook %s returned None' % Command.hooks.get_hook_name(hook))
 
216
    return names
 
217
 
107
218
 
108
219
def builtin_command_names():
109
 
    """Return list of builtin command names."""
110
 
    return _builtin_commands().keys()
 
220
    """Return list of builtin command names.
111
221
    
 
222
    Use of all_command_names() is encouraged rather than builtin_command_names
 
223
    and/or plugin_command_names.
 
224
    """
 
225
    return builtin_command_registry.keys()
 
226
 
112
227
 
113
228
def plugin_command_names():
 
229
    """Returns command names from commands registered by plugins."""
114
230
    return plugin_cmds.keys()
115
231
 
116
232
 
117
 
def _get_cmd_dict(plugins_override=True):
118
 
    """Return name->class mapping for all commands."""
119
 
    d = _builtin_commands()
120
 
    if plugins_override:
121
 
        d.update(plugin_cmds)
122
 
    return d
123
 
 
124
 
    
125
 
def get_all_cmds(plugins_override=True):
126
 
    """Return canonical name and class for all registered commands."""
127
 
    for k, v in _get_cmd_dict(plugins_override=plugins_override).iteritems():
128
 
        yield k,v
129
 
 
130
 
 
131
233
def get_cmd_object(cmd_name, plugins_override=True):
132
 
    """Return the canonical name and command class for a command.
 
234
    """Return the command object for a command.
133
235
 
134
236
    plugins_override
135
237
        If true, plugin commands can override builtins.
140
242
        raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
141
243
 
142
244
 
143
 
def _get_cmd_object(cmd_name, plugins_override=True):
144
 
    """Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""
 
245
def _get_cmd_object(cmd_name, plugins_override=True, check_missing=True):
 
246
    """Get a command object.
 
247
 
 
248
    :param cmd_name: The name of the command.
 
249
    :param plugins_override: Allow plugins to override builtins.
 
250
    :param check_missing: Look up commands not found in the regular index via
 
251
        the get_missing_command hook.
 
252
    :return: A Command object instance
 
253
    :raises KeyError: If no command is found.
 
254
    """
 
255
    # We want only 'ascii' command names, but the user may have typed
 
256
    # in a Unicode name. In that case, they should just get a
 
257
    # 'command not found' error later.
 
258
    # In the future, we may actually support Unicode command names.
 
259
    cmd = None
 
260
    # Get a command
 
261
    for hook in Command.hooks['get_command']:
 
262
        cmd = hook(cmd, cmd_name)
 
263
        if cmd is not None and not plugins_override and not cmd.plugin_name():
 
264
            # We've found a non-plugin command, don't permit it to be
 
265
            # overridden.
 
266
            break
 
267
    if cmd is None and check_missing:
 
268
        for hook in Command.hooks['get_missing_command']:
 
269
            cmd = hook(cmd_name)
 
270
            if cmd is not None:
 
271
                break
 
272
    if cmd is None:
 
273
        # No command found.
 
274
        raise KeyError
 
275
    # Allow plugins to extend commands
 
276
    for hook in Command.hooks['extend_command']:
 
277
        hook(cmd)
 
278
    return cmd
 
279
 
 
280
 
 
281
def _try_plugin_provider(cmd_name):
 
282
    """Probe for a plugin provider having cmd_name."""
 
283
    try:
 
284
        plugin_metadata, provider = probe_for_provider(cmd_name)
 
285
        raise errors.CommandAvailableInPlugin(cmd_name,
 
286
            plugin_metadata, provider)
 
287
    except errors.NoPluginAvailable:
 
288
        pass
 
289
 
 
290
 
 
291
def probe_for_provider(cmd_name):
 
292
    """Look for a provider for cmd_name.
 
293
 
 
294
    :param cmd_name: The command name.
 
295
    :return: plugin_metadata, provider for getting cmd_name.
 
296
    :raises NoPluginAvailable: When no provider can supply the plugin.
 
297
    """
 
298
    # look for providers that provide this command but aren't installed
 
299
    for provider in command_providers_registry:
 
300
        try:
 
301
            return provider.plugin_for_command(cmd_name), provider
 
302
        except errors.NoPluginAvailable:
 
303
            pass
 
304
    raise errors.NoPluginAvailable(cmd_name)
 
305
 
 
306
 
 
307
def _get_bzr_command(cmd_or_None, cmd_name):
 
308
    """Get a command from bzr's core."""
 
309
    try:
 
310
        cmd_class = builtin_command_registry.get(cmd_name)
 
311
    except KeyError:
 
312
        pass
 
313
    else:
 
314
        return cmd_class()
 
315
    return cmd_or_None
 
316
 
 
317
 
 
318
def _get_external_command(cmd_or_None, cmd_name):
 
319
    """Lookup a command that is a shell script."""
 
320
    # Only do external command lookups when no command is found so far.
 
321
    if cmd_or_None is not None:
 
322
        return cmd_or_None
145
323
    from bzrlib.externalcommand import ExternalCommand
146
 
 
147
 
    # We want only 'ascii' command names, but the user may have typed
148
 
    # in a Unicode name. In that case, they should just get a
149
 
    # 'command not found' error later.
150
 
    # In the future, we may actually support Unicode command names.
151
 
 
152
 
    # first look up this command under the specified name
153
 
    cmds = _get_cmd_dict(plugins_override=plugins_override)
154
 
    try:
155
 
        return cmds[cmd_name]()
156
 
    except KeyError:
157
 
        pass
158
 
 
159
 
    # look for any command which claims this as an alias
160
 
    for real_cmd_name, cmd_class in cmds.iteritems():
161
 
        if cmd_name in cmd_class.aliases:
162
 
            return cmd_class()
163
 
 
164
324
    cmd_obj = ExternalCommand.find_command(cmd_name)
165
325
    if cmd_obj:
166
326
        return cmd_obj
167
327
 
168
 
    # look for plugins that provide this command but aren't installed
169
 
    for provider in command_providers_registry:
170
 
        try:
171
 
            plugin_metadata = provider.plugin_for_command(cmd_name)
172
 
        except errors.NoPluginAvailable:
173
 
            pass
174
 
        else:
175
 
            raise errors.CommandAvailableInPlugin(cmd_name, 
176
 
                                                  plugin_metadata, provider)
177
328
 
178
 
    raise KeyError
 
329
def _get_plugin_command(cmd_or_None, cmd_name):
 
330
    """Get a command from bzr's plugins."""
 
331
    try:
 
332
        return plugin_cmds.get(cmd_name)()
 
333
    except KeyError:
 
334
        pass
 
335
    for key in plugin_cmds.keys():
 
336
        info = plugin_cmds.get_info(key)
 
337
        if cmd_name in info.aliases:
 
338
            return plugin_cmds.get(key)()
 
339
    return cmd_or_None
179
340
 
180
341
 
181
342
class Command(object):
235
396
            sys.stdout is forced to be a binary stream, and line-endings
236
397
            will not mangled.
237
398
 
 
399
    :cvar hooks: An instance of CommandHooks.
238
400
    """
239
401
    aliases = []
240
402
    takes_args = []
242
404
    encoding_type = 'strict'
243
405
 
244
406
    hidden = False
245
 
    
 
407
 
246
408
    def __init__(self):
247
409
        """Construct an instance of this command."""
248
410
        if self.__doc__ == Command.__doc__:
249
411
            warn("No help message set for %r" % self)
250
412
        # List of standard options directly supported
251
413
        self.supported_std_options = []
252
 
 
 
414
        self._setup_run()
 
415
 
 
416
    def add_cleanup(self, cleanup_func, *args, **kwargs):
 
417
        """Register a function to call after self.run returns or raises.
 
418
 
 
419
        Functions will be called in LIFO order.
 
420
        """
 
421
        self._operation.add_cleanup(cleanup_func, *args, **kwargs)
 
422
 
 
423
    def cleanup_now(self):
 
424
        """Execute and empty pending cleanup functions immediately.
 
425
 
 
426
        After cleanup_now all registered cleanups are forgotten.  add_cleanup
 
427
        may be called again after cleanup_now; these cleanups will be called
 
428
        after self.run returns or raises (or when cleanup_now is next called).
 
429
 
 
430
        This is useful for releasing expensive or contentious resources (such
 
431
        as write locks) before doing further work that does not require those
 
432
        resources (such as writing results to self.outf). Note though, that
 
433
        as it releases all resources, this may release locks that the command
 
434
        wants to hold, so use should be done with care.
 
435
        """
 
436
        self._operation.cleanup_now()
 
437
 
 
438
    @deprecated_method(deprecated_in((2, 1, 0)))
253
439
    def _maybe_expand_globs(self, file_list):
254
440
        """Glob expand file_list if the platform does not do that itself.
255
 
        
 
441
 
 
442
        Not used anymore, now that the bzr command-line parser globs on
 
443
        Windows.
 
444
 
256
445
        :return: A possibly empty list of unicode paths.
257
446
 
258
447
        Introduced in bzrlib 0.18.
259
448
        """
260
 
        if not file_list:
261
 
            file_list = []
262
 
        if sys.platform == 'win32':
263
 
            file_list = win32utils.glob_expand(file_list)
264
 
        return list(file_list)
 
449
        return file_list
265
450
 
266
451
    def _usage(self):
267
452
        """Return single-line grammar for this command.
282
467
        return s
283
468
 
284
469
    def get_help_text(self, additional_see_also=None, plain=True,
285
 
                      see_also_as_links=False):
 
470
                      see_also_as_links=False, verbose=True):
286
471
        """Return a text string with help for this command.
287
 
        
 
472
 
288
473
        :param additional_see_also: Additional help topics to be
289
474
            cross-referenced.
290
475
        :param plain: if False, raw help (reStructuredText) is
291
476
            returned instead of plain text.
292
477
        :param see_also_as_links: if True, convert items in 'See also'
293
478
            list to internal links (used by bzr_man rstx generator)
 
479
        :param verbose: if True, display the full help, otherwise
 
480
            leave out the descriptive sections and just display
 
481
            usage help (e.g. Purpose, Usage, Options) with a
 
482
            message explaining how to obtain full help.
294
483
        """
295
484
        doc = self.help()
296
485
        if doc is None:
297
486
            raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
298
487
 
299
488
        # Extract the summary (purpose) and sections out from the text
300
 
        purpose,sections = self._get_help_parts(doc)
 
489
        purpose,sections,order = self._get_help_parts(doc)
301
490
 
302
491
        # If a custom usage section was provided, use it
303
492
        if sections.has_key('Usage'):
315
504
        result += '\n'
316
505
 
317
506
        # Add the options
 
507
        #
 
508
        # XXX: optparse implicitly rewraps the help, and not always perfectly,
 
509
        # so we get <https://bugs.launchpad.net/bzr/+bug/249908>.  -- mbp
 
510
        # 20090319
318
511
        options = option.get_optparser(self.options()).format_option_help()
 
512
        # XXX: According to the spec, ReST option lists actually don't support 
 
513
        # options like --1.9 so that causes syntax errors (in Sphinx at least).
 
514
        # As that pattern always appears in the commands that break, we trap
 
515
        # on that and then format that block of 'format' options as a literal
 
516
        # block.
 
517
        if not plain and options.find('  --1.9  ') != -1:
 
518
            options = options.replace(' format:\n', ' format::\n\n', 1)
319
519
        if options.startswith('Options:'):
320
520
            result += ':' + options
321
521
        elif options.startswith('options:'):
325
525
            result += options
326
526
        result += '\n'
327
527
 
328
 
        # Add the description, indenting it 2 spaces
329
 
        # to match the indentation of the options
330
 
        if sections.has_key(None):
331
 
            text = sections.pop(None)
332
 
            text = '\n  '.join(text.splitlines())
333
 
            result += ':%s:\n  %s\n\n' % ('Description',text)
 
528
        if verbose:
 
529
            # Add the description, indenting it 2 spaces
 
530
            # to match the indentation of the options
 
531
            if sections.has_key(None):
 
532
                text = sections.pop(None)
 
533
                text = '\n  '.join(text.splitlines())
 
534
                result += ':%s:\n  %s\n\n' % ('Description',text)
334
535
 
335
 
        # Add the custom sections (e.g. Examples). Note that there's no need
336
 
        # to indent these as they must be indented already in the source.
337
 
        if sections:
338
 
            labels = sorted(sections.keys())
339
 
            for label in labels:
340
 
                result += ':%s:\n%s\n\n' % (label,sections[label])
 
536
            # Add the custom sections (e.g. Examples). Note that there's no need
 
537
            # to indent these as they must be indented already in the source.
 
538
            if sections:
 
539
                for label in order:
 
540
                    if sections.has_key(label):
 
541
                        result += ':%s:\n%s\n' % (label,sections[label])
 
542
                result += '\n'
 
543
        else:
 
544
            result += ("See bzr help %s for more details and examples.\n\n"
 
545
                % self.name())
341
546
 
342
547
        # Add the aliases, source (plug-in) and see also links, if any
343
548
        if self.aliases:
356
561
                        # so don't create a real link
357
562
                        see_also_links.append(item)
358
563
                    else:
359
 
                        # Use a reST link for this entry
360
 
                        see_also_links.append("`%s`_" % (item,))
 
564
                        # Use a Sphinx link for this entry
 
565
                        link_text = ":doc:`%s <%s-help>`" % (item, item)
 
566
                        see_also_links.append(link_text)
361
567
                see_also = see_also_links
362
568
            result += ':See also: '
363
569
            result += ', '.join(see_also) + '\n'
372
578
    def _get_help_parts(text):
373
579
        """Split help text into a summary and named sections.
374
580
 
375
 
        :return: (summary,sections) where summary is the top line and
 
581
        :return: (summary,sections,order) where summary is the top line and
376
582
            sections is a dictionary of the rest indexed by section name.
 
583
            order is the order the section appear in the text.
377
584
            A section starts with a heading line of the form ":xxx:".
378
585
            Indented text on following lines is the section value.
379
586
            All text found outside a named section is assigned to the
380
587
            default section which is given the key of None.
381
588
        """
382
 
        def save_section(sections, label, section):
 
589
        def save_section(sections, order, label, section):
383
590
            if len(section) > 0:
384
591
                if sections.has_key(label):
385
592
                    sections[label] += '\n' + section
386
593
                else:
 
594
                    order.append(label)
387
595
                    sections[label] = section
388
596
 
389
597
        lines = text.rstrip().splitlines()
390
598
        summary = lines.pop(0)
391
599
        sections = {}
 
600
        order = []
392
601
        label,section = None,''
393
602
        for line in lines:
394
603
            if line.startswith(':') and line.endswith(':') and len(line) > 2:
395
 
                save_section(sections, label, section)
 
604
                save_section(sections, order, label, section)
396
605
                label,section = line[1:-1],''
397
606
            elif (label is not None) and len(line) > 1 and not line[0].isspace():
398
 
                save_section(sections, label, section)
 
607
                save_section(sections, order, label, section)
399
608
                label,section = None,line
400
609
            else:
401
610
                if len(section) > 0:
402
611
                    section += '\n' + line
403
612
                else:
404
613
                    section = line
405
 
        save_section(sections, label, section)
406
 
        return summary, sections
 
614
        save_section(sections, order, label, section)
 
615
        return summary, sections, order
407
616
 
408
617
    def get_help_topic(self):
409
618
        """Return the commands help topic - its name."""
411
620
 
412
621
    def get_see_also(self, additional_terms=None):
413
622
        """Return a list of help topics that are related to this command.
414
 
        
 
623
 
415
624
        The list is derived from the content of the _see_also attribute. Any
416
625
        duplicates are removed and the result is in lexical order.
417
626
        :param additional_terms: Additional help topics to cross-reference.
438
647
 
439
648
    def _setup_outf(self):
440
649
        """Return a file linked to stdout, which has proper encoding."""
441
 
        # Originally I was using self.stdout, but that looks
442
 
        # *way* too much like sys.stdout
443
 
        if self.encoding_type == 'exact':
444
 
            # force sys.stdout to be binary stream on win32
445
 
            if sys.platform == 'win32':
446
 
                fileno = getattr(sys.stdout, 'fileno', None)
447
 
                if fileno:
448
 
                    import msvcrt
449
 
                    msvcrt.setmode(fileno(), os.O_BINARY)
450
 
            self.outf = sys.stdout
451
 
            return
452
 
 
453
 
        output_encoding = osutils.get_terminal_encoding()
454
 
 
455
 
        self.outf = codecs.getwriter(output_encoding)(sys.stdout,
456
 
                        errors=self.encoding_type)
457
 
        # For whatever reason codecs.getwriter() does not advertise its encoding
458
 
        # it just returns the encoding of the wrapped file, which is completely
459
 
        # bogus. So set the attribute, so we can find the correct encoding later.
460
 
        self.outf.encoding = output_encoding
 
650
        self.outf = ui.ui_factory.make_output_stream(
 
651
            encoding_type=self.encoding_type)
461
652
 
462
653
    def run_argv_aliases(self, argv, alias_argv=None):
463
654
        """Parse the command line and run with extra aliases in alias_argv."""
464
 
        if argv is None:
465
 
            warn("Passing None for [] is deprecated from bzrlib 0.10",
466
 
                 DeprecationWarning, stacklevel=2)
467
 
            argv = []
468
655
        args, opts = parse_args(self, argv, alias_argv)
469
656
 
470
657
        # Process the standard options
471
658
        if 'help' in opts:  # e.g. bzr add --help
472
659
            sys.stdout.write(self.get_help_text())
473
660
            return 0
 
661
        if 'usage' in opts:  # e.g. bzr add --usage
 
662
            sys.stdout.write(self.get_help_text(verbose=False))
 
663
            return 0
474
664
        trace.set_verbosity_level(option._verbosity_level)
475
665
        if 'verbose' in self.supported_std_options:
476
666
            opts['verbose'] = trace.is_verbose()
494
684
 
495
685
        return self.run(**all_cmd_args)
496
686
 
 
687
    def _setup_run(self):
 
688
        """Wrap the defined run method on self with a cleanup.
 
689
 
 
690
        This is called by __init__ to make the Command be able to be run
 
691
        by just calling run(), as it could be before cleanups were added.
 
692
 
 
693
        If a different form of cleanups are in use by your Command subclass,
 
694
        you can override this method.
 
695
        """
 
696
        class_run = self.run
 
697
        def run(*args, **kwargs):
 
698
            self._operation = cleanup.OperationWithCleanups(class_run)
 
699
            try:
 
700
                return self._operation.run_simple(*args, **kwargs)
 
701
            finally:
 
702
                del self._operation
 
703
        self.run = run
 
704
 
 
705
    @deprecated_method(deprecated_in((2, 2, 0)))
 
706
    def run_direct(self, *args, **kwargs):
 
707
        """Deprecated thunk from bzrlib 2.1."""
 
708
        return self.run(*args, **kwargs)
 
709
 
497
710
    def run(self):
498
711
        """Actually run the command.
499
712
 
503
716
        Return 0 or None if the command was successful, or a non-zero
504
717
        shell error code if not.  It's OK for this method to allow
505
718
        an exception to raise up.
 
719
 
 
720
        This method is automatically wrapped by Command.__init__ with a 
 
721
        cleanup operation, stored as self._operation. This can be used
 
722
        via self.add_cleanup to perform automatic cleanups at the end of
 
723
        run().
 
724
 
 
725
        The argument for run are assembled by introspection. So for instance,
 
726
        if your command takes an argument files, you would declare::
 
727
 
 
728
            def run(self, files=None):
 
729
                pass
506
730
        """
507
731
        raise NotImplementedError('no implementation of command %r'
508
732
                                  % self.name())
529
753
            return None
530
754
 
531
755
 
 
756
class CommandHooks(Hooks):
 
757
    """Hooks related to Command object creation/enumeration."""
 
758
 
 
759
    def __init__(self):
 
760
        """Create the default hooks.
 
761
 
 
762
        These are all empty initially, because by default nothing should get
 
763
        notified.
 
764
        """
 
765
        Hooks.__init__(self)
 
766
        self.create_hook(HookPoint('extend_command',
 
767
            "Called after creating a command object to allow modifications "
 
768
            "such as adding or removing options, docs etc. Called with the "
 
769
            "new bzrlib.commands.Command object.", (1, 13), None))
 
770
        self.create_hook(HookPoint('get_command',
 
771
            "Called when creating a single command. Called with "
 
772
            "(cmd_or_None, command_name). get_command should either return "
 
773
            "the cmd_or_None parameter, or a replacement Command object that "
 
774
            "should be used for the command. Note that the Command.hooks "
 
775
            "hooks are core infrastructure. Many users will prefer to use "
 
776
            "bzrlib.commands.register_command or plugin_cmds.register_lazy.",
 
777
            (1, 17), None))
 
778
        self.create_hook(HookPoint('get_missing_command',
 
779
            "Called when creating a single command if no command could be "
 
780
            "found. Called with (command_name). get_missing_command should "
 
781
            "either return None, or a Command object to be used for the "
 
782
            "command.", (1, 17), None))
 
783
        self.create_hook(HookPoint('list_commands',
 
784
            "Called when enumerating commands. Called with a set of "
 
785
            "cmd_name strings for all the commands found so far. This set "
 
786
            " is safe to mutate - e.g. to remove a command. "
 
787
            "list_commands should return the updated set of command names.",
 
788
            (1, 17), None))
 
789
 
 
790
Command.hooks = CommandHooks()
 
791
 
 
792
 
532
793
def parse_args(command, argv, alias_argv=None):
533
794
    """Parse command line.
534
 
    
 
795
 
535
796
    Arguments and options are parsed at this level before being passed
536
797
    down to specific command handlers.  This routine knows, from a
537
798
    lookup table, something about the available options, what optargs
586
847
                               % (cmd, argname.upper()))
587
848
            else:
588
849
                argdict[argname] = args.pop(0)
589
 
            
 
850
 
590
851
    if args:
591
852
        raise errors.BzrCommandError("extra argument to command %s: %s"
592
853
                                     % (cmd, args[0]))
600
861
 
601
862
    tracer = trace.Trace(count=1, trace=0)
602
863
    sys.settrace(tracer.globaltrace)
603
 
 
604
 
    ret = the_callable(*args, **kwargs)
605
 
 
606
 
    sys.settrace(None)
607
 
    results = tracer.results()
608
 
    results.write_results(show_missing=1, summary=False,
609
 
                          coverdir=dirname)
 
864
    threading.settrace(tracer.globaltrace)
 
865
 
 
866
    try:
 
867
        return exception_to_return_code(the_callable, *args, **kwargs)
 
868
    finally:
 
869
        sys.settrace(None)
 
870
        results = tracer.results()
 
871
        results.write_results(show_missing=1, summary=False,
 
872
                              coverdir=dirname)
610
873
 
611
874
 
612
875
def apply_profiled(the_callable, *args, **kwargs):
617
880
    try:
618
881
        prof = hotshot.Profile(pfname)
619
882
        try:
620
 
            ret = prof.runcall(the_callable, *args, **kwargs) or 0
 
883
            ret = prof.runcall(exception_to_return_code, the_callable, *args,
 
884
                **kwargs) or 0
621
885
        finally:
622
886
            prof.close()
623
887
        stats = hotshot.stats.load(pfname)
632
896
        os.remove(pfname)
633
897
 
634
898
 
 
899
def exception_to_return_code(the_callable, *args, **kwargs):
 
900
    """UI level helper for profiling and coverage.
 
901
 
 
902
    This transforms exceptions into a return value of 3. As such its only
 
903
    relevant to the UI layer, and should never be called where catching
 
904
    exceptions may be desirable.
 
905
    """
 
906
    try:
 
907
        return the_callable(*args, **kwargs)
 
908
    except (KeyboardInterrupt, Exception), e:
 
909
        # used to handle AssertionError and KeyboardInterrupt
 
910
        # specially here, but hopefully they're handled ok by the logger now
 
911
        exc_info = sys.exc_info()
 
912
        exitcode = trace.report_exception(exc_info, sys.stderr)
 
913
        if os.environ.get('BZR_PDB'):
 
914
            print '**** entering debugger'
 
915
            tb = exc_info[2]
 
916
            import pdb
 
917
            if sys.version_info[:2] < (2, 6):
 
918
                # XXX: we want to do
 
919
                #    pdb.post_mortem(tb)
 
920
                # but because pdb.post_mortem gives bad results for tracebacks
 
921
                # from inside generators, we do it manually.
 
922
                # (http://bugs.python.org/issue4150, fixed in Python 2.6)
 
923
 
 
924
                # Setup pdb on the traceback
 
925
                p = pdb.Pdb()
 
926
                p.reset()
 
927
                p.setup(tb.tb_frame, tb)
 
928
                # Point the debugger at the deepest frame of the stack
 
929
                p.curindex = len(p.stack) - 1
 
930
                p.curframe = p.stack[p.curindex][0]
 
931
                # Start the pdb prompt.
 
932
                p.print_stack_entry(p.stack[p.curindex])
 
933
                p.execRcLines()
 
934
                p.cmdloop()
 
935
            else:
 
936
                pdb.post_mortem(tb)
 
937
        return exitcode
 
938
 
 
939
 
635
940
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
636
941
    from bzrlib.lsprof import profile
637
 
    ret, stats = profile(the_callable, *args, **kwargs)
 
942
    ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
638
943
    stats.sort()
639
944
    if filename is None:
640
945
        stats.pprint()
644
949
    return ret
645
950
 
646
951
 
 
952
@deprecated_function(deprecated_in((2, 2, 0)))
647
953
def shlex_split_unicode(unsplit):
648
 
    import shlex
649
 
    return [u.decode('utf-8') for u in shlex.split(unsplit.encode('utf-8'))]
 
954
    return cmdline.split(unsplit)
650
955
 
651
956
 
652
957
def get_alias(cmd, config=None):
664
969
        config = bzrlib.config.GlobalConfig()
665
970
    alias = config.get_alias(cmd)
666
971
    if (alias):
667
 
        return shlex_split_unicode(alias)
 
972
        return cmdline.split(alias)
668
973
    return None
669
974
 
670
975
 
671
 
def run_bzr(argv):
 
976
def run_bzr(argv, load_plugins=load_plugins, disable_plugins=disable_plugins):
672
977
    """Execute a command.
673
978
 
674
 
    argv
675
 
       The command-line arguments, without the program name from argv[0]
676
 
       These should already be decoded. All library/test code calling
677
 
       run_bzr should be passing valid strings (don't need decoding).
678
 
    
679
 
    Returns a command status or raises an exception.
 
979
    :param argv: The command-line arguments, without the program name from
 
980
        argv[0] These should already be decoded. All library/test code calling
 
981
        run_bzr should be passing valid strings (don't need decoding).
 
982
    :param load_plugins: What function to call when triggering plugin loading.
 
983
        This function should take no arguments and cause all plugins to be
 
984
        loaded.
 
985
    :param disable_plugins: What function to call when disabling plugin
 
986
        loading. This function should take no arguments and cause all plugin
 
987
        loading to be prohibited (so that code paths in your application that
 
988
        know about some plugins possibly being present will fail to import
 
989
        those plugins even if they are installed.)
 
990
    :return: Returns a command exit code or raises an exception.
680
991
 
681
992
    Special master options: these must come before the command because
682
993
    they control how the command is interpreted.
699
1010
 
700
1011
    --coverage
701
1012
        Generate line coverage report in the specified directory.
 
1013
 
 
1014
    --concurrency
 
1015
        Specify the number of processes that can be run concurrently (selftest).
702
1016
    """
 
1017
    trace.mutter("bazaar version: " + bzrlib.__version__)
703
1018
    argv = list(argv)
704
1019
    trace.mutter("bzr arguments: %r", argv)
705
1020
 
729
1044
            opt_no_aliases = True
730
1045
        elif a == '--builtin':
731
1046
            opt_builtin = True
 
1047
        elif a == '--concurrency':
 
1048
            os.environ['BZR_CONCURRENCY'] = argv[i + 1]
 
1049
            i += 1
732
1050
        elif a == '--coverage':
733
1051
            opt_coverage_dir = argv[i + 1]
734
1052
            i += 1
738
1056
            argv_copy.append(a)
739
1057
        i += 1
740
1058
 
 
1059
    debug.set_debug_flags_from_config()
 
1060
 
 
1061
    if not opt_no_plugins:
 
1062
        load_plugins()
 
1063
    else:
 
1064
        disable_plugins()
 
1065
 
741
1066
    argv = argv_copy
742
1067
    if (not argv):
743
 
        from bzrlib.builtins import cmd_help
744
 
        cmd_help().run_argv_aliases([])
 
1068
        get_cmd_object('help').run_argv_aliases([])
745
1069
        return 0
746
1070
 
747
1071
    if argv[0] == '--version':
748
 
        from bzrlib.builtins import cmd_version
749
 
        cmd_version().run_argv_aliases([])
 
1072
        get_cmd_object('version').run_argv_aliases([])
750
1073
        return 0
751
1074
 
752
 
    if not opt_no_plugins:
753
 
        from bzrlib.plugin import load_plugins
754
 
        load_plugins()
755
 
    else:
756
 
        from bzrlib.plugin import disable_plugins
757
 
        disable_plugins()
758
 
 
759
1075
    alias_argv = None
760
1076
 
761
1077
    if not opt_no_aliases:
793
1109
            ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
794
1110
        else:
795
1111
            ret = run(*run_argv)
796
 
        if 'memory' in debug.debug_flags:
797
 
            trace.debug_memory('Process status after command:', short=False)
798
1112
        return ret or 0
799
1113
    finally:
800
1114
        # reset, in case we may do other commands later within the same
801
1115
        # process. Commands that want to execute sub-commands must propagate
802
1116
        # --verbose in their own way.
 
1117
        if 'memory' in debug.debug_flags:
 
1118
            trace.debug_memory('Process status after command:', short=False)
803
1119
        option._verbosity_level = saved_verbosity_level
804
1120
 
 
1121
 
805
1122
def display_command(func):
806
1123
    """Decorator that suppresses pipe/interrupt errors."""
807
1124
    def ignore_pipe(*args, **kwargs):
822
1139
    return ignore_pipe
823
1140
 
824
1141
 
825
 
def main(argv):
826
 
    import bzrlib.ui
827
 
    from bzrlib.ui.text import TextUIFactory
828
 
    bzrlib.ui.ui_factory = TextUIFactory()
829
 
 
830
 
    # Is this a final release version? If so, we should suppress warnings
831
 
    if bzrlib.version_info[3] == 'final':
832
 
        from bzrlib import symbol_versioning
833
 
        symbol_versioning.suppress_deprecation_warnings(override=False)
834
 
    try:
835
 
        user_encoding = osutils.get_user_encoding()
836
 
        argv = [a.decode(user_encoding) for a in argv[1:]]
837
 
    except UnicodeDecodeError:
838
 
        raise errors.BzrError(("Parameter '%r' is unsupported by the current "
839
 
                                                            "encoding." % a))
 
1142
def install_bzr_command_hooks():
 
1143
    """Install the hooks to supply bzr's own commands."""
 
1144
    if _list_bzr_commands in Command.hooks["list_commands"]:
 
1145
        return
 
1146
    Command.hooks.install_named_hook("list_commands", _list_bzr_commands,
 
1147
        "bzr commands")
 
1148
    Command.hooks.install_named_hook("get_command", _get_bzr_command,
 
1149
        "bzr commands")
 
1150
    Command.hooks.install_named_hook("get_command", _get_plugin_command,
 
1151
        "bzr plugin commands")
 
1152
    Command.hooks.install_named_hook("get_command", _get_external_command,
 
1153
        "bzr external command lookup")
 
1154
    Command.hooks.install_named_hook("get_missing_command", _try_plugin_provider,
 
1155
        "bzr plugin-provider-db check")
 
1156
 
 
1157
 
 
1158
 
 
1159
def _specified_or_unicode_argv(argv):
 
1160
    # For internal or testing use, argv can be passed.  Otherwise, get it from
 
1161
    # the process arguments in a unicode-safe way.
 
1162
    if argv is None:
 
1163
        return osutils.get_unicode_argv()
 
1164
    else:
 
1165
        new_argv = []
 
1166
        try:
 
1167
            # ensure all arguments are unicode strings
 
1168
            for a in argv[1:]:
 
1169
                if isinstance(a, unicode):
 
1170
                    new_argv.append(a)
 
1171
                else:
 
1172
                    new_argv.append(a.decode('ascii'))
 
1173
        except UnicodeDecodeError:
 
1174
            raise errors.BzrError("argv should be list of unicode strings.")
 
1175
        return new_argv
 
1176
 
 
1177
 
 
1178
def main(argv=None):
 
1179
    """Main entry point of command-line interface.
 
1180
 
 
1181
    Typically `bzrlib.initialize` should be called first.
 
1182
 
 
1183
    :param argv: list of unicode command-line arguments similar to sys.argv.
 
1184
        argv[0] is script name usually, it will be ignored.
 
1185
        Don't pass here sys.argv because this list contains plain strings
 
1186
        and not unicode; pass None instead.
 
1187
 
 
1188
    :return: exit code of bzr command.
 
1189
    """
 
1190
    argv = _specified_or_unicode_argv(argv)
 
1191
    _register_builtin_commands()
840
1192
    ret = run_bzr_catch_errors(argv)
 
1193
    bzrlib.ui.ui_factory.log_transport_activity(
 
1194
        display=('bytes' in debug.debug_flags))
841
1195
    trace.mutter("return code %d", ret)
842
1196
    return ret
843
1197
 
844
1198
 
845
1199
def run_bzr_catch_errors(argv):
846
 
    # Note: The except clause logic below should be kept in sync with the
847
 
    # profile() routine in lsprof.py.
848
 
    try:
849
 
        return run_bzr(argv)
850
 
    except (KeyboardInterrupt, Exception), e:
851
 
        # used to handle AssertionError and KeyboardInterrupt
852
 
        # specially here, but hopefully they're handled ok by the logger now
853
 
        exitcode = trace.report_exception(sys.exc_info(), sys.stderr)
854
 
        if os.environ.get('BZR_PDB'):
855
 
            print '**** entering debugger'
856
 
            import pdb
857
 
            pdb.post_mortem(sys.exc_traceback)
858
 
        return exitcode
 
1200
    """Run a bzr command with parameters as described by argv.
 
1201
 
 
1202
    This function assumed that that UI layer is setup, that symbol deprecations
 
1203
    are already applied, and that unicode decoding has already been performed on argv.
 
1204
    """
 
1205
    # done here so that they're covered for every test run
 
1206
    install_bzr_command_hooks()
 
1207
    return exception_to_return_code(run_bzr, argv)
859
1208
 
860
1209
 
861
1210
def run_bzr_catch_user_errors(argv):
864
1213
    This is used for the test suite, and might be useful for other programs
865
1214
    that want to wrap the commandline interface.
866
1215
    """
 
1216
    # done here so that they're covered for every test run
 
1217
    install_bzr_command_hooks()
867
1218
    try:
868
1219
        return run_bzr(argv)
869
1220
    except Exception, e:
891
1242
        if topic and topic.startswith(self.prefix):
892
1243
            topic = topic[len(self.prefix):]
893
1244
        try:
894
 
            cmd = _get_cmd_object(topic)
 
1245
            cmd = _get_cmd_object(topic, check_missing=False)
895
1246
        except KeyError:
896
1247
            return []
897
1248
        else:
903
1254
 
904
1255
    def plugin_for_command(self, cmd_name):
905
1256
        '''Takes a command and returns the information for that plugin
906
 
        
907
 
        :return: A dictionary with all the available information 
 
1257
 
 
1258
        :return: A dictionary with all the available information
908
1259
        for the requested plugin
909
1260
        '''
910
1261
        raise NotImplementedError
918
1269
            yield provider
919
1270
 
920
1271
command_providers_registry = ProvidersRegistry()
921
 
 
922
 
 
923
 
if __name__ == '__main__':
924
 
    sys.exit(main(sys.argv))