-z S r SSKJr SSKJr SSKrSSKrSSKrSSKrSSKJ r SSKJ
r
\
R r " S S\ 5 r
SqSqSqSqSqS rS
rS'S jrS rS
rS rS rS rS(S jrS r " S S\ 5 r " S S\ 5 r S'S jr S r!S r" S)S jr# " S S \ 5 r$S r%S r& S*S jr'S+S jr(S! r)S" r*S# r+S$ r, S,S% jr-\" 5 \.S&:X a \," 5 gg)-aY 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. 'help' is the default
command executed if no command is expressed, unless a different default
command is set with SetDefaultCommand.
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.
Commands can allow GNU-style scanning of their command-specific argv by
calling appcommands.UseGnuGetOpt. This can be done within each command's
__init__ function or globally in the program's main function. (Don't call
FLAGS.set_gnu_getopt directly, because this will try to interpret command
flags before they have been registered.)
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 expects 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.
)absolute_import)print_functionN)app)flagsc \ rS rSrSrSrg)AppCommandsError z$The base class for all flags errors. N)__name__
__module__ __qualname____firstlineno____doc____static_attributes__r
-platform/bq/third_party/pyglib/appcommands.pyr r s ,r r c Sq 0 q0 qSqSn U [ R
; a [ R
U S:H qOSq[ S[ 5 g)z9Reset the module for test purposes; ONLY use for testing.Nhelp)APPCOMMAND_USE_GNU_GET_OPT_FOR_SUBCOMMAND1F) _cmd_argv _cmd_list_cmd_alias_list _cmd_defaultosenviron_cmd_gnugetoptAddCmd_CmdHelp)use_gnu_opt_names r ResetForTestr! sQ ))/,@#ZZ 01S8N N r c b [ R R [ R S 5 $ )z2Returns the friendly basename of this application.r )r pathbasenamesysargvr
r r GetAppBasenamer' s #((1+ &&r c
[ R R 5 U b" [ R R SU - 5 [ R R S[ 5 - 5 [ R " S5 g)zDisplay optional message, followed by a note on how to get help, then exit.
Args:
message: optional message to display
Raises:
SystemExit: always, to indicate exiting the program.
Nz%s
zRun '%s help' to get help
)r% stdoutflushstderrwriter' exit)messages r ShortHelpAndExitr0 sW ** JJVg%&**0>3CCD((1+r c [ $ )z#Return list of registered commands.)r r
r r GetCommandListr2 s
r c [ $ )z*Return list of registered command aliases.)r r
r r GetCommandAliasListr4 s
r c [ [ 5 5 n [ 5 R 5 H u pU R U5 X' M U $ )z6Return list of registered commands, including aliases.)dictr2 r4 itemsget)all_cmds cmd_aliascmd_names r GetFullCommandListr< s>
."
#( 0 2 8 8 :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
)r2 r8 r4 )names r GetCommandByNamer? s'
1 3 7 7 = >>r c [ $ )z Return list of remaining args.)r r
r r GetCommandArgvrA s r c U q g)z1Allow mixed flag/arg ordering in subcommand argv.N)r )choices r UseGnuGetOptrD 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.)maxr2 len)r; s r GetMaxCommandLengthrH s( N,<
=,<c(m,<
= >>
=s .c H \ rS rSrSr S S jrS rS rS S jrS r S 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 Xl X0l X l X@l XPl X`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 aliases that the command can be run as.
all_commands_help: A short description of the command that is shown when
the user requests help for all commands at once.
help_full: A long description of the command and usage that is
shown when the user requests help for just this
command. If unspecified, the command's docstring is
used instead.
hidden: Whether to hide this command from the help output.
Raises:
AppCommandsError: if self is Cmd (Cmd is abstract)
z*Cmd is abstract and cannot be instantiatedN)
_command_name_command_aliases_command_flags_all_commands_help
_help_full_hiddentyperJ r )selfr> flag_valuescommand_aliasesall_commands_help help_fullhiddens r __init__ Cmd.__init__ sC 0 +% / OL 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:
unused_argv: Remaining command line arguments after parsing flags and
command (in other words, 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 this method must be overridden.
.z.Run() is not implemented)r rS r r )rT unused_argvs r RunCmd.Run s/ T
tDz 2 2 4 5 5r c D ^ [ R T R 5 [ R n SU 4S jjnU[ l [ U5 nT R R
5 T R U5 nUc SnO[ U[ 5 ( d eUU[ l [ R T R 5 $ ! [ R a) n[ R " SXUR S9 SnAOHSnAf [ R ( a* [ R " 5 [ R" " 5 e = f U[ l [ R T R 5 g! U[ l [ R T R 5 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 > [ XUUTR SS9 g NT)exitcodeshow_cmdshow_global_flags)AppcommandsUsagerM ) shorthelpwriteto_stdoutdetailed_errorrd rT s r ReplacementAppUsage+Cmd.CommandRun..ReplacementAppUsage? s y. (43E3E)-/r )rh rj rd )r r) NN)FLAGSappend_flag_valuesrO r usageParseFlagsWithUsagemark_as_parsedr_
isinstanceintremove_flag_values
UsageErrorrd pdb_post_mortem traceback print_excpdb post_mortem)rT r& orig_app_usagerk reterrors ` r
CommandRunCmd.CommandRun- s3
T 0 01YYNJN%)/
$CI4"4( **,hhtn ;#C%%
%% !ci t 2 23 ^^ N AennM
//
N !ci t 2 23 !ci t 2 23s, AC E C?:E3 ?AEE3 3,F c b [ U[ 5 ( a< [ U5 S: a- U R b [ R
" U R 5 $ 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) zNo help available)rr listrG rP r doc_to_helprQ r )rT r^ cmd_namess r CommandGetHelpCmd.CommandGetHelp] s} * 9d##I(: +
t 6 6
77
$
t
//
t||
,,
r c U R $ )zOGet aliases for command.
Returns:
aliases: list of aliases for the command.
)rN rT s r CommandGetAliasesCmd.CommandGetAliases| s r c U R $ )z/Get name of command.
Returns:
Command name.
)rM r s r CommandGetNameCmd.CommandGetName s r )rP rN rO rM rQ rR )NNNFN) r r r
r r rZ r_ r~ r r r r r
r r rJ rJ s0 9=>C KB5$.4` !>! r rJ c 2 ^ \ rS rSrSrU 4S jrS rSrU =r$ )_FunctionalCmdi zPClass to wrap functions as CMD instances.
Args:
cmd_func: command function
c f > SU; a UR US' [ [ U ] " X40 UD6 X0l g)an 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.
**kargs: Additional keyword arguments to be passed to the
superclass constructor.
rX N)r superr rZ _cmd_func)rT r> rU cmd_funckargs __class__s r rZ _FunctionalCmd.__init__ s6 % #++eK .$(DeD Nr 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 )rT r& s r r_ _FunctionalCmd.Run s >>$ r r r r r
r r rZ r_ r
__classcell__r s @r r r s r r c [ UR [ 5 ( d [ S5 eU /U=( d / - H n[ U5 U [
U' M U[ U ' g)a: 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: If 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)
issubclassr rJ r
_CheckCmdNamer r ) command_namecmdrV _r> 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: 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)r -:z1Command '%s' contains non alphanumeric charactersN)r4 r rr strrG 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)aU 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.
**kwargs: Additional keyword arguments to be passed to the
cmd_factory at initialization. Also passed to
_AddCmdInstance to catch command_aliases.
Raises:
AppCommandsError: if calling cmd_factory does not return an instance of Cmd.
r N)r
FlagValuesrr rJ r r )r cmd_factorykwargsr s r r r sD L%"2"2"4??# C
H
II,.v.r c X [ U [ U [ R " 5 UUUUS9US9 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.
hidden: Whether to hide this command from the help output.
)rV rW rY )rV N)r r r r )r r rV rW rY s r
AddCmdFuncr s3 , u/?/?/A81@3D(.0 #2 3r c 2 ^ \ rS rSrSrU 4S jrS rSrU =r$ )r i zMStandard help command.
Allows to provide help for all or specific commands.
c ^ > SU; a SS[ 5 0- US' [ [ U ] " U0 UD6 g )NrX 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' r r rZ )rT argsr r s r rZ _CmdHelp.__init__ sB & 3 ^% &
'
[
(D"D3F3r 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)rh ri rj rd re rf )rG r< rg )rT r& re s r r_ _CmdHelp.Run* sB 2 4y1}a$6$88ahhq4 (eMr r
r r s @r r r s
4 M Mr 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 K 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
)rG appendr' r2 join)rj r footers r _UsageFooterr U s & c)n)
MMH"$% & c)nN,<(==
MMF"$% &
mmB
MM$ '(
6 r c
U( a [ R nO[ R nSR [ 5 S- 5 n[ R
S R nU( ax [ R " UR S[ 5 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 SS5 5 UR S5 [! [# 5 5 S :X a / n O[# 5 R% 5 V V
s/ s H u pU
R& ( a M U PM n n n
U R) 5 Ub US :X am UR S 5 S
R+ U 5 nUR [ R " U[ R " 5 S5 5 UR S5 Ub U/n O3[, R. ( d [, R0 ( d U ( a / n U GH n[3 U5 n UR5 [7 5 U S9nUR= 5 nS
R+ UR? 5 /URA 5 =( d / - 5 n[! U5 S - [! U5 : d U( dM UR [ R " U[ R " 5 5 5 UR S5 UnO URC [ 5 S- 5 nU( aM UR [ R " U[ R " 5 UU5 5 UR S5 OUR S5 [! U 5 S :X d GMt URD nU( d GM UR U< SU< S35 UR URG US- 5 5 UR S5 GM UR S5 U( aq UR S5 U ( a$ UR [, RI 5 5 O#UR [, RG 5 5 UR S5 O UR S[ 5 - 5 UR S[K X+5 - 5 Ub [ RL " U5 g
g
s sn
n f ! [8 a nSU< S[; U5 < S3n S
nAGNS
nAff = f)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.
Raises:
SystemExit: to indicate exiting the program.
r __main__r z
zUSAGE: z r) Nr z Any of the following commands:
z, z )r z Internal error for command 'z': r] r z
z
Flags for z:
zGlobal flags:
z-Run '%s --help' to get help for global flags.z
%s
)'r% r* r, rjustrH modulesr r r replacer' r- text_wrapget_help_widthfindr rG r2 r7 rR sortr rm r helpshortr? r rA Exceptionr stripr r ljustrO get_helpmain_module_helpr r. )rh ri rj rd re rf stdfileprefixdochelp_msgsynopsisr r; r r> commandcmd_helpr} all_namesprefix1 cmd_flagss r rg rg l s 2 jjGjjG
88')A- .& J ''# T>3C!DEH MM%//(E,@,@,BCD MM( "$;=(H MM%//(E,@,@,BI"$& ' MM( a I '5&6&<&<&>%&>]X &> % NN8v-
mm67 IIi c
mmEOOC)=)=)?FG
mmH *i u)id t$GM''(8I'Nh ~~ H !"g&?&?&A&GRHJI
9~S[( mmEOOIu/C/C/EFG
mmDg 3 5 9:g
mmEOOHe.B.B.Df$+- .
mmF
mmD
9~ ((i
VT:;
i((56
f A B
-- MM#$
mmE**,-
mmENN$% MM$ MMA"$% & --<BBC
HHX }%( M;?ULhMs$ T*&T*T00
U:UUc [ R 5 nU( a [ R S5 [ U 5 q[ R U5 [ $ ! [ R
a n[
SU- 5 SnAgSnAff = f)zParse the flags, exiting (after printing usage) if they are unparseable.
Args:
argv: List of command line arguments.
force_gnu_off: If True, force GNU-style off for flags parsing.
Returns:
remaining command line arguments after parsing flags
Fz FATAL Flags parsing error: %sN)rm
is_gnu_getoptset_gnu_getoptr r Errorr0 )r&
force_gnu_offold_use_gnu_get_optr} s r rp rp sj > --/ 5!d I ,- >4u<==>s AA B,A??Bc [ [ 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) FATAL Command '%s' unknown)rp r rG r0 r? )command_requiredr s r
GetCommandr sZ "),)^a>? Yq\ *' _1IaL@Al .r c U q g)zChange the default command to execute if none is explicitly given.
Args:
default_command: str, the name of the command to execute by default.
N)r )default_commands r SetDefaultCommandr s !,r c < [ R S R [ 5 5 [ [ 5 5 S: a
[ SS9nO$[ [ 5 nUc [ S[ - 5 [ R! [" 5 [ R
" UR% [ 5 5 5 e! [ a% n[ R
" UR 5 eSnAf[ a- n[ R " 5 [ SU- 5 SnANSnAff = f)ao Main initialization.
Calls __main__.main(), and then the command indicated by the first
non-flag argument, or 'help' if no argument was given. (The command
to execute if no flag is given can be changed via SetDefaultCommand).
Only non-flag arguments are passed to main(). If main does not call
sys.exit, the return value of the command is used as the exit status.
r Nz
FATAL error in main: %sr) T)r r )r% r mainrA
SystemExitr. coder rw rx r0 rG r r? r rm r r r~ )r^ er} r s r _CommandsStartr s :KK
!12 Q $/G |,G3lBC~& ##N$4566
((166
:
05899:s# *B7 7
D C!!
D.#DDc [ R S5 [ R n [ [ l [ R
" [ [ S9U [ l $ ! U [ l f = f)zThis must be called from __main__ modules main, instead of app.run().
app.run will base its actions on its stacktrace.
Returns:
app.run()
F) flags_parser)rm r r ro _ReplacementAppUsagerunr rp )original_usages r r_ r_ 8 sE u 99."#) 77>0C D CICIs A
A+c [ XX#S SS9 g rc )rg )rh ri rj rd s r r r J s 9n D:r r r )T)NNF)r r NNNF)F)r r NN)/r
__future__r r r ry r% rw abslr r rm r r r r r r r r! r' r0 r2 r4 r< r? rA rD rH objectrJ r r r r r r r r rg rp r r r r_ r r r
r r r s+ l\ ' %
y
$'
?
?
Y & Y x" S " J :,4/. 8<.3300Ms 0Mf. DHEJm`>04! 7> $ HL"&:
z% r