|hjldZddlZddlZddlmZddlmZddlmZddlmZddlmZddlm Z dd lm Z d Z d Z d Z d0d Zd0d Z d1dZdZdZdZdZdZdZdZdZdZdZd2dZd3dZdZdZ d4dZdZ dZ!d5d!Z"d"Z#d#Z$d$Z%d%Z&d0d&Z'd'Z(d(Z)d)Z*d6d*Z+d+Z,d d,e fd-Z-Gd.d/Z.y)7aUtilities 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. N) completion)custom_descriptions) decorators) docstrings) formatting) inspectutils) value_typesPctj|}t||}tj|}t j |}t ||||}t|||||}t||} t|rt|||\} } ng} g} t||} ||| g| z| z| z} djd| 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)r c30K|]}| t|ywN)_CreateOutputSection).0sections L/var/www/html/test/engine/venv/lib/python3.12/site-packages/fire/helptext.py zHelpText..Xs" !4G$s) rInfo_GetActionsGroupedByKindGetFullArgSpecr GetMetadata _NameSection_SynopsisSection_DescriptionSectioncallable_ArgsAndFlagsSections_UsageDetailsSectionsjoin) componentrrinfoactions_grouped_by_kindspecmetadata name_sectionsynopsis_sectiondescription_sectionargs_and_flags_sectionsnotes_sectionsusage_details_sectionssectionss rHelpTextr/0s   9 %$4YP  $ $Y /$  # #I .(iUGL,%($G+It<i.C dH/+^!N01HJ%':;    ct||}t|}tj|r7tt z t |dzz }tj||t}|r |d|}d|fS|}d|fS)z&The "Name" section of the help string.include_separatorsz - NAME)_GetCurrentCommand _GetSummaryrNeedsCustomDescription LINE_LENGTHSECTION_INDENTATIONlen GetSummary)r#r$rrcurrent_commandsummaryavailable_spacetexts rrr^s'uI/  '// :!$77#o>C?D;EEO!,,Y-8:G  c' +D $ D $r0c6t|d}t|}g}|r|jt|t |r=t ||}|r|j|n|r|j|j dj|} |d| } d| fS)z*The "Synopsis" section of the help string.T)rr3 |  SYNOPSIS)r5_GetPossibleActionsappend_GetPossibleActionsStringr_GetArgsAndFlagsString separatorr") r#r%r&r'rr<possible_actions continuationscallable_continuation continuationr?s rrrss'UtL/()@A-23CDE i24B01 5??+M*,  Al^ ,$ d r0ctj|rDttz }tj||t}tj ||t}nt |}t|}|xs|xsd}|rd|fSy)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)rr7r8r9GetDescriptionr;_GetDescriptionr6)r#r$r> descriptionr=r?s rrrs// :!$77O%44Y5@BK!,,Y-8:G"$'K$G  ' '4$ 4  r0c:t|||||jv|S)Nrequired short_arg)_CreateFlagItemkwonlydefaults)flagdocstring_infor&rUs r_CreateKeywordOnlyFlagItemrZs&  ND4t7J7J+J r0c|Dcgc]}|d }}tj|}|Dcgc] }||dk(s |c}Scc}wcc}w)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. r) collectionsCounter)flagsf short_flagsshort_flag_countsvs r_GetShortFlagsrdsR %%!1%+%!))+6 >$5a$8A$=! >>& >s A AAc Z|jdt|jt|jz }|jt|jt|jz d}|jtj }g}g}|d}|D cgc]} t | ||} } |jr&| jt |j||| rN|rdnd} | dj| jdf} |j| |r|r|jdt|} |Dcgc]}t|||d|d| v }}t|j}|jDcgc]}t||||d|v }}||z}|jr;g}|jxsg}|Dcgc]}|j }}t|}|D]}t#|t$j&s|j d|vr"|j d}d |d |j }nd |j }t|j |||}|j||r4|r!d}t)|dd}|j||j+|t-|j|}|rd}n|rd}nd}t)||d}|j||r$ddj|f}|j|||fScc} wcc}wcc}wcc}w)z1The "Args and Flags" sections of the help string.NrYzPOSITIONAL ARGUMENTS ARGUMENTS )NOTESz6You can also use flags syntax for POSITIONAL ARGUMENTSFrrS)rU-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)argsr:defaultsgetrACCEPTS_POSITIONAL_ARGS_CreateArgItemvarargsrEr"rstriprdrV kwonlyargsrZvarkwname isinstancer KwargInfo _CreateItemextend_GetArgDescription)r$r&r'args_with_no_defaultsargs_with_defaultsaccepts_positional_argsr+r,rYarg arg_itemstitlearguments_sectionunique_short_argsrXpositional_flag_itemsunique_short_kwonly_flagskwonly_flag_items flag_itemsdocumented_kwargsr_r` flag_namesunique_short_flags short_namerk flag_itemmessageitemrQ flags_sections rr r sS))$HS^c$--6H%HIyyTYY#dmm2D!D!EF%LL)K)KL.().' S.$/)  \\ t||^T:&= ";E ) 4 ; ;D AB""#45!8 M%%78 %    uG00-T__= //   ! G88%'88* ZZ    %2E"'(Q!&&(J(' 3 , D*.. / 99Q<- -yy|*J[]...rB)ror:rprqrrrr Underlineupperr|rvrwrErtr") r&r'r~rrarg_and_flag_stringsr arg_stringsvarargs_underlinedvarargs_strings rrGrG7so&))$HS^c$--6H%HIyyTYY#dmm2D!D!EF%LL)K)KL 57 ))#))+67k7 + se1Z))#))+67 8k ,4??djj * \\#--dll.@.@.BC+,D1N/ & ''%7s *F 0Fchg}|D]*}|js|j|j,|S)z"The list of possible action kinds.)rrErx)r%rI action_groups rrDrDhs<-1ll//01 r0c2djd|DS)zAA help screen string listing the possible action kinds available.rAc3bK|]'}tj|j)ywr)rrr)ractions rrz,_GetPossibleActionsString..ss)4((84s-/r")rIs rrFrFqs 4"24 44r0ctdd}tdd}tdd}tdd }tj|| }|D]\}}t|}t j |r|j || t j|r|j || t j|sw|j || t|ttfr\|rZt|} | d kr2|j d jdt| Dn|j d| dz ||||gS)z8Gets lists of available actions, grouped by action kind.groupr)rxpluralcommandrvaluerindexrr )rxmember , c32K|]}t|ywr)str)rxs rrz+_GetActionsGroupedByKind..s FAQ Fs)rxz0..r\) ActionGrouprVisibleMembersrr IsGroupAdd IsCommandIsValuerylisttupler:r"range) r#rrrrrr member_namer component_lens rrrws* GH 5& i ;( GH 5& WY 7'  % %i A'$2k6k"K6" jjk&j1V$ll Fl36" jjk&j12 D%=)i NMr kktyy F}1E FFkG kk]1_-.k/ (FG ,,r0c6|r|j|}|Sd}|S)z@Returns current command for the purpose of generating help text.r2) GetCommand)rr3r<s rr5r5s. &&:L&MO O r0cftj|dtj|tSNrg)rBoldIndentr9)rxcontents rrrs4ood# $% 7/01 55r0cTttz tz }t||}t j |j }t||}|rd|nd}|t|z }t j|||}djd||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: rrgc3&K|] }|s| ywrrparts rrz!_CreateArgItem..sK4d$Krl) r8r9SUBSECTION_INDENTATIONr}r BoldUnderliner _GetArgTyper:EllipsisTruncater"r{)rrYr&max_str_lengthrQ arg_stringarg_typer>s rrsrss !447MM."37+'' 4* d #($,vhZ "("S]2/!!(O^L  KHk+BKK+ Z5K LLr0c ttz tz }t||}|s+t j |j }d|d|}|r|dz }|r |d} d| d|}t||} t||} | dk(rd| d } | rd | nd } |t| z } t j| | |} | rd | nd } |t| z } t j| | |} d jd| | |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. rjrz (required)rrirNonez Optional[]rrz Default: rgc3&K|] }|s| ywrrrs rrz"_CreateFlagItem..stdrrl) r8r9rr}rrrr_GetArgDefaultr:rr"r{) rXrYr&rTrkrUrrQflag_name_upper short_flagr arg_defaultr>s rrVrVsK0!447MM."48+  **4::<8OtfAo./K = KaJj\K=1K t $(tT*+F8*A&H$,vhZ "("S]2/!!(O^L .9)K=)b+"S%55/!!+O  +{;+ [+6L MMr0c||jvr|j|} |jSy#t$rt|cYSwxYw)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) annotations __qualname__AttributeErrorrepr)rr&rs rrrsU D  $H  " "" (^ s ,AAct|j}|j| d}t||jD]\}}||k(s t |cS||j vrt |j |Sy)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)r:rproziprrW)rXr& num_defaultsrrdefaults rrrs~T]]#,yy,0,dmm<lc7 d{ '] T  ##D) ** r0cD|s|Stj||}|d|Sr)rr)rxrQrms rr{r{-s5  K!!+v6+V  r0c|jr6|jD]'}|j|d|d|fvs|jcSy)N*z**)rorxrQ)rxrYarg_in_docstrings rr}r}5sS*//,   41TFr$["A A+++, r0cg}|jD]\}}tj|}|}|jd}|r"t j |s |j }n>t j |r't j|ttz t}nd}t||}|j||jjt|jj|fS)z>Creates a usage details section for the provided action group.rYN)GetItemsrrrqrr7r=r;r8r9r{rErrrrx)r item_stringsrxrr$rrYr=s rrr=s,"++- ldF   V $D DXX./N#::6B&&g  3 3F ;#.. + 33[Bgg tW %D     # # % \..446 E GGr0c~g}|jD]\}}~tj|jj}d}d|vrH|d}|j r7|j D](}|j |k(st||j}*| t|}|j|dtd|fS)zDCreates a section tuple for the values section of the usage details.NrYVALUESVALUE) rrr __class____init__rorxr{rQrrEr) r#rvalue_item_strings value_namer init_info value_iteminit_docstring_infoarg_infos rrrRs!??, *j% !!)"5"5">">?IJ9$%&67  ! !+00 GH ]]j ($Z1E1EFJ Gz?jj) * &w0BC DDr0ctjtj|}t|dddj |zdS)Nz is one of the following:rgrr\rl)rrrr{r")rxchoicesname_formatteds rrresH??:#7#7#=>.  12 V[[ !!  r0c|r!|j}|j}nd}d}|sd}|}tj|}t j |}t ||}t|} g} | r| jt| t|} t|rft||} | r!| jdj| n|r| j|j| jt!|| r|ddj| zz }||rdndzdz} d |d dj| 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. NFrr rBrAz -- z--helpzUsage: rgz2 For detailed information on this command, run: )rNeedsSeparatingHyphenHyphenrrrrrrDrE_GetPossibleActionsUsageString_UsageAvailabilityLinesr_GetCallableUsageItemsr"rHr|_GetCallableAvailabilityLines)r#rrrneeds_separating_hyphen_hyphencontinued_commandr&r'r%rIrJavailability_linescallable_items help_commands r UsageTextrmsf  G%*%F%F%H"G%*" G  $ $Y /$  # #I .(5YP()@A-78HIJ./FG i+D(;N388N34 5??+;DABuzz-888 1s< &'( . r0c6|rdj|}d|dSy)N|<>r)rI actions_strs rr r s&((+,K {m1  r0cg}|D]E}|jstd|jd|j}|j |G|S)Nz available :)headeritems)r_CreateAvailabilityLinerrrE)r%rravailability_lines rr r s`-3l1l112!4"" 12 3 r0c|jdt|jt|jz }|jt|jt|jz d}|jtj }|s$|Dcgc]}d|d|j }}n|Dcgc]}|j }}|s|js |jr|jd|jr-|jd|jj d|Scc}wcc}w)zBA list of elements that comprise the usage summary for a callable.Nrjrrrr) ror:rprqrrrrrvrwrErt)r&r'r~rrrrs rr r s ))$HS^c$--6H%HIyyTYY#dmm2D!D!EF%LL)K)KL - /#a } % /E /%: :SSYY[ :E :4??djj LL \\ LL1T\\'')*$/0 , / ;s D9:D>c2fdjDS)Nc3DK|]}|jvk7r|ywr)rW)rrXrTr&s rrz(_KeywordOnlyArguments..s+ 84 $$"5"55 6  8s )rv)r&rTs``r_KeywordOnlyArgumentsr!s 84?? 88r0c|jt|jt|jz d}tj|t |dDcgc]}d| }}t |dDcgc]}d| }}g}|r|j td|d|r|j td |d|jr%|s|rd nd }|j t|gd|Scc}wcc}w) zHThe list of availability lines for a callable for use in a usage string.NF)rTrjTzoptional flags:r)rr header_indentzrequired flags:zadditional flags are acceptedzflags are accepted) ror:rp itertoolschainr!rErrw)r&rrXoptional_flagsrequired_flagsradditional_flagss rr r s(yyTYY#dmm2D!D!EF-6OO/uE-GHDbKH.H4D4H4&k. '8./ 12'8./ 12 ZZ)^8,'7r./ 12 /Hs  C:9 C?c||z }djtj||}tj||}tj||}||t |dzdzS)Nrg)width)spaces)r"r WrappedJoinrr:) rrr# items_indent line_length items_width items_textindented_items_textindented_headers rrrsll*+yy//[IJ*"))*\J%%f]C/ .s?/C/DE E LLr0c$eZdZdZdZddZdZy)rz$A group of actions of the same kind.c<||_||_g|_g|_yr)rxrrr)selfrxrs rrzActionGroup.__init__sDIDKDJDLr0Ncp|jj||jj|yr)rrEr)r6rxrs rrzActionGroup.Add s&JJdLLr0cBt|j|jSr)rrr)r6s rrzActionGroup.GetItemss tzz4<< ((r0r)__name__ __module__r__doc__rrrrr0rrrs,  )r0r)NFr)F)NT)FNF)r)T)/r;r]r$firerrrrrrr r8r9rr/rrrrZrdr r!r6rPrGrDrFrr5rrsrVrrr{r}rrrrr r r r!r rrrr0rr=s"$ +\, 08 ?]1@"D L .(b4 -65 MB:?05;N| . .G*E&9x 08 @+,"(3M))r0