n ~ S r SSKrSSKrSSKrSSKrSSKJr SSKr\R r " S S\
5 r Sq 0 q
0 qS rS"S jrS rS rS
rS rS rS
r " S S\5 r " S S\5 rS"S jrS rS r S#S jr " S S\5 r S r S r S$S jr!S r"S r#S r$S r%\ " S \ 5 S%S jr&\'S!:X a \%" 5 gg)&at 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.
N)appc \ rS rSrSrSrg)AppCommandsError z$The base class for all flags errors. N)__name__
__module__ __qualname____firstlineno____doc____static_attributes__r 6platform/bq/third_party/google/apputils/appcommands.pyr r s ,r r c [ R R [ R S 5 R S5 n U S $ )z2Returns the friendly basename of this application.r .)ospathbasenamesysargvsplit)bases r GetAppBasenamer s2 #((1+ & , ,S 1$
a.r c
[ R R 5 U b" [ R R SU - 5 [ R R S[ 5 - 5 [ R " S5 g)zzDisplay optional message, followed by a note on how to get help, then exit.
Args:
message: optional message to display
Nz%s
zRun '%s help' to get help
)r stdoutflushstderrwriter exit)messages r ShortHelpAndExitr" sW ** JJVg%&**0>3CCD((1+r c [ $ )z#Return list of registered commands.) _cmd_listr r r GetCommandListr% s
r c [ $ )z*Return list of registered command aliases.)_cmd_alias_listr r r GetCommandAliasListr( s
r c [ [ 5 5 n [ 5 R 5 H u pU R U5 X' M U $ )z6Return list of registered commands, including aliases.)dictr% r( iteritemsget)all_cmds cmd_aliascmd_names r GetFullCommandListr0 s>
."
#( 0 2 < < >i",,x0H ? /r c b [ 5 R [ 5 R U 5 5 $ )zGet the command or None if name is not a registered command.
Args:
name: name of command to look for
Returns:
Cmd instance holding the command or None
)r% r, r( )names r GetCommandByNamer3 s'
1 3 7 7 = >>r c [ $ )z Return list of remaining args.) _cmd_argvr r r GetCommandArgvr6 s r c f [ [ 5 V s/ s H n [ U 5 PM sn 5 $ s sn f )z5Returns the length of the longest registered command.)maxr% len)r/ s r GetMaxCommandLengthr: s( N,<
=,<c(m,<
= >>
=s .c > \ rS rSrSrS
S jrS rS rS
S jrS r S r
g) Cmd aG Abstract class describing and implementing a command.
When creating code for a command, at least you have to derive this class
and override method Run(). The other methods of this class might be
overridden as well. Check their documentation for details. If the command
needs any specific flags, use __init__ for registration.
Nc p Xl X0l X l SU l [ U 5 [
L a [
S5 eg)a- Initialize and check whether self is actually a Cmd instance.
This can be used to register command specific flags. If you do so
remember that you have to provide the 'flag_values=flag_values'
parameter to any flags.DEFINE_*() call.
Args:
name: Name of the command
flag_values: FlagValues() instance that needs to be passed as
flag_values parameter to any flags registering call.
command_aliases: A list of command aliases that the command can be run as.
Raises:
AppCommandsError: if self is Cmd (Cmd is abstract)
Nz*Cmd is abstract and cannot be instantiated)
_command_name_command_aliases_command_flags_all_commands_helptyper< r )selfr2 flag_valuescommand_aliasess r __init__ Cmd.__init__ s; +% "D DzS I JJ r c t [ [ U 5 R < S[ U 5 R < S35 e)a Execute the command. Must be provided by the implementing class.
Args:
argv: Remaining command line arguments after parsing flags and command
(that is a copy of sys.argv at the time of the function call with
all parsed flags removed).
Returns:
0 for success, anything else for failure (must return with integer).
Alternatively you may return None (or not use a return statement at all).
Raises:
AppCommandsError: Always as in must be overwritten
r z.Run() is not implemented)r rC r r rD r s r RunCmd.Run s/ T
tDz 2 2 4 5 5r c j ^ [ R T R 5 [ R n SU 4S jjnU[ l [ U5 n[ R ( a" [ R " T R U5 nOT R U5 nUc SnO[ U[ 5 ( d eUU[ l T R R 5 H n[ [ U5 M $ ! [ R a) n[ R " SXfR S9 SnAOSnAff = f U[ l T R R 5 H n[ [ U5 M g! U[ l T R R 5 H n[ [ U5 M f = f)aK Execute the command with given arguments.
First register and parse additional flags. Then run the command.
Returns:
Command return value.
Args:
argv: Remaining command line arguments after parsing command and flags
(that is a copy of sys.argv at the time of the function call with
all parsed flags removed).
r r Nc 4 > [ XUSTR SS9 g )Nr Texitcodeshow_cmdshow_global_flags)AppcommandsUsager? ) shorthelpwriteto_stdoutdetailed_errorrP rD s r ReplacementAppUsage+Cmd.CommandRun..ReplacementAppUsage s y.1 $ 2 2dLr )rT rV rP )r r NN)FLAGSAppendFlagValuesrA r usageParseFlagsWithUsage run_with_pdbpdbruncallrK
isinstanceintFlagDictdelattr
UsageErrorrP )rD r orig_app_usagerW ret flag_nameerrors ` r
CommandRunCmd.CommandRun sI
4../YYNJN%)L $CI"
N"4( DHHd+## ;#C%%
%%
!ci**335)y! 6 ^^ N AennMNM !ci**335)y! 6 !ci**335)y! 6s+ A1C6 6D3
D.)E4 .D33E4 4>F2c [ U5 [ L a< [ U5 S: a- U R b [ R
" U R 5 $ U R ( a [ R
" U R 5 $ g)a Get help string for command.
Args:
unused_argv: Remaining command line flags and arguments after parsing
command (that is a copy of sys.argv at the time of the
function call with all parsed flags removed); unused in this
default implementation, but may be used in subclasses.
cmd_names: Complete list of commands for which help is being shown at
the same time. This is used to determine whether to return
_all_commands_help, or the command's docstring.
(_all_commands_help is used, if not None, when help is being
shown for more than one command, otherwise the command's
docstring is used.)
Returns:
Help string, one of the following (by order):
- Result of the registered 'help' function (if any)
- Doc string of the Cmd class (if any)
- Default fallback string
r No help available)rC listr9 rB flags DocToHelpr rD unused_argv cmd_namess r CommandGetHelpCmd.CommandGetHelp* sY *
Y4 C NQ$6 +
__T 4 4
55
__T\\
**
r c U R $ )zOGet aliases for command.
Returns:
aliases: list of aliases for the command.
)r@ )rD s r CommandGetAliasesCmd.CommandGetAliasesG s r )rB r@ rA r? N) r r r
r r rG rK ri rs rv r
r r r r< r< s" K,5$+"Z!:!r r< c 2 \ rS rSrSrSS jrSS jrS rSrg) _FunctionalCmdiP zPClass to wrap functions as CMD instances.
Args:
cmd_func: command function
Nc L [ R " XU40 UD6 X@l X0l g)a Create a functional command.
Args:
name: Name of command
flag_values: FlagValues() instance that needs to be passed as flag_values
parameter to any flags registering call.
cmd_func: Function to call when command is to be executed.
N)r< rG rB _cmd_func)rD r2 rE cmd_funcall_commands_helpkargss r rG _FunctionalCmd.__init__W s" LL[2E2 / Nr c " [ U5 [ L a< [ U5 S: a- U R b [ R
" U R 5 $ U R R b* [ R
" U R R 5 $ g)a Get help for command.
Args:
unused_argv: Remaining command line flags and arguments after parsing
command (that is a copy of sys.argv at the time of the
function call with all parsed flags removed); unused in this
implementation.
cmd_names: By default, if help is being shown for more than one command,
and this command defines _all_commands_help, then
_all_commands_help will be displayed instead of the class
doc. cmd_names is used to determine the number of commands
being displayed and if only a single command is display then
the class doc is returned.
Returns:
__doc__ property for command function or a message stating there is no
help.
r rl )rC rm r9 rB rn ro r| r rp s r rs _FunctionalCmd.CommandGetHelpe sh &
Y4 C NQ$6 +
__T 4 4
55 ~~ )
__T^^ 3 3
44
r c $ U R U5 $ )a Execute the command with given arguments.
Args:
argv: Remaining command line flags and arguments after parsing command
(that is a copy of sys.argv at the time of the function call with
all parsed flags removed).
Returns:
Command return value.
)r| rJ s r rK _FunctionalCmd.Run s >>$ r )rB r| rx ) r r r
r r rG rs rK r
r r r rz rz P s !6 r rz c [ UR [ 5 ( d [ S5 eU /U=( d / - H n[ U5 U [
U' M U[ U ' g)an Add a command from a Cmd instance.
Args:
command_name: name of the command which will be used in argument parsing
cmd: Cmd instance to register
command_aliases: A list of command aliases that the command can be run as.
Raises:
AppCommandsError: is command is already registered OR cmd is not a subclass
of Cmd
AppCommandsError: if name is already registered OR name is not a string OR
name is too short OR name does not start with a letter OR
name contains any non alphanumeric characters besides
'_', '-', or ':'.
+Command must be an instance of commands.CmdN)
issubclass __class__r< r
_CheckCmdNamer' r$ ) command_namecmdrF r2 s r _AddCmdInstancer sU (
CMM3 ' '
H
IIn 526d$ (OD 7 )Lr c U [ 5 ; a [ SU - 5 e[ U [ 5 ( a [ U 5 S:: a [ S[ U 5 - 5 eU S R 5 ( d [ SU - 5 eU Vs/ s H# oR
5 ( a M US; a M! UPM% sn( a [ SU - 5 egs snf ) a Only allow strings for command names and aliases (reject unicode as well).
Args:
name_or_alias: properly formatted string name or alias.
Raises:
AppCommandsError: is command is already registered OR cmd is not a subclass
of Cmd
AppCommandsError: if name is already registered OR name is not a string OR
name is too short OR name does not start with a letter OR
name contains any non alphanumeric characters besides
'_', '-', or ':'.
z%Command or Alias '%s' already definedr z&Command '%s' not a string or too shortr z)Command '%s' does not start with a letter)_-:z1Command '%s' contains non alphanumeric charactersN)r( r r` strr9 isalphaisalnum)
name_or_aliascs r r r s )++
B( ) * * M3 ' '3}+=+B
C / 0 1 1 q ! ! # #
F * + , , L Ayy{aa?6Ja L
N * + , , MLs C C&Cc U" U [ R " 5 40 UD6n[ U[ 5 ( d [ S5 e[ X40 UD6 g)a Add a command from a Cmd subclass or factory.
Args:
command_name: name of the command which will be used in argument parsing
cmd_factory: A callable whose arguments match those of Cmd.__init__ and
returns a Cmd. In the simplest case this is just a subclass
of Cmd.
command_aliases: A list of command aliases that the command can be run as.
Raises:
AppCommandsError: if calling cmd_factory does not return an instance of Cmd.
r N)rn
FlagValuesr` r< r r )r cmd_factoryr r s r AddCmdr sD L%"2"2"4>># C
H
II,-u-r c Z [ U [ U [ R " 5 UUUS9U5 g)a Add a new command to the list of registered commands.
Args:
command_name: name of the command which will be used in argument
parsing
cmd_func: command function, this function received the remaining
arguments as its only parameter. It is supposed to do the
command work and then return with the command result that
is being used as the shell exit code.
command_aliases: A list of command aliases that the command can be run as.
all_commands_help: Help message to be displayed in place of func.__doc__
when all commands are displayed.
)rF r~ N)r rz rn r )r r} rF r~ s r
AddCmdFuncr s1 , u/?/?/A81@3DF " #r c ( \ rS rSrSrS rSS jrSrg)_CmdHelpi zMStandard help command.
Allows to provide help for all or specific commands.
c p [ U5 S: a US [ 5 ; a US nOSn[ SSSSUSS9 g)a Execute help command.
If an argument is given and that argument is a registered command
name, then help specific to that command is being displayed.
If the command is unknown then a fatal error will be displayed. If
no argument is present then help for all commands will be presented.
If a specific command help is being generated, the list of commands is
temporarily replaced with one containing only that command. Thus the call
to usage() will only show help for that command. Otherwise call usage()
will show help for all registered commands as it sees all commands.
Args:
argv: Remaining command line flags and arguments after parsing command
(that is a copy of sys.argv at the time of the function call with
all parsed flags removed).
So argv[0] is the program and argv[1] will be the first argument to
the call. For instance 'tool.py help command' will result in argv
containing ('tool.py', 'command'). In this case the list of
commands is searched for 'command'.
Returns:
1 for failure
r Nr F)rT rU rV rP rQ rR )r9 r0 rS )rD r rQ s r rK _CmdHelp.Run sB 2 4y1}a$6$88ahhq4 (eMr Nc L SS[ 5 0- n[ R " U5 $ )zReturns: Help for command.zHelp for all or selected command:
%(prog)s help []
To retrieve help with global flags:
%(prog)s --help
To retrieve help with flags only from the main module:
%(prog)s --helpshort []
prog)r rn ro )rD rq rr cmd_helps r rs _CmdHelp.CommandGetHelp s, 9 >+,
-H ??8 $$r r rx )r r r
r r rK rs r
r r r r r s
M@ %r r c S[ 5 - $ )zKGet synopsis for program.
Returns:
Synopsis including program basename.
z6%s [--global_flags] [--command_flags] [args])r r r r GetSynopsisr % s
B
r c p / nU( a [ U5 S:X a UR S[ 5 - 5 U( a [ U5 [ [ 5 5 :X a UR S[ 5 - 5 U b, U( a UR S5 UR SU - 5 SR U5 $ )a 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.
r z4Run '%s help' to see the list of available commands.z2Run '%s help ' to get help for . %s
)r9 appendr r% join)rV rr footers r _UsageFooterr / s & c)n)
MMH"$% & c)nN,<(==
MMF"$% &
mmB
MM$ '(
6 r c j
U( a [ R nO[ R nSR [ 5 S- 5 n[ R
S R nU( a [ R " UR S[ R S 5 5 n UR [ R " U [ R " 5 5 5 UR S5 U( a UR S5 S:X aY S[ 5 - n
UR [ R " U
[ R " 5 S S5 5 UR S5 [! [# 5 5 S
:X a / n GOUb US :X a [# 5 R% 5 n U R' 5 UR S
5 SR) U 5 nUR [ R " U[ R " 5 S5 5 UR S5 Ub U/n O\[* R, ( d [* R. ( d U ( a / n O([# 5 R% 5 n U R' 5 U GH n [1 U 5 n
U
R3 [5 5 U S9nUR7 5 nSR) U /U
R9 5 =( d / - 5 n[! U5 S
- [! U5 : d U( dM UR [ R " U[ R " 5 5 5 UR S5 UnO UR; [ 5 S- 5 nU( aM UR [ R " U[ R " 5 UU5 5 UR S5 OUR S5 [! U 5 S
:X d GMe U
R< nUR? 5 ( d GM UR U< SU < S35 UR URA US- 5 5 UR S5 GM UR S5 U( aq UR S5 U ( a$ UR [* RC 5 5 O#UR [* RA 5 5 UR S5 O UR S[E 5 - 5 UR S[G X+5 - 5 Ub [ RH " U5 g g )a 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.
r __main__r r z
zUSAGE: z r Nhelpz Any of the following commands:
z, z )rr r z
z
Flags for z:
zGlobal flags:
z-Run '%s --help' to get help for global flags.z
%s
)%r r r rjustr: modulesr rn ro replacer r TextWrap GetHelpWidthfindr r9 r% keyssortr rY r helpshortr3 rs r6 striprv ljustrA RegisteredFlagsGetHelpMainModuleHelpr r r )rT rU rV rP rQ rR stdfileprefixdochelp_msgsynopsisrr r2 commandr all_namesprefix1 cmd_flagss r rS rS F s , jjGjjG
88')A- .& J ''#s{{4! =>H MM%..5+=+=+?@A MM( "$;=(H MM%..5+=+=+?!#% & MM( a I 8v- "'')inn
mm67 IIi c
mmENN3(:(:(d I >4u<==>s ?:?c [ [ 5 q[ [ 5 S: a U ( a [ S5 g[ [ S 5 nUc [ S[ S - 5 [ S U$ )ab 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.
r z%FATAL Command expected but none givenNr zFATAL Command '%s' unknown)r\ r5 r9 r" r3 )command_requiredr s r
GetCommandr sZ "),)^a>? Yq\ *' _1IaL@Al .r c [ R " 5 [ R S R [ 5 5 [ [ 5 5 S: a
[ SS9nO [ S5 n[ R " UR! [ 5 5 5 g! [ a* n [ R " U R 5 Sn A NSn A f[ a- n[ R " 5 [ SU- 5 SnANSnAff = f)zMain 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.
r Nz
FATAL error in main: %sr T)r r )r RegisterAndParseFlagsWithUsager r mainr6
SystemExitr code Exception traceback print_excr" r9 r r3 ri )erh r s r _CommandsStartr s $$&:KK
!12 Q $/G v&G((7 n . /0
HHQVV :
05899:s# *B
D% C
D#C??Dc [ [ l [ [ l [
[ l [ R " 5 $ )zThis 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 parse_flags_with_usager really_start_ReplacementAppUsager[ runr r r rK rK s' 3# ##"#) r r c [ XX#S SS9 g )NTrO )rS )rT rU rV rP s r r r s 9n D:r r rx )NN)r r NNNF)r r NN)(r r r^ r r google.apputilsr gflagsrn rY r r r5 r$ r' r r" r% r( r0 r3 r6 r: objectr< rz r r r r r r r rS r\ r r rK r r r r r r s cN
y
?
?
A!& A!H; S ; | <,8.* 8&414 vx HL"&: z% r