18
18
# TODO: probably should say which arguments are candidates for glob
19
19
# expansion on windows and do that at the command level.
21
# TODO: Help messages for options.
21
23
# TODO: Define arguments by objects, rather than just using names.
22
24
# Those objects can specify the expected type of the argument, which
23
# would help with validation and shell completion. They could also provide
24
# help/explanation for that argument in a structured way.
26
# TODO: Specific "examples" property on commands for consistent formatting.
25
# would help with validation and shell completion.
28
27
# TODO: "--profile=cum", to change sort order. Is there any value in leaving
29
28
# the profile output behind so it can be interactively examined?
34
from bzrlib.lazy_import import lazy_import
35
lazy_import(globals(), """
32
from warnings import warn
33
from inspect import getdoc
38
from warnings import warn
51
from bzrlib import registry
53
from bzrlib.hooks import Hooks
38
from bzrlib.trace import mutter, note, log_error, warning, be_quiet
39
from bzrlib.errors import (BzrError,
44
from bzrlib.revisionspec import RevisionSpec
45
from bzrlib import BZRDIR
54
46
from bzrlib.option import Option
57
class CommandInfo(object):
58
"""Information about a command."""
60
def __init__(self, aliases):
61
"""The list of aliases for the command."""
62
self.aliases = aliases
65
def from_command(klass, command):
66
"""Factory to construct a CommandInfo from a command."""
67
return klass(command.aliases)
70
class CommandRegistry(registry.Registry):
73
def _get_name(command_name):
74
if command_name.startswith("cmd_"):
75
return _unsquish_command_name(command_name)
79
def register(self, cmd, decorate=False):
80
"""Utility function to help register a command
82
:param cmd: Command subclass to register
83
:param decorate: If true, allow overriding an existing command
84
of the same name; the old command is returned by this function.
85
Otherwise it is an error to try to override an existing command.
88
k_unsquished = self._get_name(k)
90
previous = self.get(k_unsquished)
92
previous = _builtin_commands().get(k_unsquished)
93
info = CommandInfo.from_command(cmd)
95
registry.Registry.register(self, k_unsquished, cmd,
96
override_existing=decorate, info=info)
98
trace.log_error('Two plugins defined the same command: %r' % k)
99
trace.log_error('Not loading the one in %r' %
100
sys.modules[cmd.__module__])
101
trace.log_error('Previously this command was registered from %r' %
102
sys.modules[previous.__module__])
105
def register_lazy(self, command_name, aliases, module_name):
106
"""Register a command without loading its module.
108
:param command_name: The primary name of the command.
109
:param aliases: A list of aliases for the command.
110
:module_name: The module that the command lives in.
112
key = self._get_name(command_name)
113
registry.Registry.register_lazy(self, key, module_name, command_name,
114
info=CommandInfo(aliases))
117
plugin_cmds = CommandRegistry()
120
51
def register_command(cmd, decorate=False):
52
"Utility function to help register a command"
121
53
global plugin_cmds
122
return plugin_cmds.register(cmd, decorate)
55
if k.startswith("cmd_"):
56
k_unsquished = _unsquish_command_name(k)
59
if not plugin_cmds.has_key(k_unsquished):
60
plugin_cmds[k_unsquished] = cmd
61
mutter('registered plugin command %s', k_unsquished)
62
if decorate and k_unsquished in builtin_command_names():
63
return _builtin_commands()[k_unsquished]
65
result = plugin_cmds[k_unsquished]
66
plugin_cmds[k_unsquished] = cmd
69
log_error('Two plugins defined the same command: %r' % k)
70
log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
125
73
def _squish_command_name(cmd):
296
195
"""Construct an instance of this command."""
297
196
if self.__doc__ == Command.__doc__:
298
197
warn("No help message set for %r" % self)
299
# List of standard options directly supported
300
self.supported_std_options = []
302
def _maybe_expand_globs(self, file_list):
303
"""Glob expand file_list if the platform does not do that itself.
305
:return: A possibly empty list of unicode paths.
307
Introduced in bzrlib 0.18.
311
if sys.platform == 'win32':
312
file_list = win32utils.glob_expand(file_list)
313
return list(file_list)
316
"""Return single-line grammar for this command.
318
Only describes arguments, not options.
320
s = 'bzr ' + self.name() + ' '
321
for aname in self.takes_args:
322
aname = aname.upper()
323
if aname[-1] in ['$', '+']:
324
aname = aname[:-1] + '...'
325
elif aname[-1] == '?':
326
aname = '[' + aname[:-1] + ']'
327
elif aname[-1] == '*':
328
aname = '[' + aname[:-1] + '...]'
330
s = s[:-1] # remove last space
333
def get_help_text(self, additional_see_also=None, plain=True,
334
see_also_as_links=False):
335
"""Return a text string with help for this command.
337
:param additional_see_also: Additional help topics to be
339
:param plain: if False, raw help (reStructuredText) is
340
returned instead of plain text.
341
:param see_also_as_links: if True, convert items in 'See also'
342
list to internal links (used by bzr_man rstx generator)
346
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
348
# Extract the summary (purpose) and sections out from the text
349
purpose,sections,order = self._get_help_parts(doc)
351
# If a custom usage section was provided, use it
352
if sections.has_key('Usage'):
353
usage = sections.pop('Usage')
355
usage = self._usage()
357
# The header is the purpose and usage
359
result += ':Purpose: %s\n' % purpose
360
if usage.find('\n') >= 0:
361
result += ':Usage:\n%s\n' % usage
363
result += ':Usage: %s\n' % usage
367
options = option.get_optparser(self.options()).format_option_help()
368
if options.startswith('Options:'):
369
result += ':' + options
370
elif options.startswith('options:'):
371
# Python 2.4 version of optparse
372
result += ':Options:' + options[len('options:'):]
377
# Add the description, indenting it 2 spaces
378
# to match the indentation of the options
379
if sections.has_key(None):
380
text = sections.pop(None)
381
text = '\n '.join(text.splitlines())
382
result += ':%s:\n %s\n\n' % ('Description',text)
384
# Add the custom sections (e.g. Examples). Note that there's no need
385
# to indent these as they must be indented already in the source.
388
if sections.has_key(label):
389
result += ':%s:\n%s\n\n' % (label,sections[label])
391
# Add the aliases, source (plug-in) and see also links, if any
393
result += ':Aliases: '
394
result += ', '.join(self.aliases) + '\n'
395
plugin_name = self.plugin_name()
396
if plugin_name is not None:
397
result += ':From: plugin "%s"\n' % plugin_name
398
see_also = self.get_see_also(additional_see_also)
400
if not plain and see_also_as_links:
402
for item in see_also:
404
# topics doesn't have an independent section
405
# so don't create a real link
406
see_also_links.append(item)
408
# Use a reST link for this entry
409
see_also_links.append("`%s`_" % (item,))
410
see_also = see_also_links
411
result += ':See also: '
412
result += ', '.join(see_also) + '\n'
414
# If this will be rendered as plain text, convert it
416
import bzrlib.help_topics
417
result = bzrlib.help_topics.help_as_plain_text(result)
421
def _get_help_parts(text):
422
"""Split help text into a summary and named sections.
424
:return: (summary,sections,order) where summary is the top line and
425
sections is a dictionary of the rest indexed by section name.
426
order is the order the section appear in the text.
427
A section starts with a heading line of the form ":xxx:".
428
Indented text on following lines is the section value.
429
All text found outside a named section is assigned to the
430
default section which is given the key of None.
432
def save_section(sections, order, label, section):
434
if sections.has_key(label):
435
sections[label] += '\n' + section
438
sections[label] = section
440
lines = text.rstrip().splitlines()
441
summary = lines.pop(0)
444
label,section = None,''
446
if line.startswith(':') and line.endswith(':') and len(line) > 2:
447
save_section(sections, order, label, section)
448
label,section = line[1:-1],''
449
elif (label is not None) and len(line) > 1 and not line[0].isspace():
450
save_section(sections, order, label, section)
451
label,section = None,line
454
section += '\n' + line
457
save_section(sections, order, label, section)
458
return summary, sections, order
460
def get_help_topic(self):
461
"""Return the commands help topic - its name."""
464
def get_see_also(self, additional_terms=None):
465
"""Return a list of help topics that are related to this command.
467
The list is derived from the content of the _see_also attribute. Any
468
duplicates are removed and the result is in lexical order.
469
:param additional_terms: Additional help topics to cross-reference.
470
:return: A list of help topics.
472
see_also = set(getattr(self, '_see_also', []))
474
see_also.update(additional_terms)
475
return sorted(see_also)
477
199
def options(self):
478
200
"""Return dict of valid options for this command.
480
202
Maps from long option name to option object."""
481
r = Option.STD_OPTIONS.copy()
204
r['help'] = Option.OPTIONS['help']
483
205
for o in self.takes_options:
484
if isinstance(o, basestring):
485
o = option.Option.OPTIONS[o]
206
if not isinstance(o, Option):
207
o = Option.OPTIONS[o]
487
if o.name in std_names:
488
self.supported_std_options.append(o.name)
491
def _setup_outf(self):
492
"""Return a file linked to stdout, which has proper encoding."""
493
# Originally I was using self.stdout, but that looks
494
# *way* too much like sys.stdout
495
if self.encoding_type == 'exact':
496
# force sys.stdout to be binary stream on win32
497
if sys.platform == 'win32':
498
fileno = getattr(sys.stdout, 'fileno', None)
501
msvcrt.setmode(fileno(), os.O_BINARY)
502
self.outf = sys.stdout
505
output_encoding = osutils.get_terminal_encoding()
507
self.outf = codecs.getwriter(output_encoding)(sys.stdout,
508
errors=self.encoding_type)
509
# For whatever reason codecs.getwriter() does not advertise its encoding
510
# it just returns the encoding of the wrapped file, which is completely
511
# bogus. So set the attribute, so we can find the correct encoding later.
512
self.outf.encoding = output_encoding
514
def run_argv_aliases(self, argv, alias_argv=None):
515
"""Parse the command line and run with extra aliases in alias_argv."""
517
warn("Passing None for [] is deprecated from bzrlib 0.10",
518
DeprecationWarning, stacklevel=2)
520
args, opts = parse_args(self, argv, alias_argv)
522
# Process the standard options
211
def run_argv(self, argv):
212
"""Parse command line and run."""
213
args, opts = parse_args(self, argv)
523
214
if 'help' in opts: # e.g. bzr add --help
524
sys.stdout.write(self.get_help_text())
215
from bzrlib.help import help_on_command
216
help_on_command(self.name())
526
trace.set_verbosity_level(option._verbosity_level)
527
if 'verbose' in self.supported_std_options:
528
opts['verbose'] = trace.is_verbose()
529
elif opts.has_key('verbose'):
531
if 'quiet' in self.supported_std_options:
532
opts['quiet'] = trace.is_quiet()
533
elif opts.has_key('quiet'):
218
# XXX: This should be handled by the parser
219
allowed_names = self.options().keys()
221
if oname not in allowed_names:
222
raise BzrCommandError("option '--%s' is not allowed for command %r"
223
% (oname, self.name()))
536
224
# mix arguments and options into one dictionary
537
225
cmdargs = _match_argform(self.name(), self.takes_args, args)
608
294
lookup table, something about the available options, what optargs
609
295
they take, and which commands will accept them.
611
# TODO: make it a method of the Command?
612
parser = option.get_optparser(command.options())
613
if alias_argv is not None:
614
args = alias_argv + argv
618
options, args = parser.parse_args(args)
619
opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
620
v is not option.OptionParser.DEFAULT_VALUE])
297
# TODO: chop up this beast; make it a method of the Command
301
cmd_options = command.options()
309
# We've received a standalone -- No more flags
313
# option names must not be unicode
317
mutter(" got option %r", a)
319
optname, optarg = a[2:].split('=', 1)
322
if optname not in cmd_options:
323
raise BzrOptionError('unknown long option %r for command %s'
324
% (a, command.name()))
327
if shortopt in Option.SHORT_OPTIONS:
328
# Multi-character options must have a space to delimit
330
# ^^^ what does this mean? mbp 20051014
331
optname = Option.SHORT_OPTIONS[shortopt].name
333
# Single character short options, can be chained,
334
# and have their value appended to their name
336
if shortopt not in Option.SHORT_OPTIONS:
337
# We didn't find the multi-character name, and we
338
# didn't find the single char name
339
raise BzrError('unknown short option %r' % a)
340
optname = Option.SHORT_OPTIONS[shortopt].name
343
# There are extra things on this option
344
# see if it is the value, or if it is another
346
optargfn = Option.OPTIONS[optname].type
348
# This option does not take an argument, so the
349
# next entry is another short option, pack it back
351
argv.insert(0, '-' + a[2:])
353
# This option takes an argument, so pack it
357
if optname not in cmd_options:
358
raise BzrOptionError('unknown short option %r for command'
359
' %s' % (shortopt, command.name()))
361
# XXX: Do we ever want to support this, e.g. for -r?
362
raise BzrError('repeated option %r' % a)
364
option_obj = cmd_options[optname]
365
optargfn = option_obj.type
369
raise BzrError('option %r needs an argument' % a)
372
opts[optname] = optargfn(optarg)
375
raise BzrError('option %r takes no argument' % optname)
621
379
return args, opts
638
396
argdict[argname + '_list'] = None
639
397
elif ap[-1] == '+':
641
raise errors.BzrCommandError("command %r needs one or more %s"
642
% (cmd, argname.upper()))
399
raise BzrCommandError("command %r needs one or more %s"
400
% (cmd, argname.upper()))
644
402
argdict[argname + '_list'] = args[:]
646
404
elif ap[-1] == '$': # all but one
647
405
if len(args) < 2:
648
raise errors.BzrCommandError("command %r needs one or more %s"
649
% (cmd, argname.upper()))
406
raise BzrCommandError("command %r needs one or more %s"
407
% (cmd, argname.upper()))
650
408
argdict[argname + '_list'] = args[:-1]
653
411
# just a plain arg
656
raise errors.BzrCommandError("command %r requires argument %s"
657
% (cmd, argname.upper()))
414
raise BzrCommandError("command %r requires argument %s"
415
% (cmd, argname.upper()))
659
417
argdict[argname] = args.pop(0)
662
raise errors.BzrCommandError("extra argument to command %s: %s"
420
raise BzrCommandError("extra argument to command %s: %s"
667
def apply_coveraged(dirname, the_callable, *args, **kwargs):
668
# Cannot use "import trace", as that would import bzrlib.trace instead of
669
# the standard library's trace.
670
trace = __import__('trace')
672
tracer = trace.Trace(count=1, trace=0)
673
sys.settrace(tracer.globaltrace)
675
ret = the_callable(*args, **kwargs)
678
results = tracer.results()
679
results.write_results(show_missing=1, summary=False,
683
427
def apply_profiled(the_callable, *args, **kwargs):
756
465
Do not load plugin modules at all
762
468
Only use builtin commands. (Plugins are still allowed to change
763
469
other behaviour.)
766
Run under the Python hotshot profiler.
769
Run under the Python lsprof profiler.
772
Generate line coverage report in the specified directory.
472
Run under the Python profiler.
775
trace.mutter("bzr arguments: %r", argv)
474
argv = [a.decode(bzrlib.user_encoding) for a in argv]
777
opt_lsprof = opt_profile = opt_no_plugins = opt_builtin = \
778
opt_no_aliases = False
779
opt_lsprof_file = opt_coverage_dir = None
476
opt_profile = opt_no_plugins = opt_builtin = False
781
478
# --no-plugins is handled specially at a very early stage. We need
782
479
# to load plugins before doing other command parsing so that they
783
480
# can override commands, but this needs to happen first.
789
483
if a == '--profile':
790
484
opt_profile = True
791
elif a == '--lsprof':
793
elif a == '--lsprof-file':
795
opt_lsprof_file = argv[i + 1]
797
485
elif a == '--no-plugins':
798
486
opt_no_plugins = True
799
elif a == '--no-aliases':
800
opt_no_aliases = True
801
487
elif a == '--builtin':
802
488
opt_builtin = True
803
elif a == '--coverage':
804
opt_coverage_dir = argv[i + 1]
806
elif a.startswith('-D'):
807
debug.debug_flags.add(a[2:])
489
elif a in ('--quiet', '-q'):
814
from bzrlib.builtins import cmd_help
815
cmd_help().run_argv_aliases([])
495
if (not argv) or (argv[0] == '--help'):
496
from bzrlib.help import help
818
503
if argv[0] == '--version':
819
from bzrlib.builtins import cmd_version
820
cmd_version().run_argv_aliases([])
504
from bzrlib.builtins import show_version
823
508
if not opt_no_plugins:
824
509
from bzrlib.plugin import load_plugins
827
from bzrlib.plugin import disable_plugins
832
if not opt_no_aliases:
833
alias_argv = get_alias(argv[0])
835
user_encoding = osutils.get_user_encoding()
836
alias_argv = [a.decode(user_encoding) for a in alias_argv]
837
argv[0] = alias_argv.pop(0)
840
# We want only 'ascii' command names, but the user may have typed
841
# in a Unicode name. In that case, they should just get a
842
# 'command not found' error later.
512
cmd = str(argv.pop(0))
844
514
cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
845
run = cmd_obj.run_argv_aliases
846
run_argv = [argv, alias_argv]
849
# We can be called recursively (tests for example), but we don't want
850
# the verbosity level to propagate.
851
saved_verbosity_level = option._verbosity_level
852
option._verbosity_level = 0
856
'--coverage ignored, because --lsprof is in use.')
857
ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
861
'--coverage ignored, because --profile is in use.')
862
ret = apply_profiled(run, *run_argv)
863
elif opt_coverage_dir:
864
ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
518
ret = apply_profiled(cmd_obj.run_argv, argv)
867
if 'memory' in debug.debug_flags:
868
trace.debug_memory('Process status after command:', short=False)
520
ret = cmd_obj.run_argv(argv)
871
# reset, in case we may do other commands later within the same
872
# process. Commands that want to execute sub-commands must propagate
873
# --verbose in their own way.
874
option._verbosity_level = saved_verbosity_level
523
# reset, in case we may do other commands later within the same process
877
526
def display_command(func):
878
527
"""Decorator that suppresses pipe/interrupt errors."""
899
bzrlib.ui.ui_factory = bzrlib.ui.make_ui_for_terminal(
900
sys.stdin, sys.stdout, sys.stderr)
902
# Is this a final release version? If so, we should suppress warnings
903
if bzrlib.version_info[3] == 'final':
904
from bzrlib import symbol_versioning
905
symbol_versioning.suppress_deprecation_warnings(override=False)
907
user_encoding = osutils.get_user_encoding()
908
argv = [a.decode(user_encoding) for a in argv[1:]]
909
except UnicodeDecodeError:
910
raise errors.BzrError(("Parameter '%r' is unsupported by the current "
912
ret = run_bzr_catch_errors(argv)
913
trace.mutter("return code %d", ret)
546
from bzrlib.ui.text import TextUIFactory
547
## bzrlib.trace.enable_default_logging()
548
bzrlib.trace.log_startup(argv)
549
bzrlib.ui.ui_factory = TextUIFactory()
550
ret = run_bzr_catch_errors(argv[1:])
551
mutter("return code %d", ret)
917
555
def run_bzr_catch_errors(argv):
918
# Note: The except clause logic below should be kept in sync with the
919
# profile() routine in lsprof.py.
922
except (KeyboardInterrupt, Exception), e:
560
# do this here inside the exception wrappers to catch EPIPE
923
563
# used to handle AssertionError and KeyboardInterrupt
924
564
# specially here, but hopefully they're handled ok by the logger now
925
exc_info = sys.exc_info()
926
exitcode = trace.report_exception(exc_info, sys.stderr)
927
if os.environ.get('BZR_PDB'):
928
print '**** entering debugger'
931
if sys.version_info[:2] < (2, 6):
933
# pdb.post_mortem(tb)
934
# but because pdb.post_mortem gives bad results for tracebacks
935
# from inside generators, we do it manually.
936
# (http://bugs.python.org/issue4150, fixed in Python 2.6)
938
# Setup pdb on the traceback
941
p.setup(tb.tb_frame, tb)
942
# Point the debugger at the deepest frame of the stack
943
p.curindex = len(p.stack) - 1
944
p.curframe = p.stack[p.curindex]
945
# Start the pdb prompt.
946
p.print_stack_entry(p.stack[p.curindex])
954
def run_bzr_catch_user_errors(argv):
955
"""Run bzr and report user errors, but let internal errors propagate.
957
This is used for the test suite, and might be useful for other programs
958
that want to wrap the commandline interface.
963
if (isinstance(e, (OSError, IOError))
964
or not getattr(e, 'internal_error', True)):
965
trace.report_exception(sys.exc_info(), sys.stderr)
971
class HelpCommandIndex(object):
972
"""A index for bzr help that returns commands."""
975
self.prefix = 'commands/'
977
def get_topics(self, topic):
978
"""Search for topic amongst commands.
980
:param topic: A topic to search for.
981
:return: A list which is either empty or contains a single
984
if topic and topic.startswith(self.prefix):
985
topic = topic[len(self.prefix):]
987
cmd = _get_cmd_object(topic)
994
class Provider(object):
995
'''Generic class to be overriden by plugins'''
997
def plugin_for_command(self, cmd_name):
998
'''Takes a command and returns the information for that plugin
1000
:return: A dictionary with all the available information
1001
for the requested plugin
1003
raise NotImplementedError
1006
class ProvidersRegistry(registry.Registry):
1007
'''This registry exists to allow other providers to exist'''
1010
for key, provider in self.iteritems():
1013
command_providers_registry = ProvidersRegistry()
566
if (isinstance(e, IOError)
567
and hasattr(e, 'errno')
568
and e.errno == errno.EPIPE):
569
bzrlib.trace.note('broken pipe')
572
bzrlib.trace.log_exception()
573
if os.environ.get('BZR_PDB'):
574
print '**** entering debugger'
576
pdb.post_mortem(sys.exc_traceback)
1016
579
if __name__ == '__main__':
1017
580
sys.exit(main(sys.argv))
added
removed
bzrlib/commands.py
