Qc
@ s d Z d d k Z d d k Z d d k Z d d k Z d d k l Z d d k Z e i Z d e
f d YZ d a
h a h a d Z d d Z d Z d Z d
Z d Z d Z d
Z d e f d YZ d e f d YZ d d Z d Z d Z d d d Z d e f d YZ d Z d Z! d d d d d e" d Z# d Z$ d Z% d Z& d Z' e d e d d d d d! Z( e) d" j o e' n d S(# st This module is the base for programs that provide multiple commands.
This provides command line tools that have a few shared global flags,
followed by a command name, followed by command specific flags,
then by arguments. That is:
tool [--global_flags] command [--command_flags] [args]
The module is built on top of app.py and 'overrides' a bit of it. However
the interface is mostly the same. The main difference is that your main
is supposed to register commands and return without further execution
of the commands; pre checking is of course welcome! Also your
global initialization should call appcommands.Run() rather than app.run().
To register commands use AddCmd() or AddCmdFunc(). AddCmd() is used
for commands that derive from class Cmd and the AddCmdFunc() is used
to wrap simple functions.
This module itself registers the command 'help' that allows users
to retrieve help for all or specific commands.
Example:
from mx import DateTime
class CmdDate(appcommands.Cmd):
"""This docstring contains the help for the date command."""
def Run(self, argv):
print DateTime.now()
def main(argv):
appcommands.AddCmd('date', CmdDate, command_aliases=['data_now'])
if __name__ == '__main__':
appcommands.Run()
In the above example the name of the registered command on the command line is
'date'. Thus, to get the date you would execute:
tool date
The above example also added the command alias 'data_now' which allows to
replace 'tool date' with 'tool data_now'.
To get a list of available commands run:
tool help
For help with a specific command, you would execute:
tool help date
For help on flags run one of the following:
tool --help
Note that 'tool --help' gives you information on global flags, just like for
applications that do not use appcommand. Likewise 'tool --helpshort' and the
other help-flags from app.py are also available.
The above example also demonstrates that you only have to call
appcommands.Run()
and register your commands in main() to initialize your program with appcommands
(and app).
Handling of flags:
Flags can be registered just as with any other google tool using flags.py.
In addition you can also provide command specific flags. To do so simply add
flags registering code into the __init__ function of your Cmd classes passing
parameter flag_values to any flags registering calls. These flags will get
copied to the global flag list, so that once the command is detected they
behave just like any other flag. That means these flags won't be available
for other commands. Note that it is possible to register flags with more
than one command.
Getting help:
This module activates formatting and wrapping to help output. That is
the main difference to help created from app.py. So just as with app.py,
appcommands.py will create help from the main modules main __doc__.
But it adds the new 'help' command that allows you to get a list of
all available commands. Each command's help will be followed by the
registered command specific flags along with their defaults and help.
After help for all commands there will also be a list of all registered
global flags with their defaults and help.
The text for the command's help can best be supplied by overwriting the
__doc__ property of the Cmd classes for commands registered with AddCmd() or
the __doc__ property of command functions registered AddCmdFunc().
Inner working:
This module interacts with app.py by replacing its inner start dispatcher.
The replacement version basically does the same, registering help flags,
checking whether help flags were present, and calling the main module's main
function. However unlike app.py, this module epxpects main() to only register
commands and then to return. After having all commands registered
appcommands.py will then parse the remaining arguments for any registered
command. If one is found it will get executed. Otherwise a short usage info
will be displayed.
Each provided command must be an instance of Cmd. If commands get registered
from global functions using AddCmdFunc() then the helper class _FunctionalCmd
will be used in the registering process.
iN( t appt AppCommandsErrorc B s e Z d Z RS( s$ The base class for all flags errors.( t __name__t
__module__t __doc__( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyR s c C s t i i t i d S( s2 Returns the friendly basename of this application.i ( t ost patht basenamet syst argv( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt GetAppBasename s c C sZ t i i | d j o t i i d | n t i i d t t i d d S( s Display optional message, followed by a note on how to get help, then exit.
Args:
message: optional message to display
s %s
s Run '%s help' to get help
i N( R t stdoutt flusht Nonet stderrt writeR
t exit( t message( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt ShortHelpAndExit s
c C s t S( s# Return list of registered commands.( t _cmd_list( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt GetCommandList s c C s t S( s* Return list of registered command aliases.( t _cmd_alias_list( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt GetCommandAliasList s c C sF t t } x0 t i D] \ } } | i | | | ]
To retrieve help with global flags:
%(prog)s --help
To retrieve help with flags only from the main module:
%(prog)s --helpshort []
t prog( R
RM RN ( R, RO RP t cmd_help( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyRQ s N( R R R R0 R
RQ ( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyRh s c C s d t S( sQ Get synopsis for program.
Returns:
Synopsis including program basename.
s6 %s [--global_flags] [--command_flags] [args]( R
( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt GetSynopsis$ s c C s g } | p t | d j o | i d t n | p t | t t j o | i d t n | d j o- | o | i d n | i d | n d i | S( s$ Output a footer at the end of usage or help output.
Args:
detailed_error: additional detail about why usage info was presented.
cmd_names: list of command names for which help was shown or None.
Returns:
Generated footer that contains 'Run..' messages if appropriate.
i s4 Run '%s help' to see the list of available commands.s2 Run '%s help ' to get help for .t s %ss
N( R# t appendR
R R
t join( R8 RP t footer( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt _UsageFooter. s $
i c C s8 | o
t i } n
t i } d i t d } t i d i } | oR t i | i d t i
d } | i t i | t i
| i d n | p | i d d j oC d t }
| i t i |
t i
d d | i d n t t d
j o
g } n | d j p
| d j oh t i } | i | i d d
i | } | i t i | t i
d | i d n | d j o
| g } n? t i p t i p | o
g } n t i } | i x| D]} t | }
|
i t d | } | i } d
i | g |
i p g } t | d
t | j p | o6 | i t i | t i
| i d | } n | i t d } | o6 | i t i | t i
| | | i d n | i d t | d
j o\ |
i } | i oB | i d | | f | i | i! | d | i d qqqW| i d | oO | i d | o | i t i" n | i t i! | i d n | i d t# | i d t$ | | | d j o t i% | n d S( s$ 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.
Rm i t __main__s %si s
is USAGE: s i t helps Any of the following commands:
s , s RP s
s
s %sFlags for %s:
s Global flags:
s- Run '%s --help' to get help for global flags.s
%s
N(& R R R t rjustR% t modulesR RM RN t replaceR R t TextWrapt GetHelpWidtht findRl R# R R
t keyst sortRo R: Rs t helpshortR RQ R! t stripRR t ljustR) t RegisteredFlagst GetHelpt MainModuleHelpR
Rq R ( R6 R7 R8 R1 R2 R3 t stdfilet prefixt doct help_msgt synopsisRP R t commandRk t all_namest prefix1t cmd_flags( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyR4 E s~
"
"
#%
c C sA y t | a t SWn& t i j
o } t d | n Xd S( s Parse the flags, exiting (after printing usage) if they are unparseable.
Args:
argv: command line arguments
Returns:
remaining command line arguments after parsing flags
s FATAL Flags parsing error: %sN( R: R RM t
FlagsErrorR ( R RI ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyR= s
c C sw t t a t t d j o | o t d n d St t d } | d j o t d t d n t d =| S( sp Get the command or return None (or issue an error) if there is none.
Args:
command_required: whether to issue an error if no command is present
Returns:
command or None, if command_required is True then return value is a valid
command or the program will exit. The program also exits if a command was
specified but that command does not exist.
i s% FATAL Command expected but none giveni s FATAL Command '%s' unknownN( R= R R# R R
R ( t command_requiredR ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt
GetCommand s
c C s t i y t i d i t WnQ t j
o } t i | i n. t j
o! } t
i t d | n Xt
t d j o t d t } n
t d } t i | i t d S( s Main initialization.
This initializes flag values, and calls __main__.main(). Only non-flag
arguments are passed to main(). The return value of main() is used as the
exit status.
Rr s
FATAL error in main: %si R Rs N( R t RegisterAndParseFlagsWithUsageR Ru t mainR! t
SystemExitR t codet Exceptiont tracebackt print_excR R# R R5 R RK ( t eRI R ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt _CommandsStart s
c C s% t t _ t t _ t t _ t i S( s This must be called from __main__ modules main, instead of app.run().
app.run will base its actions on its stacktrace.
Returns:
app.run()
( R= R t parse_flags_with_usageR t really_startt _ReplacementAppUsageR< t run( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyR0 s Rs c
C s& t | | | d | d d d t d S( NR1 R2 R3 ( R4 R
R5 ( R6 R7 R8 R1 ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyR s Rr (* R R R? R R t google.apputilsR t gflagsRM R: R R R
R R R R
R R R R R R! R% t objectR& RS R] RZ Rf Rg Rh Rl Rq Ri R4 R= R R R0 R R ( ( ( sc /Users/riccardo/git/gcloud/packages/gcutil-1.7.1/lib/google_apputils/google/apputils/appcommands.pyt s sP
> 2
i