U +cm@sdZddlmZddlmZddlmZddlZddlZddlZddlm Z ddlm Z ddlm Z dd lm Z dd lm Z dd lmZdd lmZd ZdZdZdUddZdVddZdWddZddZddZddZddZddZd d!Zd"d#Zd$d%Zd&d'Zd(d)ZdXd*d+Z dYd-d.Z!d/d0Z"d1d2Z#dZd3d4Z$d5d6Z%d7d8Z&d[d:d;Z'dd?Z)d@dAZ*dBdCZ+d\dDdEZ,dFdGZ-dHdIZ.dJdKZ/d]dLdMZ0dNdOZ1d9dPefdQdRZ2GdSdTdTe3Z4dS)^aUtilities 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. )absolute_import)division)print_functionN) completion)custom_descriptions) decorators) docstrings) formatting) inspectutils) value_typesPFcCst|}t||d}t|}t|}t||||d}t|||||d}t||} t |rpt |||\} } ng} g} t ||} ||| g| | | } d dd| 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 css|]}|dk rt|VqdSN)_CreateOutputSection).0sectionr1/tmp/pip-unpacked-wheel-1xt1w7un/fire/helptext.py ]szHelpText..) r Info_GetActionsGroupedByKindGetFullArgSpecr GetMetadata _NameSection_SynopsisSection_DescriptionSectioncallable_ArgsAndFlagsSections_UsageDetailsSectionsjoin) componentrrinfoactions_grouped_by_kindspecmetadataZ name_sectionZsynopsis_sectionZdescription_sectionargs_and_flags_sectionsnotes_sectionsZusage_details_sectionssectionsrrrHelpText5sF       r,cCs^t||d}t|}t|r@ttt|d}t||t}|rR|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_spacetextrrrrcs   rc Cst|dd}t|}g}|r*|t|t|r\t||}|rL||n|r\||jd|} d} | j|| d} d| fS)z*The "Synopsis" section of the help string.T)rr. | z {current_command} {continuation})r7 continuationZSYNOPSIS) r0_GetPossibleActionsappend_GetPossibleActionsStringr _GetArgsAndFlagsString separatorr#format) r$r&r'r(rr7possible_actions continuationsZcallable_continuationr<Zsynopsis_templater:rrrrxs$     rcCs`t|r0tt}t||t}t||t}nt|}t|}|pJ|pJd}|rXd|fSdSdS)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. NZ DESCRIPTION)rr2r3r4ZGetDescriptionr6_GetDescriptionr1)r$r%r9 descriptionr8r:rrrrs  rcCst|||||jk|dS)Nrequired short_arg)_CreateFlagItemkwonlydefaults)flagdocstring_infor'rIrrr_CreateKeywordOnlyFlagItemsrNcs*dd|D}t|fdd|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. cSsg|] }|dqS)rrrfrrr sz"_GetShortFlags..csg|]}|dkr|qS)r)rvZshort_flag_countsrrrQs ) collectionsCounter)flagsZ short_flagsrrTr_GetShortFlagss  rXcsHjdtjtj}jtjtjd}|tj}g}g}|dfdd|D}jr|tj|r|rdnd} | d | df} || |r|r|dt |fd d|D} t j fd dj D} | | } j r"g}d }d }jp,g}d d|D}t |}|D]f}t|tjrH|jd|kr|j|j|jdd}n|j|jd}t|j|d}||qH|r| rd}t|ddd}| || |tj }|rd}n| rd}nd}t||dd}| || r@dd | f}||||fS)z1The "Args and Flags" sections of the help string.NrMcsg|]}t|qSr)_CreateArgItemrarg)rMr'rrrQsz)_ArgsAndFlagsSections..zPOSITIONAL ARGUMENTSZ ARGUMENTS )ZNOTESz6You can also use flags syntax for POSITIONAL ARGUMENTSc s&g|]}t|d|dkdqS)FrrG)rJrrL)rMr'unique_short_argsrrrQs cs$g|]}t||dkdqS)r)rI)rNr])rMr'unique_short_kwonly_flagsrrrQs z--{name}z-{short_name}, --{name}cSsg|] }|jqSrnamerOrrrrQsr)raZ short_namer`) flag_stringz&The following flags are also accepted.r indentz3Additional undocumented flags may also be accepted.zAdditional flags are accepted.zFlags are accepted.FLAGS)argsr5defaultsgetrACCEPTS_POSITIONAL_ARGSvarargsr>rYr#rstriprX kwonlyargsvarkw isinstancerZ KwargInforarBrJ _CreateItemextend_GetArgDescription)r%r'r(args_with_no_defaultsargs_with_defaultsaccepts_positional_argsr)r*Z arg_itemstitleZarguments_sectionZpositional_flag_itemsZkwonly_flag_itemsZ flag_itemsZdocumented_kwargsrbZshort_flag_stringrWZ flag_namesZunique_short_flagsrLZ flag_itemmessageitemrFZ flags_sectionr)rMr'r^r_rr!s            r!cCsn|\}}}}g}|jr$|t||jr8|t||jrN|t|||jrj|dtd|jf|S)z.The usage details sections of the help string.ZINDEXESZINDEX)membersr>_MakeUsageDetailsSection_ValuesUsageDetailsSection_NewChoicesSectionnames)r$r&groupscommandsvaluesindexesr+rrrr"(s r"cCs|d}|jr|jSdSNrM)r8r%rMrrrr19sr1cCs|d}|jr|jSdSr)rFrrrrrE>srEcCs|jdt|jt|j}|jt|jt|jd}|tj}g}|r||rddd|D}ndd|D}|||s|js|jr| d|j rdj t |j 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. NcSsg|]}t|qSrr UnderlineupperrZrrrrQ_sz*_GetArgsAndFlagsString..cSs$g|]}dj|t|dqS)z--{arg}={arg_upper})r[Z arg_upper)rBr rrrZrrrrQbs  [{varargs}]...rj )rfr5rgrhrrirprlrmr>rjrBr rrr#)r'r(rrrsrtZarg_and_flag_strings arg_stringsZvarargs_stringrrrr@Cs*    r@cCs$g}|D]}|jr||jq|S)z"The list of possible action kinds.)rxr>ra)r&rC action_grouprrrr=ts r=cCsddd|DS)zAA help screen string listing the possible action kinds available.r;css|]}t|VqdSrr)ractionrrrrsz,_GetPossibleActionsString..)r#rCrrrr?}s r?c Cstddd}tddd}tddd}tdd d}tj||d }|D]X\}}t|}t|rj|j||d t|r|j||d t|rB|j||d qBt |t t fr|rt |} | d kr|jd ddt| Ddn|jdj| ddd||||gS)z8Gets lists of available actions, grouped by action kind.groupr})rapluralcommandr~valuerindexrr)ramember z, css|]}t|VqdSr)str)rxrrrrsz+_GetActionsGroupedByKind..r`z0..{max}rR)max) ActionGrouprZVisibleMembersrr ZIsGroupAddZ IsCommandZIsValuernlisttupler5r#rangerB) r$rr}r~rrrx member_namerZ component_lenrrrrs&        "rTcCs|r|j|d}nd}|S)z@Returns current command for the purpose of generating help text.r-) GetCommand)rr.r7rrrr0sr0cCsdjt|t|tdS)Nz{name} {content}racontent)rBr BoldIndentr4rrrrrs rcCsttt}t||}t|}t||}|r.rc) r3r4SUBSECTION_INDENTATIONrqr Z BoldUnderliner _GetArgTyperBr5EllipsisTruncater#ro)r[rMr'max_str_lengthrF arg_stringarg_typer9rrrrYs     rYc Csttt}t||}|s6d}|j|t|d}|rB|d7}|rZdj|dd|}t||} t ||} | dkrd| } | rd | nd } |t | } t | | |} | rd | nd } |t | } t | | |} d d d| | |fD}t ||tdS)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. z--{flag_name}={flag_name_upper})Z flag_nameZflag_name_upperz (required)z-{short_flag}, r)Z short_flagNonez Optional[{}]rrz Default: {}r\css|]}|r|VqdSrrrrrrrsz"_CreateFlagItem..rc)r3r4rrqrBr rrr_GetArgDefaultr5rr#ro) rLrMr'rHrbrIrrFZflag_string_templaterZ arg_defaultr9rrrrJs8           rJcCsX||jkrT|j|}z"tjdddkr0|jWS|jWStk rRt|YSXdS)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)rr) annotationssys version_info __qualname____name__AttributeErrorrepr)r[r'rrrrrs  rcCs`t|j}|j| d}t||jD]\}}||kr&t|Sq&||jkr\t|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)r5rgrfziprrK)rLr' num_defaultsrsr[defaultrrrr's  rrcCs|s|Sdj|t||dS)Nz{name} {description})rarF)rBr r)rarFrdrrrro>s  rocCs8|jr4|jD]&}|j|d|d|fkr |jSq dS)N*z**)rfrarF)rarMZarg_in_docstringrrrrqFs   rqcCsg}|D]l\}}t|}|}|d}|rBt|sB|j}n"t|r`t|tt t}nd}t ||}| |q |j t|j |fS)z>Creates a usage details section for the provided action group.rMN)GetItemsr rrhrr2r8r6r3r4ror>rrr{ra)rZ item_stringsrarr%rwrMr8rrrryNs*     ryc Csg}|D]n\}}~t|jj}d}d|kr`|d}|jr`|jD]}|j|krDt||j}qD|dkrpt |}| |q dt d|fS)zDCreates a section tuple for the values section of the usage details.NrMZVALUESZVALUE) rr r __class____init__rfrarorFrr>r{) r$rZvalue_item_stringsZ value_namerZ init_infoZ value_itemZinit_docstring_infoZarg_inforrrrzcs   rzcCs,tdjtt|ddd|ddS)Nz{name} is one of the following:r`r\rrRrc)rorBr rrr#)rachoicesrrrr{vs r{cCsd}|r|}|}nd}d}|s*d}|}t|}t|}t||d} t| } g} | rl| t | t | } t |rt ||} | r| d | n|r| |j| t|| r|dd | 7}||rdndd }|j|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. zoUsage: {continued_command} {availability_lines} For detailed information on this command, run: {help_command}NFrrrr;z -- z--help)continued_commandavailability_lines help_command)rZNeedsSeparatingHyphenHyphenr rrrrr=r>_GetPossibleActionsUsageString_UsageAvailabilityLinesr _GetCallableUsageItemsr#rArp_GetCallableAvailabilityLinesrB)r$rrZoutput_templaterZneeds_separating_hyphen_hyphenrr'r(r&rCrDrZcallable_itemsrrrr UsageText~sJ        rcCs|rdjd|dSdS)Nz <{actions}>|)actions)rBr#rrrrrsrcCs:g}|D],}|jrtdj|jd|jd}||q|S)Nzavailable {plural}:)r)headeritems)rx_CreateAvailabilityLinerBrr|r>)r&rrZavailability_linerrrrs  rcCs|jdt|jt|j}|jt|jt|jd}|tj}|s\dd|D}ndd|D}|sz|jsz|jr|d|j r|dj |j d|S)zBA list of elements that comprise the usage summary for a callable.NcSsg|]}dj||dqS)z--{arg}={upper})r[r)rBrrZrrrrQsz*_GetCallableUsageItems..cSsg|] }|qSr)rrZrrrrQsrrr) rfr5rgrhrrirlrmr>rjrBr)r'r(rrrsrtrrrrrs  rcsfddjDS)Nc3s |]}|jkkr|VqdSr)rKr]rHr'rrrsz(_KeywordOnlyArguments..)rl)r'rHrrr_KeywordOnlyArgumentssrcCs|jt|jt|jd}ddt|t|ddD}ddt|ddD}g}|rn|td|d d |r|td |d d |jr|s|rd nd }|t|gd d |S)zHThe list of availability lines for a callable for use in a usage string.NcSsg|] }d|qSz--rr]rrrrQsz1_GetCallableAvailabilityLines..F)rHcSsg|] }d|qSrrr]rrrrQsTzoptional flags:r)rr header_indentzrequired flags:zadditional flags are acceptedzflags are accepted) rfr5rg itertoolschainrr>rrm)r'rsZoptional_flagsZrequired_flagsrZadditional_flagsrrrrsD   rc CsP||}dtj||d}tj||d}tj||d}||t|ddS)Nr\)width)spaces)r#r Z WrappedJoinrr5) rrrZ items_indentZ line_lengthZ items_widthZ items_textZindented_items_textZindented_headerrrrr s rc@s*eZdZdZddZd ddZddZdS) rz$A group of actions of the same kind.cCs||_||_g|_g|_dSr)rarr|rx)selfrarrrrrszActionGroup.__init__NcCs|j||j|dSr)r|r>rx)rrarrrrr s zActionGroup.AddcCst|j|jSr)rr|rx)rrrrr$szActionGroup.GetItems)N)r __module__r__doc__rrrrrrrrs r)NF)NF)N)F)NT)FNF)r)NF)T)5r __future__rrrrUrrZfirerrrrr r r r3r4rr,rrrrNrXr!r"r1rEr@r=r?rr0rrYrJrrrorqryrzr{rrrrrrrobjectrrrrrsp           .  c1   ! ?  A