359
357
summary, then a complete description of the command. A grammar
360
358
description will be inserted.
362
:cvar aliases: Other accepted names for this command.
364
:cvar takes_args: List of argument forms, marked with whether they are
365
optional, repeated, etc. Examples::
367
['to_location', 'from_branch?', 'file*']
369
* 'to_location' is required
370
* 'from_branch' is optional
371
* 'file' can be specified 0 or more times
373
:cvar takes_options: List of options that may be given for this command.
374
These can be either strings, referring to globally-defined options, or
375
option objects. Retrieve through options().
377
:cvar hidden: If true, this command isn't advertised. This is typically
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
378
382
for commands intended for expert users.
380
:cvar encoding_type: Command objects will get a 'outf' attribute, which has
381
been setup to properly handle encoding of unicode strings.
382
encoding_type determines what will happen when characters cannot be
385
* strict - abort if we cannot decode
386
* replace - put in a bogus character (typically '?')
387
* exact - do not encode sys.stdout
389
NOTE: by default on Windows, sys.stdout is opened as a text stream,
390
therefore LF line-endings are converted to CRLF. When a command uses
391
encoding_type = 'exact', then sys.stdout is forced to be a binary
392
stream, and line-endings will not mangled.
395
A string indicating the real name under which this command was
396
invoked, before expansion of aliases.
397
(This may be None if the command was constructed and run in-process.)
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
399
399
:cvar hooks: An instance of CommandHooks.
401
:cvar __doc__: The help shown by 'bzr help command' for this command.
400
:ivar __doc__: The help shown by 'bzr help command' for this command.
402
401
This is set by assigning explicitly to __doc__ so that -OO can
406
__doc__ = "My help goes here"
405
__doc__ = "My help goes here"
410
409
takes_options = []
411
410
encoding_type = 'strict'
488
485
usage help (e.g. Purpose, Usage, Options) with a
489
486
message explaining how to obtain full help.
491
if self.l10n and not i18n.installed():
492
i18n.install() # Install i18n only for get_help_text for now.
493
488
doc = self.help()
495
# Note: If self.gettext() translates ':Usage:\n', the section will
496
# be shown after "Description" section and we don't want to
497
# translate the usage string.
498
# Though, bzr export-pot don't exports :Usage: section and it must
500
doc = self.gettext(doc)
502
doc = gettext("No help for this command.")
490
doc = "No help for this command."
504
492
# Extract the summary (purpose) and sections out from the text
505
493
purpose,sections,order = self._get_help_parts(doc)
524
512
# XXX: optparse implicitly rewraps the help, and not always perfectly,
525
513
# so we get <https://bugs.launchpad.net/bzr/+bug/249908>. -- mbp
527
parser = option.get_optparser(self.options())
528
options = parser.format_option_help()
529
# FIXME: According to the spec, ReST option lists actually don't
530
# support options like --1.14 so that causes syntax errors (in Sphinx
531
# at least). As that pattern always appears in the commands that
532
# break, we trap on that and then format that block of 'format' options
533
# as a literal block. We use the most recent format still listed so we
534
# don't have to do that too often -- vila 20110514
535
if not plain and options.find(' --1.14 ') != -1:
515
options = option.get_optparser(self.options()).format_option_help()
516
# XXX: According to the spec, ReST option lists actually don't support
517
# options like --1.9 so that causes syntax errors (in Sphinx at least).
518
# As that pattern always appears in the commands that break, we trap
519
# on that and then format that block of 'format' options as a literal
521
if not plain and options.find(' --1.9 ') != -1:
536
522
options = options.replace(' format:\n', ' format::\n\n', 1)
537
523
if options.startswith('Options:'):
538
result += gettext(':Options:%s') % (options[len('options:'):],)
524
result += ':' + options
525
elif options.startswith('options:'):
526
# Python 2.4 version of optparse
527
result += ':Options:' + options[len('options:'):]
540
529
result += options
546
535
if sections.has_key(None):
547
536
text = sections.pop(None)
548
537
text = '\n '.join(text.splitlines())
549
result += gettext(':Description:\n %s\n\n') % (text,)
538
result += ':%s:\n %s\n\n' % ('Description',text)
551
540
# Add the custom sections (e.g. Examples). Note that there's no need
552
541
# to indent these as they must be indented already in the source.
554
543
for label in order:
555
if label in sections:
556
result += ':%s:\n%s\n' % (label, sections[label])
544
if sections.has_key(label):
545
result += ':%s:\n%s\n' % (label,sections[label])
559
result += (gettext("See bzr help %s for more details and examples.\n\n")
548
result += ("See bzr help %s for more details and examples.\n\n"
562
551
# Add the aliases, source (plug-in) and see also links, if any
564
result += gettext(':Aliases: ')
553
result += ':Aliases: '
565
554
result += ', '.join(self.aliases) + '\n'
566
555
plugin_name = self.plugin_name()
567
556
if plugin_name is not None:
568
result += gettext(':From: plugin "%s"\n') % plugin_name
557
result += ':From: plugin "%s"\n' % plugin_name
569
558
see_also = self.get_see_also(additional_see_also)
571
560
if not plain and see_also_as_links:
577
566
see_also_links.append(item)
579
568
# Use a Sphinx link for this entry
580
link_text = gettext(":doc:`%s <%s-help>`") % (item, item)
569
link_text = ":doc:`%s <%s-help>`" % (item, item)
581
570
see_also_links.append(link_text)
582
571
see_also = see_also_links
583
result += gettext(':See also: %s') % ', '.join(see_also) + '\n'
572
result += ':See also: '
573
result += ', '.join(see_also) + '\n'
585
575
# If this will be rendered as plain text, convert it
667
657
def run_argv_aliases(self, argv, alias_argv=None):
668
658
"""Parse the command line and run with extra aliases in alias_argv."""
669
659
args, opts = parse_args(self, argv, alias_argv)
672
661
# Process the standard options
673
662
if 'help' in opts: # e.g. bzr add --help
674
self.outf.write(self.get_help_text())
663
sys.stdout.write(self.get_help_text())
676
665
if 'usage' in opts: # e.g. bzr add --usage
677
self.outf.write(self.get_help_text(verbose=False))
666
sys.stdout.write(self.get_help_text(verbose=False))
679
668
trace.set_verbosity_level(option._verbosity_level)
680
669
if 'verbose' in self.supported_std_options:
695
684
all_cmd_args = cmdargs.copy()
696
685
all_cmd_args.update(cmdopts)
699
return self.run(**all_cmd_args)
701
# reset it, so that other commands run in the same process won't
702
# inherit state. Before we reset it, log any activity, so that it
703
# gets properly tracked.
704
ui.ui_factory.log_transport_activity(
705
display=('bytes' in debug.debug_flags))
706
trace.set_verbosity_level(0)
689
return self.run(**all_cmd_args)
708
691
def _setup_run(self):
709
692
"""Wrap the defined run method on self with a cleanup.
795
766
These are all empty initially, because by default nothing should get
798
Hooks.__init__(self, "bzrlib.commands", "Command.hooks")
799
self.add_hook('extend_command',
770
self.create_hook(HookPoint('extend_command',
800
771
"Called after creating a command object to allow modifications "
801
772
"such as adding or removing options, docs etc. Called with the "
802
"new bzrlib.commands.Command object.", (1, 13))
803
self.add_hook('get_command',
773
"new bzrlib.commands.Command object.", (1, 13), None))
774
self.create_hook(HookPoint('get_command',
804
775
"Called when creating a single command. Called with "
805
776
"(cmd_or_None, command_name). get_command should either return "
806
777
"the cmd_or_None parameter, or a replacement Command object that "
807
778
"should be used for the command. Note that the Command.hooks "
808
779
"hooks are core infrastructure. Many users will prefer to use "
809
780
"bzrlib.commands.register_command or plugin_cmds.register_lazy.",
811
self.add_hook('get_missing_command',
782
self.create_hook(HookPoint('get_missing_command',
812
783
"Called when creating a single command if no command could be "
813
784
"found. Called with (command_name). get_missing_command should "
814
785
"either return None, or a Command object to be used for the "
816
self.add_hook('list_commands',
786
"command.", (1, 17), None))
787
self.create_hook(HookPoint('list_commands',
817
788
"Called when enumerating commands. Called with a set of "
818
789
"cmd_name strings for all the commands found so far. This set "
819
790
" is safe to mutate - e.g. to remove a command. "
820
791
"list_commands should return the updated set of command names.",
823
794
Command.hooks = CommandHooks()
841
# for python 2.5 and later, optparse raises this exception if a non-ascii
842
# option name is given. See http://bugs.python.org/issue2931
844
options, args = parser.parse_args(args)
845
except UnicodeEncodeError,e:
846
raise errors.BzrCommandError('Only ASCII permitted in option names')
812
options, args = parser.parse_args(args)
848
813
opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
849
814
v is not option.OptionParser.DEFAULT_VALUE])
850
815
return args, opts
1290
1252
class Provider(object):
1291
"""Generic class to be overriden by plugins"""
1253
'''Generic class to be overriden by plugins'''
1293
1255
def plugin_for_command(self, cmd_name):
1294
"""Takes a command and returns the information for that plugin
1256
'''Takes a command and returns the information for that plugin
1296
1258
:return: A dictionary with all the available information
1297
for the requested plugin
1259
for the requested plugin
1299
1261
raise NotImplementedError
1302
1264
class ProvidersRegistry(registry.Registry):
1303
"""This registry exists to allow other providers to exist"""
1265
'''This registry exists to allow other providers to exist'''
1305
1267
def __iter__(self):
1306
1268
for key, provider in self.iteritems():
added
removed
bzrlib/commands.py
