357
346
summary, then a complete description of the command. A grammar
358
347
description will be inserted.
361
Other accepted names for this command.
364
List of argument forms, marked with whether they are optional,
369
['to_location', 'from_branch?', 'file*']
371
'to_location' is required
372
'from_branch' is optional
373
'file' can be specified 0 or more times
376
List of options that may be given for this command. These can
377
be either strings, referring to globally-defined options,
378
or option objects. Retrieve through options().
381
If true, this command isn't advertised. This is typically
349
:cvar aliases: Other accepted names for this command.
351
:cvar takes_args: List of argument forms, marked with whether they are
352
optional, repeated, etc. Examples::
354
['to_location', 'from_branch?', 'file*']
356
* 'to_location' is required
357
* 'from_branch' is optional
358
* 'file' can be specified 0 or more times
360
:cvar takes_options: List of options that may be given for this command.
361
These can be either strings, referring to globally-defined options, or
362
option objects. Retrieve through options().
364
:cvar hidden: If true, this command isn't advertised. This is typically
382
365
for commands intended for expert users.
385
Command objects will get a 'outf' attribute, which has been
386
setup to properly handle encoding of unicode strings.
387
encoding_type determines what will happen when characters cannot
389
strict - abort if we cannot decode
390
replace - put in a bogus character (typically '?')
391
exact - do not encode sys.stdout
393
NOTE: by default on Windows, sys.stdout is opened as a text
394
stream, therefore LF line-endings are converted to CRLF.
395
When a command uses encoding_type = 'exact', then
396
sys.stdout is forced to be a binary stream, and line-endings
367
:cvar encoding_type: Command objects will get a 'outf' attribute, which has
368
been setup to properly handle encoding of unicode strings.
369
encoding_type determines what will happen when characters cannot be
372
* strict - abort if we cannot decode
373
* replace - put in a bogus character (typically '?')
374
* exact - do not encode sys.stdout
376
NOTE: by default on Windows, sys.stdout is opened as a text stream,
377
therefore LF line-endings are converted to CRLF. When a command uses
378
encoding_type = 'exact', then sys.stdout is forced to be a binary
379
stream, and line-endings will not mangled.
400
382
A string indicating the real name under which this command was
401
invoked, before expansion of aliases.
383
invoked, before expansion of aliases.
402
384
(This may be None if the command was constructed and run in-process.)
404
386
:cvar hooks: An instance of CommandHooks.
406
:ivar __doc__: The help shown by 'bzr help command' for this command.
388
:cvar __doc__: The help shown by 'bzr help command' for this command.
407
389
This is set by assigning explicitly to __doc__ so that -OO can
411
__doc__ = "My help goes here"
393
__doc__ = "My help goes here"
415
397
takes_options = []
416
398
encoding_type = 'strict'
417
399
invoked_as = None
492
462
usage help (e.g. Purpose, Usage, Options) with a
493
463
message explaining how to obtain full help.
466
i18n.install() # Install i18n only for get_help_text for now.
495
467
doc = self.help()
497
doc = "No help for this command."
469
# Note: If self.gettext() translates ':Usage:\n', the section will
470
# be shown after "Description" section and we don't want to
471
# translate the usage string.
472
# Though, bzr export-pot don't exports :Usage: section and it must
474
doc = self.gettext(doc)
476
doc = gettext("No help for this command.")
499
478
# Extract the summary (purpose) and sections out from the text
500
479
purpose,sections,order = self._get_help_parts(doc)
519
498
# XXX: optparse implicitly rewraps the help, and not always perfectly,
520
499
# so we get <https://bugs.launchpad.net/bzr/+bug/249908>. -- mbp
522
options = option.get_optparser(self.options()).format_option_help()
523
# XXX: According to the spec, ReST option lists actually don't support
524
# options like --1.9 so that causes syntax errors (in Sphinx at least).
525
# As that pattern always appears in the commands that break, we trap
526
# on that and then format that block of 'format' options as a literal
528
if not plain and options.find(' --1.9 ') != -1:
501
parser = option.get_optparser(self.options())
502
options = parser.format_option_help()
503
# FIXME: According to the spec, ReST option lists actually don't
504
# support options like --1.14 so that causes syntax errors (in Sphinx
505
# at least). As that pattern always appears in the commands that
506
# break, we trap on that and then format that block of 'format' options
507
# as a literal block. We use the most recent format still listed so we
508
# don't have to do that too often -- vila 20110514
509
if not plain and options.find(' --1.14 ') != -1:
529
510
options = options.replace(' format:\n', ' format::\n\n', 1)
530
511
if options.startswith('Options:'):
531
result += ':' + options
532
elif options.startswith('options:'):
533
# Python 2.4 version of optparse
534
result += ':Options:' + options[len('options:'):]
512
result += gettext(':Options:%s') % (options[len('options:'):],)
536
514
result += options
542
520
if sections.has_key(None):
543
521
text = sections.pop(None)
544
522
text = '\n '.join(text.splitlines())
545
result += ':%s:\n %s\n\n' % ('Description',text)
523
result += gettext(':Description:\n %s\n\n') % (text,)
547
525
# Add the custom sections (e.g. Examples). Note that there's no need
548
526
# to indent these as they must be indented already in the source.
550
528
for label in order:
551
if sections.has_key(label):
552
result += ':%s:\n%s\n' % (label,sections[label])
529
if label in sections:
530
result += ':%s:\n%s\n' % (label, sections[label])
555
result += ("See bzr help %s for more details and examples.\n\n"
533
result += (gettext("See bzr help %s for more details and examples.\n\n")
558
536
# Add the aliases, source (plug-in) and see also links, if any
560
result += ':Aliases: '
538
result += gettext(':Aliases: ')
561
539
result += ', '.join(self.aliases) + '\n'
562
540
plugin_name = self.plugin_name()
563
541
if plugin_name is not None:
564
result += ':From: plugin "%s"\n' % plugin_name
542
result += gettext(':From: plugin "%s"\n') % plugin_name
565
543
see_also = self.get_see_also(additional_see_also)
567
545
if not plain and see_also_as_links:
573
551
see_also_links.append(item)
575
553
# Use a Sphinx link for this entry
576
link_text = ":doc:`%s <%s-help>`" % (item, item)
554
link_text = gettext(":doc:`{0} <{1}-help>`").format(
577
556
see_also_links.append(link_text)
578
557
see_also = see_also_links
579
result += ':See also: '
580
result += ', '.join(see_also) + '\n'
558
result += gettext(':See also: %s') % ', '.join(see_also) + '\n'
582
560
# If this will be rendered as plain text, convert it
664
642
def run_argv_aliases(self, argv, alias_argv=None):
665
643
"""Parse the command line and run with extra aliases in alias_argv."""
666
644
args, opts = parse_args(self, argv, alias_argv)
668
647
# Process the standard options
669
648
if 'help' in opts: # e.g. bzr add --help
670
sys.stdout.write(self.get_help_text())
649
self.outf.write(self.get_help_text())
672
651
if 'usage' in opts: # e.g. bzr add --usage
673
sys.stdout.write(self.get_help_text(verbose=False))
652
self.outf.write(self.get_help_text(verbose=False))
675
654
trace.set_verbosity_level(option._verbosity_level)
676
655
if 'verbose' in self.supported_std_options:
715
691
class_run = self.run
716
692
def run(*args, **kwargs):
693
for hook in Command.hooks['pre_command']:
717
695
self._operation = cleanup.OperationWithCleanups(class_run)
719
697
return self._operation.run_simple(*args, **kwargs)
721
699
del self._operation
700
for hook in Command.hooks['post_command']:
724
@deprecated_method(deprecated_in((2, 2, 0)))
725
def run_direct(self, *args, **kwargs):
726
"""Deprecated thunk from bzrlib 2.1."""
727
return self.run(*args, **kwargs)
730
705
"""Actually run the command.
857
847
argdict[argname + '_list'] = None
858
848
elif ap[-1] == '+':
860
raise errors.BzrCommandError("command %r needs one or more %s"
861
% (cmd, argname.upper()))
850
raise errors.BzrCommandError(gettext(
851
"command {0!r} needs one or more {1}").format(
852
cmd, argname.upper()))
863
854
argdict[argname + '_list'] = args[:]
865
856
elif ap[-1] == '$': # all but one
866
857
if len(args) < 2:
867
raise errors.BzrCommandError("command %r needs one or more %s"
868
% (cmd, argname.upper()))
858
raise errors.BzrCommandError(
859
gettext("command {0!r} needs one or more {1}").format(
860
cmd, argname.upper()))
869
861
argdict[argname + '_list'] = args[:-1]
872
864
# just a plain arg
875
raise errors.BzrCommandError("command %r requires argument %s"
876
% (cmd, argname.upper()))
867
raise errors.BzrCommandError(
868
gettext("command {0!r} requires argument {1}").format(
869
cmd, argname.upper()))
878
871
argdict[argname] = args.pop(0)
881
raise errors.BzrCommandError("extra argument to command %s: %s"
874
raise errors.BzrCommandError( gettext(
875
"extra argument to command {0}: {1}").format(
941
935
exitcode = trace.report_exception(exc_info, sys.stderr)
942
936
if os.environ.get('BZR_PDB'):
943
937
print '**** entering debugger'
946
if sys.version_info[:2] < (2, 6):
948
# pdb.post_mortem(tb)
949
# but because pdb.post_mortem gives bad results for tracebacks
950
# from inside generators, we do it manually.
951
# (http://bugs.python.org/issue4150, fixed in Python 2.6)
953
# Setup pdb on the traceback
956
p.setup(tb.tb_frame, tb)
957
# Point the debugger at the deepest frame of the stack
958
p.curindex = len(p.stack) - 1
959
p.curframe = p.stack[p.curindex][0]
960
# Start the pdb prompt.
961
p.print_stack_entry(p.stack[p.curindex])
939
pdb.post_mortem(exc_info[2])
969
943
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
970
944
from bzrlib.lsprof import profile
971
ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
945
ret, stats = profile(exception_to_return_code, the_callable,
973
948
if filename is None:
976
951
stats.save(filename)
977
trace.note('Profile data written to "%s".', filename)
952
trace.note(gettext('Profile data written to "%s".'), filename)
981
@deprecated_function(deprecated_in((2, 2, 0)))
982
def shlex_split_unicode(unsplit):
983
return cmdline.split(unsplit)
986
956
def get_alias(cmd, config=None):
987
957
"""Return an expanded alias, or None if no alias exists.
1276
1264
class Provider(object):
1277
'''Generic class to be overriden by plugins'''
1265
"""Generic class to be overriden by plugins"""
1279
1267
def plugin_for_command(self, cmd_name):
1280
'''Takes a command and returns the information for that plugin
1268
"""Takes a command and returns the information for that plugin
1282
1270
:return: A dictionary with all the available information
1283
for the requested plugin
1271
for the requested plugin
1285
1273
raise NotImplementedError
1288
1276
class ProvidersRegistry(registry.Registry):
1289
'''This registry exists to allow other providers to exist'''
1277
"""This registry exists to allow other providers to exist"""
1291
1279
def __iter__(self):
1292
1280
for key, provider in self.iteritems():
added
removed
bzrlib/commands.py
