def usage(shorthelp=0, writeto_stdout=0, detailed_error=None, exitcode=None):
"""Write __main__'s docstring to stderr with some help text.
Args:
shorthelp: print only flags from this module, rather than all flags.
writeto_stdout: write help message to stdout, rather than to stderr.
detailed_error: additional detail about why usage info was presented.
exitcode: if set, exit with this status code after writing help.
"""
if writeto_stdout:
stdfile = sys.stdout
else:
stdfile = sys.stderr
doc = sys.modules['__main__'].__doc__
if not doc:
doc = '\nUSAGE: %s [flags]\n' % sys.argv[0]
doc = flags.TextWrap(doc, indent=' ', firstline_indent='')
else:
# Replace all '%s' with sys.argv[0], and all '%%' with '%'.
num_specifiers = doc.count('%') - 2 * doc.count('%%')
try:
doc %= (sys.argv[0], ) * num_specifiers
except (OverflowError, TypeError, ValueError):
# Just display the docstring as-is.
pass
if help_text_wrap:
doc = flags.TextWrap(flags.DocToHelp(doc))
if shorthelp:
flag_str = FLAGS.MainModuleHelp()
else:
flag_str = str(FLAGS)
try:
stdfile.write(doc)
if flag_str:
stdfile.write('\nflags:\n')
stdfile.write(flag_str)
stdfile.write('\n')
if detailed_error is not None:
stdfile.write('\n%s\n' % detailed_error)
except IOError as e:
# We avoid printing a huge backtrace if we get EPIPE, because
# "foo.par --help | less" is a frequent use case.
if e.errno != errno.EPIPE:
raise
if exitcode is not None:
sys.exit(exitcode)
def FormatOneCmd(name, command, command_names):
indent_size = appcommands.GetMaxCommandLength() + 3
if len(command_names) > 1:
indent = ' ' * indent_size
command_help = flags.TextWrap(
command.CommandGetHelp('', cmd_names=command_names),
indent=indent,
firstline_indent='')
first_help_line, _, rest = command_help.partition('\n')
first_line = '%-*s%s' % (indent_size, name + ':', first_help_line)
return '\n'.join((first_line, rest))
else:
default_indent = ' '
return '\n' + flags.TextWrap(
command.CommandGetHelp('', cmd_names=command_names),
indent=default_indent,
firstline_indent=default_indent) + '\n'
def main():
args = FLAGS(sys.argv)[1:]
if FLAGS.version:
print('Immaculater CLI Version %s' % __version__)
sys.exit(0)
if FLAGS.help:
doc = sys.modules[_get_username_and_password.__module__].__doc__
help_msg = flags.DocToHelp(doc.replace('%s', sys.argv[0]))
_print(flags.TextWrap(help_msg, flags.GetHelpWidth()))
_print('\n')
_print(FLAGS.GetHelp())
sys.exit(0)
username, password = _get_username_and_password()
if not args:
_repl(username=username, password=password)
sys.exit(0)
if FLAGS.single_command:
args = [u' '.join(pipes.quote(x) for x in args)]
sys.exit(_handle_commands(args, username=username, password=password))
def AppcommandsUsage(shorthelp=0, writeto_stdout=0, detailed_error=None,
exitcode=None, show_cmd=None, show_global_flags=False):
"""Output usage or help information.
Extracts the __doc__ string from the __main__ module and writes it to
stderr. If that string contains a '%s' then that is replaced by the command
pathname. Otherwise a default usage string is being generated.
The output varies depending on the following:
- FLAGS.help
- FLAGS.helpshort
- show_cmd
- show_global_flags
Args:
shorthelp: print only command and main module flags, rather than all.
writeto_stdout: write help message to stdout, rather than to stderr.
detailed_error: additional details about why usage info was presented.
exitcode: if set, exit with this status code after writing help.
show_cmd: show help for this command only (name of command).
show_global_flags: show help for global flags.
"""
if writeto_stdout:
stdfile = sys.stdout
else:
stdfile = sys.stderr
prefix = ''.rjust(GetMaxCommandLength() + 2)
# Deal with header, containing general tool documentation
doc = sys.modules['__main__'].__doc__
if doc:
help_msg = flags.DocToHelp(doc.replace('%s', sys.argv[0]))
stdfile.write(flags.TextWrap(help_msg, flags.GetHelpWidth()))
stdfile.write('\n\n\n')
if not doc or doc.find('%s') == -1:
synopsis = 'USAGE: ' + GetSynopsis()
stdfile.write(flags.TextWrap(synopsis, flags.GetHelpWidth(), ' ',
''))
stdfile.write('\n\n\n')
# Special case just 'help' registered, that means run as 'tool --help'.
if len(GetCommandList()) == 1:
cmd_names = []
else:
# Show list of commands
if show_cmd is None or show_cmd == 'help':
cmd_names = GetCommandList().keys()
cmd_names.sort()
stdfile.write('Any of the following commands:\n')
doc = ', '.join(cmd_names)
stdfile.write(flags.TextWrap(doc, flags.GetHelpWidth(), ' '))
stdfile.write('\n\n\n')
# Prepare list of commands to show help for
if show_cmd is not None:
cmd_names = [show_cmd] # show only one command
elif FLAGS.help or FLAGS.helpshort or shorthelp:
cmd_names = []
else:
cmd_names = GetCommandList().keys() # show all commands
cmd_names.sort()
# Show the command help (none, one specific, or all)
for name in cmd_names:
command = GetCommandByName(name)
try:
cmd_help = command.CommandGetHelp(GetCommandArgv(), cmd_names=cmd_names)
except Exception as error:
cmd_help = "Internal error for command '%s': %s." % (name, str(error))
cmd_help = cmd_help.strip()
all_names = ', '.join([name] + (command.CommandGetAliases() or []))
if len(all_names) + 1 >= len(prefix) or not cmd_help:
# If command/alias list would reach over help block-indent
# start the help block on a new line.
stdfile.write(flags.TextWrap(all_names, flags.GetHelpWidth()))
stdfile.write('\n')
prefix1 = prefix
else:
prefix1 = all_names.ljust(GetMaxCommandLength() + 2)
if cmd_help:
stdfile.write(flags.TextWrap(cmd_help, flags.GetHelpWidth(), prefix,
prefix1))
stdfile.write('\n\n')
else:
stdfile.write('\n')
# When showing help for exactly one command we show its flags
if len(cmd_names) == 1:
# Need to register flags for command prior to be able to use them.
# We do not register them globally so that they do not reappear.
# pylint: disable=protected-access
cmd_flags = command._command_flags
if cmd_flags.RegisteredFlags():
stdfile.write('%sFlags for %s:\n' % (prefix, name))
stdfile.write(cmd_flags.GetHelp(prefix+' '))
stdfile.write('\n\n')
stdfile.write('\n')
# Now show global flags as asked for
if show_global_flags:
stdfile.write('Global flags:\n')
if shorthelp:
stdfile.write(FLAGS.MainModuleHelp())
else:
stdfile.write(FLAGS.GetHelp())
stdfile.write('\n')
else:
stdfile.write("Run '%s --help' to get help for global flags."
% GetAppBasename())
stdfile.write('\n%s\n' % _UsageFooter(detailed_error, cmd_names))
if exitcode is not None:
sys.exit(exitcode)
def testTextWrap(self):
"""Test that wrapping works as expected.
Also tests that it is using global gflags._help_width by default.
"""
default_help_width = _helpers._DEFAULT_HELP_WIDTH
_helpers._DEFAULT_HELP_WIDTH = 10
# Generate a string with length 40, no spaces
text = ''
expect = []
for n in range(4):
line = str(n)
line += '123456789'
text += line
expect.append(line)
# Verify we still break
wrapped = gflags.TextWrap(text).split('\n')
self.assertEqual(4, len(wrapped))
self.assertEqual(expect, wrapped)
wrapped = gflags.TextWrap(text, 80).split('\n')
self.assertEqual(1, len(wrapped))
self.assertEqual([text], wrapped)
# Normal case, breaking at word boundaries and rewriting new lines
input_value = 'a b c d e f g h'
expect = {
1: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'],
2: ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'],
3: ['a b', 'c d', 'e f', 'g h'],
4: ['a b', 'c d', 'e f', 'g h'],
5: ['a b c', 'd e f', 'g h'],
6: ['a b c', 'd e f', 'g h'],
7: ['a b c d', 'e f g h'],
8: ['a b c d', 'e f g h'],
9: ['a b c d e', 'f g h'],
10: ['a b c d e', 'f g h'],
11: ['a b c d e f', 'g h'],
12: ['a b c d e f', 'g h'],
13: ['a b c d e f g', 'h'],
14: ['a b c d e f g', 'h'],
15: ['a b c d e f g h']
}
for width, exp in expect.items():
self.assertEqual(exp,
gflags.TextWrap(input_value, width).split('\n'))
# We turn lines with only whitespace into empty lines
# We strip from the right up to the first new line
self.assertEqual('', gflags.TextWrap(' '))
self.assertEqual('\n', gflags.TextWrap(' \n '))
self.assertEqual('\n', gflags.TextWrap('\n\n'))
self.assertEqual('\n\n', gflags.TextWrap('\n\n\n'))
self.assertEqual('\n', gflags.TextWrap('\n '))
self.assertEqual('a\n\nb', gflags.TextWrap('a\n \nb'))
self.assertEqual('a\n\n\nb', gflags.TextWrap('a\n \n \nb'))
self.assertEqual('a\nb', gflags.TextWrap(' a\nb '))
self.assertEqual('\na\nb', gflags.TextWrap('\na\nb\n'))
self.assertEqual('\na\nb\n', gflags.TextWrap(' \na\nb\n '))
self.assertEqual('\na\nb\n', gflags.TextWrap(' \na\nb\n\n'))
# Double newline.
self.assertEqual('a\n\nb', gflags.TextWrap(' a\n\n b'))
# We respect prefix
self.assertEqual(' a\n b\n c', gflags.TextWrap('a\nb\nc', 80, ' '))
self.assertEqual('a\n b\n c', gflags.TextWrap('a\nb\nc', 80, ' ', ''))
# tabs
self.assertEqual('a\n b c', gflags.TextWrap('a\nb\tc', 80, ' ', ''))
self.assertEqual('a\n bb c', gflags.TextWrap('a\nbb\tc', 80, ' ', ''))
self.assertEqual('a\n bbb c', gflags.TextWrap('a\nbbb\tc', 80, ' ',
''))
self.assertEqual('a\n bbbb c',
gflags.TextWrap('a\nbbbb\tc', 80, ' ', ''))
self.assertEqual('a\n b\n c\n d',
gflags.TextWrap('a\nb\tc\td', 3, ' ', ''))
self.assertEqual('a\n b\n c\n d',
gflags.TextWrap('a\nb\tc\td', 4, ' ', ''))
self.assertEqual('a\n b\n c\n d',
gflags.TextWrap('a\nb\tc\td', 5, ' ', ''))
self.assertEqual('a\n b c\n d',
gflags.TextWrap('a\nb\tc\td', 6, ' ', ''))
self.assertEqual('a\n b c\n d',
gflags.TextWrap('a\nb\tc\td', 7, ' ', ''))
self.assertEqual('a\n b c\n d',
gflags.TextWrap('a\nb\tc\td', 8, ' ', ''))
self.assertEqual('a\n b c\n d',
gflags.TextWrap('a\nb\tc\td', 9, ' ', ''))
self.assertEqual('a\n b c d',
gflags.TextWrap('a\nb\tc\td', 10, ' ', ''))
# multiple tabs
self.assertEqual('a c', gflags.TextWrap('a\t\tc', 80, ' ', ''))
_helpers._DEFAULT_HELP_WIDTH = default_help_width # restore
