eijdZddlmZddlZddlZddlmZddlmZddlmZddlm Z ddlm Z dd lm Z dd lm Z d Z d Zd Zd9dZd9d:dZ d;d:dZdd Zd?d$Zd%Z d@d&Z!d'Z"d(Z#dAd*Z$d+Z%d,Z&d-Z'd.Z(d9d/Z)d0Z*d1Z+d2Z,dBd3Z-d4Z.d)d5e fd6Z/Gd7d8Z0dS)CaUtilities for producing help strings for use in Fire CLIs. Can produce help strings suitable for display in Fire CLIs for any type of Python object, module, class, or function. There are two types of informative strings: Usage and Help screens. Usage screens are shown when the user accesses a group or accesses a command without calling it. A Usage screen shows information about how to use that group or command. Usage screens are typically short and show the minimal information necessary for the user to determine how to proceed. Help screens are shown when the user requests help with the help flag (--help). Help screens are shown in a less-style console view, and contain detailed help information. ) annotationsN) completion)custom_descriptions) decorators) docstrings) formatting) inspectutils) value_typesPFctj|}t||}tj|}t j|}t ||||}t|||||}t||} t|rt|||\} } ng} g} t||} ||| g| z| z| z} d| D}d d|DS)aGets the help string for the current component, suitable for a help screen. Args: component: The component to construct the help string for. trace: The Fire trace of the command so far. The command executed so far can be extracted from this trace. verbose: Whether to include private members in the help screen. Returns: The full help screen as a string. verbose)tracer)rcg|]}||SN).0sections Q/home/div/.hermes/hermes-agent/venv/lib/python3.11/site-packages/fire/helptext.py zHelpText..ZsKKKw7JG7J7J7J c3<K|]\}}t||VdSr)_CreateOutputSection)rnamecontents r zHelpText..[sD $4))r) r Info_GetActionsGroupedByKindGetFullArgSpecr GetMetadata _NameSection_SynopsisSection_DescriptionSectioncallable_ArgsAndFlagsSections_UsageDetailsSectionsjoin) componentrrinfoactions_grouped_by_kindspecmetadata name_sectionsynopsis_sectiondescription_sectionargs_and_flags_sectionsnotes_sectionsusage_details_sectionssectionsvalid_sectionss rHelpTextr72s\  9 % %$4YPPP  $Y / /$  #I . .(iUGLLL,%($GGG+It<<i.C dH//+^^!N01HJJ%':;   LK8KKK. )  rreturntuple[str, str]ct||}t|}tj|r=tt z t |dzz }tj||t}|r|d|}n|}d|fS)z&The "Name" section of the help string.include_separatorsz - NAME)_GetCurrentCommand _GetSummaryrNeedsCustomDescription LINE_LENGTHSECTION_INDENTATIONlen GetSummary)r*r+rrcurrent_commandsummaryavailable_spacetexts rr#r#as'uIII/   '/ :::!$77#o>C?D;E;EEO!,Y-8::G  + +' + +DD D $rctt|d}t|}g}|r"|t|t |rDt ||}|r||n|r||jd|} |d| } d| fS)z*The "Synopsis" section of the help string.T)rr< |  SYNOPSIS)r>_GetPossibleActionsappend_GetPossibleActionsStringr&_GetArgsAndFlagsString separatorr)) r*r,r-r.rrEpossible_actions continuationscallable_continuation continuationrHs rr$r$vs'UtLLL/()@AA-F23CDDEEE i,24BB,01111 ,5?+++M**,  , ,l , ,$ d rtuple[str, str] | Nonectj|rFttz }tj||t}tj||t}nt |}t|}|p|pd}|rd|fSdS)a5The "Description" sections of the help string. Args: component: The component to produce the description section for. info: The info dict for the component of interest. Returns: Returns the description if available. If not, returns the summary. If neither are available, returns None. N DESCRIPTION)rr@rArBGetDescriptionrD_GetDescriptionr?)r*r+rG descriptionrFrHs rr%r%s/ :: !$77O%4Y5@BBK!,Y-8::GG"$''K$G  ' '4$  4  4rc8t|||||jv|S)Nrequired short_arg)_CreateFlagItemkwonlydefaults)flagdocstring_infor-r_s r_CreateKeywordOnlyFlagItemrds-  ND4t7J+J   rc`d|D}tj|fd|DS)zGets a list of single-character flags that uniquely identify a flag. Args: flags: list of strings representing flags Returns: List of single character short flags, where the character occurred at the start of a flag once. cg|] }|d S)rrrfs rrz"_GetShortFlags..s%%%!1%%%rc,g|]}|dk|S)r)rvshort_flag_countss rrz"_GetShortFlags..s) > > >$5a$8A$=$=!$=$=$=r) collectionsCounter)flags short_flagsrls @r_GetShortFlagsrqsC&%u%%%+!)+66 > > > >[ > > >>rcjdtjtjz }jtjtjz d}|tj}g}g}|dfd|D}jr)|tj|r^|rdnd} | d | df} || |r|r|dt|fd|D} tj fd j D} | | z} j r0g}jpg}d |D}t|}|D]}}t|tjra|jd |vr|jd }d |d |j}n d|j}t%|j|}||~|r@| r)d}t'|dd}| || |t+j }|rd}n| rd}nd}t'||d}| || r,dd | f}||||fS)z1The "Args and Flags" sections of the help string.Nrcc2g|]}t|Sr)_CreateArgItem)rargrcr-s rrz)_ArgsAndFlagsSections..s5 S.$//rzPOSITIONAL ARGUMENTS ARGUMENTS )NOTESz6You can also use flags syntax for POSITIONAL ARGUMENTSc Hg|]}t|d|dvS)Frr])r`)rrbrcr-unique_short_argss rrz)_ArgsAndFlagsSections..sP   uG00rc Fg|]}t||dvS)r)r_)rd)rrbrcr-unique_short_kwonly_flagss rrz)_ArgsAndFlagsSections..sN  ! G88rcg|] }|j Srrrgs rrz)_ArgsAndFlagsSections..s(((Q!&(((rr-z, ----) flag_stringz&The following flags are also accepted.r indentz3Additional undocumented flags may also be accepted.zAdditional flags are accepted.zFlags are accepted.FLAGS)argsrCdefaultsgetrACCEPTS_POSITIONAL_ARGSvarargsrNrtr)rstriprq kwonlyargsvarkw isinstancer KwargInforr` _CreateItemextend_GetArgDescription)r+r-r.args_with_no_defaultsargs_with_defaultsaccepts_positional_argsr2r3 arg_itemstitlearguments_sectionpositional_flag_itemskwonly_flag_items flag_itemsdocumented_kwargsro flag_namesunique_short_flagsrb short_namer flag_itemmessageitemr[ flags_sectionrcrzr|s ` @@@rr'r's)$HS^^c$-6H6H%H$HIyTY#dm2D2D!D!E!EF%LL)KLL.().&)  \ t|^T::&= N " ";E ) 4 4 ; ;D A AB""#4555!8 M%%788 % -T_== / %'88* Z$   %2E((%(((J' 33 , , D*. / / , 9Q<- - -y|*7J77DI77++(TY((+# I~t#%%%    ++++  :7D333$)***$TZ@@K&Egg &0gg%g w A 6 6 6Dd2dii 334M""=111 . 00rcr|\}}}}g}|jr"|t||jr"|t||jr#|t|||jr*|dt d|jf|S)z.The usage details sections of the help string.INDEXESINDEX)membersrN_MakeUsageDetailsSection_ValuesUsageDetailsSection_NewChoicesSectionnames)r*r,groupscommandsvaluesindexesr5s rr(r(s&=#&(FG ( ^6 OO,V44555 8 OO,X66777 ^C OO.y&AABBB _M OOY 27GM J JKLLL /rc2|d}|jr|jndSNrc)rFr+rcs rr?r?0s#().#1#9 C  tCrc2|d}|jr|jndSr)r[rs rrZrZ5s#().'5'A K # #tKrc|jdt|jt|jz }|jt|jt|jz d}|tj}g}|r0|r d|D}n d|D}|||s|js|jr| d|j rFtj |j }d|d}| |d|S)a-The args and flags string for showing how to call a function. If positional arguments are accepted, the args will be shown as positional. E.g. "ARG1 ARG2 [--flag=FLAG]" If positional arguments are disallowed, the args will be shown with flags syntax. E.g. "--arg1=ARG1 [--flag=FLAG]" Args: spec: The full arg spec for the component to construct the args and flags string for. metadata: Metadata for the component, including whether it accepts positional arguments. Returns: The constructed args and flags string. NcZg|](}tj|)Srr Underlineupperrrus rrz*_GetArgsAndFlagsString..Vs;777 )#))++66777rc fg|].}d|dtj|/Sr=rrs rrz*_GetArgsAndFlagsString..YsK 9s 8 8Z)#))++66 8 8r[]...rK)rrCrrrrrrrrNrrrrr)) r-r.rrrarg_and_flag_strings arg_stringsvarargs_underlinedvarargs_strings rrPrP:sj&)$HS^^c$-6H6H%H$HIyTY#dm2D2D!D!E!EF%LL)KLL -77 5777kk*k ,,,+4?+dj+ *** \0#-dl.@.@.B.BCC1+111N/// & ' ''rcVg}|D]#}|jr||j$|S)z"The list of possible action kinds.)rrNr)r,rR action_groups rrMrMks@-11l1l/000 rc@dd|DS)zAA help screen string listing the possible action kinds available.rJc3bK|]*}tj|V+dSrr)ractions rrz,_GetPossibleActionsString..vsI44(88444444rr))rRs rrOrOts4 44"2444 4 44rctdd}tdd}tdd}tdd }tj|| }|D]\}}t|}t j|r||| t j|r||| t j|r||| t|ttfrt|rrt|} | d krA|d dt| Dn|d| dz ||||gS)z8Gets lists of available actions, grouped by action kind.groupr)rpluralcommandrvaluerindexrr)rmember , c34K|]}t|VdSr)str)rxs rrz+_GetActionsGroupedByKind..s( F FAQ F F F F F Frr~z0..rj) ActionGrouprVisibleMembersrr IsGroupAdd IsCommandIsValuerlisttuplerCr)range) r*rrrrrr member_namer component_lens rr r zs GH 5 5 5& i ; ; ;( GH 5 5 5& WY 7 7 7'  %i A A A'$22k6k""K6""2 jjk&j111V$$4ll Fl3336""2 jjk&j111 D%=))0i0 NNMr kktyy F F}1E1E F F FFFkGGGG kk.]1_..k/// (FG ,,rTc<|r||}nd}|S)z@Returns current command for the purpose of generating help text.r;) GetCommand)rr<rEs rr>r>s. &&:L&MMOOO rrrrcdtj|dtj|tSNrw)rBoldIndentrB)rrs rrrs9od## 5 5 7/00 5 55rcttz tz }t||}t j|}t||}|rd|nd}|t|z }t j |||}d d||fD}t||tS)aReturns a string describing a positional argument. Args: arg: The name of the positional argument. docstring_info: A docstrings.DocstringInfo namedtuple with information about the containing function's docstring. spec: An instance of fire.inspectutils.FullArgSpec, containing type and default information about the arguments to a callable. Returns: A string to be used in constructing the help screen for the function. Type: rrwc3K|]}||V dSrrrparts rrz!_CreateArgItem..s'KK4dK$KKKKKKrr) rArBSUBSECTION_INDENTATIONrr BoldUnderliner _GetArgTyperCEllipsisTruncater)r)rurcr-max_str_lengthr[ arg_stringarg_typerGs rrtrts !447MM."377+' 44* d # #($, 4 h "("S]]2/!(O^LL  KKHk+BKKKKK+ Z5K L L LLrcpttz tz }t||}|s.t j|}d|d|}|r|dz }|r|d} d| d|}t||} t||} | dkrd| d } | rd | nd } |t| z } t j | | |} | rd | nd } |t| z } t j | | |} d d| | |fD}t||tS)aReturns a string describing a flag using docstring and FullArgSpec info. Args: flag: The name of the flag. docstring_info: A docstrings.DocstringInfo namedtuple with information about the containing function's docstring. spec: An instance of fire.inspectutils.FullArgSpec, containing type and default information about the arguments to a callable. required: Whether the flag is required. flag_string: If provided, use this string for the flag, rather than constructing one from the flag name. short_arg: Whether the flag has a short variation or not. Returns: A string to be used in constructing the help screen for the function. rrz (required)rrrNonez Optional[]rrz Default: rwc3K|]}||V dSrrrs rrz"_CreateFlagItem..s;t rr) rArBrrrrrr_GetArgDefaultrCrr)r) rbrcr-r^rr_rr[flag_name_upper short_flagr arg_defaultrGs rr`r`s0!447MM."488+ 0 *4::<<88O/t//o//K != K2aJ1j11K11K t $ $(tT**+F&8&&&H$, 4 h "("S]]2/!(O^LL .9@)K)))b+"S%5%55/!+OO  +{;+ [+6L M M MMrc||jvr4|j|} |jS#t$rt|cYSwxYwdS)a|Returns a string describing the type of an argument. Args: arg: The name of the argument. spec: An instance of fire.inspectutils.FullArgSpec, containing type and default information about the arguments to a callable. Returns: A string to be used in constructing the help screen for the function, the empty string if the argument type is not available. r)r __qualname__AttributeErrorrepr)rur-rs rrrsc D $H  "" (^^  s ;;ct|j}|j| d}t||jD]\}}||krt |cS||jvrt |j|SdS)aReturns a string describing a flag's default value. Args: flag: The name of the flag. spec: An instance of fire.inspectutils.FullArgSpec, containing type and default information about the arguments to a callable. Returns: A string to be used in constructing the help screen for the function, the empty string if the flag does not have a default or the default is not available. Nr)rCrrziprra)rbr- num_defaultsrrudefaults rrrsT]##,y,0,dm<<lc7 d{{ ']] T   #D) * ** rcB|s|Stj||}|d|Sr)rr)rr[rs rrr0s@  K!+v66+     rc^|jr%|jD]}|j|d|d|fvr |jcSdS)N*z**)rrr[)rrcarg_in_docstrings rrr8s[,*/,,  4T[$[["A A A++++ B rcg}|D]\}}tj|}|}|d}|rt j|s|j}n?t j|r)t j|ttz t}nd}t||}| ||j t|j |fS)z>Creates a usage details section for the provided action group.rcN)GetItemsr rrrr@rFrDrArBrrNrrrr)r item_stringsrrr+rrcrFs rrr@s,"++--  ldF  V $ $D DXX.//N#:6BB&gg  3F ; ;#. + 33[BBggg tW % %D   # # % % \.4466 E E GGrcfg}|D]\}}~tj|jj}d}d|vr9|d}|jr*|jD]"}|j|krt||j}#|t|}| |dtd|fS)zDCreates a section tuple for the values section of the usage details.NrcVALUESVALUE) r r r __class____init__rrrr[rrNr) r*rvalue_item_strings value_namer init_info value_iteminit_docstring_infoarg_infos rrrUs!??,, * *j% !)"5">??IJ9$$%&67  !G+0 G GH ]j ( ($Z1EFFJz??jj)))) &w0BCC DDrctjtj|}t|ddd|zdS)Nz is one of the following:rwrrjr)rrrrr))rchoicesname_formatteds rrrhsV?:#7#=#=>>.  222 V[[ ! !!    rc|r)|}|}nd}d}|sd}|}tj|}t j|}t ||}t|} g} | r"| t| t|} t|ryt||} | r)| d | n|r| |j| t!|| r|dd | zz }||rdndzdz} d |d d | d | S) aDReturns usage text for the given component. Args: component: The component to determine the usage text for. trace: The Fire trace object containing all metadata of current execution. verbose: Whether to display the usage text in verbose mode. Returns: String suitable for display in an error screen. NFrrrKrJz -- z--helpzUsage: rwz2 For detailed information on this command, run: )rNeedsSeparatingHyphenHyphenr r!rr"r rMrN_GetPossibleActionsUsageString_UsageAvailabilityLinesr&_GetCallableUsageItemsr)rQr_GetCallableAvailabilityLines)r*rrrneeds_separating_hyphen_hyphencontinued_commandr-r.r,rRrSavailability_linescallable_items help_commands r UsageTextr$ps +  G%*%F%F%H%H""G%*" G  $Y / /$  #I . .(5YPPP()@AA-K78HIIJJJ./FGG iC+D(;;N,388N334444 ,5?+++;DAABBB9uzz-8888 1 :s<  &       rc@|rd|}d|dSdS)N|<>r)rR actions_strs rrrs2((+,,K {    rcg}|D]=}|jr4td|jd|j}||>|S)Nz available :)headeritems)r_CreateAvailabilityLinerrrN)r,r!ravailability_lines rrrsl-33l314l1444" 1222 rc |jdt|jt|jz }|jt|jt|jz d}|tj}|s d|D}n d|D}|s|js|jr|d|j r0|d|j d|S)zBA list of elements that comprise the usage summary for a callable.NcBg|]}d|d|Srrrs rrz*_GetCallableUsageItems..s@ / / /&# % % % % / / /rc6g|]}|Srr2rs rrz*_GetCallableUsageItems..s : : :SSYY[[ : : :rrrr) rrCrrrrrrrNrr)r-r.rrrr-s rrrs)$HS^^c$-6H6H%H$HIyTY#dm2D2D!D!E!EF%LL)KLL ; / /- / / /EE ; :$9 : : :E4?dj LL \1 LL/T\''))///000 ,rc.fdjDS)Nc36K|]}|jvk|VdSr)ra)rrbr^r-s rrz(_KeywordOnlyArguments..sA 8 84 $$"55 6 6  6 6 6 6 8 8r)r)r-r^s``r_KeywordOnlyArgumentsr6s5 8 8 8 8 84? 8 8 88rc |jt|jt|jz d}dtj|t |dD}dt |dD}g}|r%|td|d |r%|td |d |jr-|s|rd nd }|t|gd |S) zHThe list of availability lines for a callable for use in a usage string.Ncg|]}d|Srrrrbs rrz1_GetCallableAvailabilityLines..s0HHHDKKKHHHrF)r^cg|]}d|Sr9rr:s rrz1_GetCallableAvailabilityLines..s+k4kkrTzoptional flags:r)r,r- header_indentzrequired flags:zadditional flags are acceptedzflags are accepted) rrCr itertoolschainr6rNr.r)r-roptional_flagsrequired_flagsr!additional_flagss rrrs~yTY#dm2D2D!D!E!EFHHIO/uEEE-G-GHHH.3D4HHH. 2'8./ 1 1 12222'8./ 1 1 1222 Z2)--;-77,'7r./ 1 1 1222 rc||z }dtj||}tj||}tj||}||t |dzdzS)Nrw)width)spaces)r)r WrappedJoinrrC) r,r-r< items_indent line_length items_width items_textindented_items_textindented_headers rr.r.s~l*+yy/[IIIJJ*")*\JJJ%f]CCC/ .s?/C/C/D/DE E LLrc&eZdZdZdZddZdZdS)rz$A group of actions of the same kind.c>||_||_g|_g|_dSr)rrrr)selfrrs rrzActionGroup.__init__s"DIDKDJDLLLrNcn|j||j|dSr)rrNr)rOrrs rrzActionGroup.Adds4JdLrc6t|j|jSr)rrr)rOs rr zActionGroup.GetItemss tz4< ( ((rr)__name__ __module__r__doc__rrr rrrrrsL,,     )))))rr)NF)r8r9r)r8rV)F)NT)rrrrr8r)FNF)r)T)1rT __future__rrmr=firerrrrrr r rArBrr7r#r$r%rdrqr'r(r?rZrPrMrOr r>rrtr`rrrrrrrr$rrrr6rr.rrrrrWsZ"#"""""$$$$$$ ,,,,^, 08 ? ? ?]1]1]1@"DDD LLL .(.(.(b444 ----65555 MMMB:?05;N;N;N;N|   .   .GGG*EEE&9999x   08888 @+,"(3MMMM))))))))))r