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.symbol_versioning import (
38
from bzrlib.trace import mutter, note, log_error, warning
39
from bzrlib.errors import (BzrError,
44
from bzrlib.revisionspec import RevisionSpec
45
from bzrlib import BZRDIR
56
46
from bzrlib.option import Option
62
51
def register_command(cmd, decorate=False):
63
"""Utility function to help register a command
65
:param cmd: Command subclass to register
66
:param decorate: If true, allow overriding an existing command
67
of the same name; the old command is returned by this function.
68
Otherwise it is an error to try to override an existing command.
52
"Utility function to help register a command"
72
55
if k.startswith("cmd_"):
73
56
k_unsquished = _unsquish_command_name(k)
76
if k_unsquished not in plugin_cmds:
59
if not plugin_cmds.has_key(k_unsquished):
77
60
plugin_cmds[k_unsquished] = cmd
78
## trace.mutter('registered plugin command %s', k_unsquished)
61
mutter('registered plugin command %s', k_unsquished)
79
62
if decorate and k_unsquished in builtin_command_names():
80
63
return _builtin_commands()[k_unsquished]
240
187
"""Construct an instance of this command."""
241
188
if self.__doc__ == Command.__doc__:
242
189
warn("No help message set for %r" % self)
243
# List of standard options directly supported
244
self.supported_std_options = []
246
def _maybe_expand_globs(self, file_list):
247
"""Glob expand file_list if the platform does not do that itself.
249
:return: A possibly empty list of unicode paths.
251
Introduced in bzrlib 0.18.
255
if sys.platform == 'win32':
256
file_list = win32utils.glob_expand(file_list)
257
return list(file_list)
260
"""Return single-line grammar for this command.
262
Only describes arguments, not options.
264
s = 'bzr ' + self.name() + ' '
265
for aname in self.takes_args:
266
aname = aname.upper()
267
if aname[-1] in ['$', '+']:
268
aname = aname[:-1] + '...'
269
elif aname[-1] == '?':
270
aname = '[' + aname[:-1] + ']'
271
elif aname[-1] == '*':
272
aname = '[' + aname[:-1] + '...]'
279
def get_help_text(self, additional_see_also=None, plain=True,
280
see_also_as_links=False):
281
"""Return a text string with help for this command.
283
:param additional_see_also: Additional help topics to be
285
:param plain: if False, raw help (reStructuredText) is
286
returned instead of plain text.
287
:param see_also_as_links: if True, convert items in 'See also'
288
list to internal links (used by bzr_man rstx generator)
292
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
294
# Extract the summary (purpose) and sections out from the text
295
purpose,sections = self._get_help_parts(doc)
297
# If a custom usage section was provided, use it
298
if sections.has_key('Usage'):
299
usage = sections.pop('Usage')
301
usage = self._usage()
303
# The header is the purpose and usage
305
result += ':Purpose: %s\n' % purpose
306
if usage.find('\n') >= 0:
307
result += ':Usage:\n%s\n' % usage
309
result += ':Usage: %s\n' % usage
313
options = option.get_optparser(self.options()).format_option_help()
314
if options.startswith('Options:'):
315
result += ':' + options
316
elif options.startswith('options:'):
317
# Python 2.4 version of optparse
318
result += ':Options:' + options[len('options:'):]
323
# Add the description, indenting it 2 spaces
324
# to match the indentation of the options
325
if sections.has_key(None):
326
text = sections.pop(None)
327
text = '\n '.join(text.splitlines())
328
result += ':%s:\n %s\n\n' % ('Description',text)
330
# Add the custom sections (e.g. Examples). Note that there's no need
331
# to indent these as they must be indented already in the source.
333
labels = sorted(sections.keys())
335
result += ':%s:\n%s\n\n' % (label,sections[label])
337
# Add the aliases, source (plug-in) and see also links, if any
339
result += ':Aliases: '
340
result += ', '.join(self.aliases) + '\n'
341
plugin_name = self.plugin_name()
342
if plugin_name is not None:
343
result += ':From: plugin "%s"\n' % plugin_name
344
see_also = self.get_see_also(additional_see_also)
346
if not plain and see_also_as_links:
348
for item in see_also:
350
# topics doesn't have an independent section
351
# so don't create a real link
352
see_also_links.append(item)
354
# Use a reST link for this entry
355
see_also_links.append("`%s`_" % (item,))
356
see_also = see_also_links
357
result += ':See also: '
358
result += ', '.join(see_also) + '\n'
360
# If this will be rendered as plan text, convert it
362
import bzrlib.help_topics
363
result = bzrlib.help_topics.help_as_plain_text(result)
367
def _get_help_parts(text):
368
"""Split help text into a summary and named sections.
370
:return: (summary,sections) where summary is the top line and
371
sections is a dictionary of the rest indexed by section name.
372
A section starts with a heading line of the form ":xxx:".
373
Indented text on following lines is the section value.
374
All text found outside a named section is assigned to the
375
default section which is given the key of None.
377
def save_section(sections, label, section):
379
if sections.has_key(label):
380
sections[label] += '\n' + section
382
sections[label] = section
384
lines = text.rstrip().splitlines()
385
summary = lines.pop(0)
387
label,section = None,''
389
if line.startswith(':') and line.endswith(':') and len(line) > 2:
390
save_section(sections, label, section)
391
label,section = line[1:-1],''
392
elif label != None and len(line) > 1 and not line[0].isspace():
393
save_section(sections, label, section)
394
label,section = None,line
397
section += '\n' + line
400
save_section(sections, label, section)
401
return summary, sections
403
def get_help_topic(self):
404
"""Return the commands help topic - its name."""
407
def get_see_also(self, additional_terms=None):
408
"""Return a list of help topics that are related to this command.
410
The list is derived from the content of the _see_also attribute. Any
411
duplicates are removed and the result is in lexical order.
412
:param additional_terms: Additional help topics to cross-reference.
413
:return: A list of help topics.
415
see_also = set(getattr(self, '_see_also', []))
417
see_also.update(additional_terms)
418
return sorted(see_also)
420
191
def options(self):
421
192
"""Return dict of valid options for this command.
423
194
Maps from long option name to option object."""
424
r = Option.STD_OPTIONS.copy()
196
r['help'] = Option.OPTIONS['help']
426
197
for o in self.takes_options:
427
if isinstance(o, basestring):
428
o = option.Option.OPTIONS[o]
198
if not isinstance(o, Option):
199
o = Option.OPTIONS[o]
430
if o.name in std_names:
431
self.supported_std_options.append(o.name)
434
def _setup_outf(self):
435
"""Return a file linked to stdout, which has proper encoding."""
436
assert self.encoding_type in ['strict', 'exact', 'replace']
438
# Originally I was using self.stdout, but that looks
439
# *way* too much like sys.stdout
440
if self.encoding_type == 'exact':
441
# force sys.stdout to be binary stream on win32
442
if sys.platform == 'win32':
443
fileno = getattr(sys.stdout, 'fileno', None)
446
msvcrt.setmode(fileno(), os.O_BINARY)
447
self.outf = sys.stdout
450
output_encoding = osutils.get_terminal_encoding()
452
self.outf = codecs.getwriter(output_encoding)(sys.stdout,
453
errors=self.encoding_type)
454
# For whatever reason codecs.getwriter() does not advertise its encoding
455
# it just returns the encoding of the wrapped file, which is completely
456
# bogus. So set the attribute, so we can find the correct encoding later.
457
self.outf.encoding = output_encoding
459
def run_argv_aliases(self, argv, alias_argv=None):
460
"""Parse the command line and run with extra aliases in alias_argv."""
462
warn("Passing None for [] is deprecated from bzrlib 0.10",
463
DeprecationWarning, stacklevel=2)
465
args, opts = parse_args(self, argv, alias_argv)
467
# Process the standard options
203
def run_argv(self, argv):
204
"""Parse command line and run."""
205
args, opts = parse_args(self, argv)
468
206
if 'help' in opts: # e.g. bzr add --help
469
sys.stdout.write(self.get_help_text())
207
from bzrlib.help import help_on_command
208
help_on_command(self.name())
471
trace.set_verbosity_level(option._verbosity_level)
472
if 'verbose' in self.supported_std_options:
473
opts['verbose'] = trace.is_verbose()
474
elif opts.has_key('verbose'):
476
if 'quiet' in self.supported_std_options:
477
opts['quiet'] = trace.is_quiet()
478
elif opts.has_key('quiet'):
210
# XXX: This should be handled by the parser
211
allowed_names = self.options().keys()
213
if oname not in allowed_names:
214
raise BzrCommandError("option '--%s' is not allowed for command %r"
215
% (oname, self.name()))
481
216
# mix arguments and options into one dictionary
482
217
cmdargs = _match_argform(self.name(), self.takes_args, args)
534
286
lookup table, something about the available options, what optargs
535
287
they take, and which commands will accept them.
537
# TODO: make it a method of the Command?
538
parser = option.get_optparser(command.options())
539
if alias_argv is not None:
540
args = alias_argv + argv
544
options, args = parser.parse_args(args)
545
opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
546
v is not option.OptionParser.DEFAULT_VALUE])
289
# TODO: chop up this beast; make it a method of the Command
293
cmd_options = command.options()
301
# We've received a standalone -- No more flags
305
# option names must not be unicode
309
mutter(" got option %r" % a)
311
optname, optarg = a[2:].split('=', 1)
314
if optname not in cmd_options:
315
raise BzrOptionError('unknown long option %r for command %s'
316
% (a, command.name()))
319
if shortopt in Option.SHORT_OPTIONS:
320
# Multi-character options must have a space to delimit
322
# ^^^ what does this mean? mbp 20051014
323
optname = Option.SHORT_OPTIONS[shortopt].name
325
# Single character short options, can be chained,
326
# and have their value appended to their name
328
if shortopt not in Option.SHORT_OPTIONS:
329
# We didn't find the multi-character name, and we
330
# didn't find the single char name
331
raise BzrError('unknown short option %r' % a)
332
optname = Option.SHORT_OPTIONS[shortopt].name
335
# There are extra things on this option
336
# see if it is the value, or if it is another
338
optargfn = Option.OPTIONS[optname].type
340
# This option does not take an argument, so the
341
# next entry is another short option, pack it back
343
argv.insert(0, '-' + a[2:])
345
# This option takes an argument, so pack it
350
# XXX: Do we ever want to support this, e.g. for -r?
351
raise BzrError('repeated option %r' % a)
353
option_obj = cmd_options[optname]
354
optargfn = option_obj.type
358
raise BzrError('option %r needs an argument' % a)
361
opts[optname] = optargfn(optarg)
364
raise BzrError('option %r takes no argument' % optname)
547
368
return args, opts
564
385
argdict[argname + '_list'] = None
565
386
elif ap[-1] == '+':
567
raise errors.BzrCommandError("command %r needs one or more %s"
568
% (cmd, argname.upper()))
388
raise BzrCommandError("command %r needs one or more %s"
389
% (cmd, argname.upper()))
570
391
argdict[argname + '_list'] = args[:]
572
393
elif ap[-1] == '$': # all but one
573
394
if len(args) < 2:
574
raise errors.BzrCommandError("command %r needs one or more %s"
575
% (cmd, argname.upper()))
395
raise BzrCommandError("command %r needs one or more %s"
396
% (cmd, argname.upper()))
576
397
argdict[argname + '_list'] = args[:-1]
579
400
# just a plain arg
582
raise errors.BzrCommandError("command %r requires argument %s"
583
% (cmd, argname.upper()))
403
raise BzrCommandError("command %r requires argument %s"
404
% (cmd, argname.upper()))
585
406
argdict[argname] = args.pop(0)
588
raise errors.BzrCommandError("extra argument to command %s: %s"
409
raise BzrCommandError("extra argument to command %s: %s"
593
def apply_coveraged(dirname, the_callable, *args, **kwargs):
594
# Cannot use "import trace", as that would import bzrlib.trace instead of
595
# the standard library's trace.
596
trace = __import__('trace')
598
tracer = trace.Trace(count=1, trace=0)
599
sys.settrace(tracer.globaltrace)
601
ret = the_callable(*args, **kwargs)
604
results = tracer.results()
605
results.write_results(show_missing=1, summary=False,
609
416
def apply_profiled(the_callable, *args, **kwargs):
685
454
Do not load plugin modules at all
691
457
Only use builtin commands. (Plugins are still allowed to change
692
458
other behaviour.)
695
Run under the Python hotshot profiler.
698
Run under the Python lsprof profiler.
701
Generate line coverage report in the specified directory.
461
Run under the Python profiler.
704
trace.mutter("bzr arguments: %r", argv)
463
argv = [a.decode(bzrlib.user_encoding) for a in argv]
706
opt_lsprof = opt_profile = opt_no_plugins = opt_builtin = \
707
opt_no_aliases = False
708
opt_lsprof_file = opt_coverage_dir = None
465
opt_profile = opt_no_plugins = opt_builtin = False
710
467
# --no-plugins is handled specially at a very early stage. We need
711
468
# to load plugins before doing other command parsing so that they
712
469
# can override commands, but this needs to happen first.
718
472
if a == '--profile':
719
473
opt_profile = True
720
elif a == '--lsprof':
722
elif a == '--lsprof-file':
724
opt_lsprof_file = argv[i + 1]
726
474
elif a == '--no-plugins':
727
475
opt_no_plugins = True
728
elif a == '--no-aliases':
729
opt_no_aliases = True
730
476
elif a == '--builtin':
731
477
opt_builtin = True
732
elif a == '--coverage':
733
opt_coverage_dir = argv[i + 1]
735
elif a.startswith('-D'):
736
debug.debug_flags.add(a[2:])
743
from bzrlib.builtins import cmd_help
744
cmd_help().run_argv_aliases([])
482
if (not argv) or (argv[0] == '--help'):
483
from bzrlib.help import help
747
490
if argv[0] == '--version':
748
from bzrlib.builtins import cmd_version
749
cmd_version().run_argv_aliases([])
491
from bzrlib.builtins import show_version
752
495
if not opt_no_plugins:
753
496
from bzrlib.plugin import load_plugins
756
from bzrlib.plugin import disable_plugins
761
if not opt_no_aliases:
762
alias_argv = get_alias(argv[0])
764
alias_argv = [a.decode(bzrlib.user_encoding) for a in alias_argv]
765
argv[0] = alias_argv.pop(0)
768
# We want only 'ascii' command names, but the user may have typed
769
# in a Unicode name. In that case, they should just get a
770
# 'command not found' error later.
499
cmd = str(argv.pop(0))
772
501
cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
773
run = cmd_obj.run_argv_aliases
774
run_argv = [argv, alias_argv]
780
'--coverage ignored, because --lsprof is in use.')
781
ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
785
'--coverage ignored, because --profile is in use.')
786
ret = apply_profiled(run, *run_argv)
787
elif opt_coverage_dir:
788
ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
793
# reset, in case we may do other commands later within the same process
794
option._verbosity_level = 0
504
ret = apply_profiled(cmd_obj.run_argv, argv)
506
ret = cmd_obj.run_argv(argv)
796
509
def display_command(func):
797
"""Decorator that suppresses pipe/interrupt errors."""
798
510
def ignore_pipe(*args, **kwargs):
800
result = func(*args, **kwargs)
512
return func(*args, **kwargs)
803
513
except IOError, e:
804
if getattr(e, 'errno', None) is None:
514
if e.errno != errno.EPIPE:
806
if e.errno != errno.EPIPE:
807
# Win32 raises IOError with errno=0 on a broken pipe
808
if sys.platform != 'win32' or (e.errno not in (0, errno.EINVAL)):
811
516
except KeyboardInterrupt:
813
518
return ignore_pipe
818
from bzrlib.ui.text import TextUIFactory
819
bzrlib.ui.ui_factory = TextUIFactory()
821
argv = [a.decode(bzrlib.user_encoding) for a in argv[1:]]
822
except UnicodeDecodeError:
823
raise errors.BzrError(("Parameter '%r' is unsupported by the current "
825
ret = run_bzr_catch_errors(argv)
826
trace.mutter("return code %d", ret)
522
bzrlib.trace.log_startup(argv)
523
bzrlib.ui.ui_factory = bzrlib.ui.TextUIFactory()
525
return run_bzr_catch_errors(argv[1:])
830
528
def run_bzr_catch_errors(argv):
831
# Note: The except clause logic below should be kept in sync with the
832
# profile() routine in lsprof.py.
835
except (KeyboardInterrupt, Exception), e:
836
# used to handle AssertionError and KeyboardInterrupt
837
# specially here, but hopefully they're handled ok by the logger now
838
exitcode = trace.report_exception(sys.exc_info(), sys.stderr)
839
if os.environ.get('BZR_PDB'):
840
print '**** entering debugger'
842
pdb.post_mortem(sys.exc_traceback)
846
def run_bzr_catch_user_errors(argv):
847
"""Run bzr and report user errors, but let internal errors propagate.
849
This is used for the test suite, and might be useful for other programs
850
that want to wrap the commandline interface.
533
# do this here inside the exception wrappers to catch EPIPE
535
except BzrCommandError, e:
536
# command line syntax error, etc
540
bzrlib.trace.log_exception()
542
except AssertionError, e:
543
bzrlib.trace.log_exception('assertion failed: ' + str(e))
545
except KeyboardInterrupt, e:
546
bzrlib.trace.log_exception('interrupted')
854
548
except Exception, e:
855
if (isinstance(e, (OSError, IOError))
856
or not getattr(e, 'internal_error', True)):
857
trace.report_exception(sys.exc_info(), sys.stderr)
863
class HelpCommandIndex(object):
864
"""A index for bzr help that returns commands."""
867
self.prefix = 'commands/'
869
def get_topics(self, topic):
870
"""Search for topic amongst commands.
872
:param topic: A topic to search for.
873
:return: A list which is either empty or contains a single
876
if topic and topic.startswith(self.prefix):
877
topic = topic[len(self.prefix):]
879
cmd = _get_cmd_object(topic)
550
if (isinstance(e, IOError)
551
and hasattr(e, 'errno')
552
and e.errno == errno.EPIPE):
553
bzrlib.trace.note('broken pipe')
558
bzrlib.trace.log_exception()
886
561
if __name__ == '__main__':
887
562
sys.exit(main(sys.argv))
added
removed
bzrlib/commands.py
