o X@sdZddlmZddlmZddlmZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZddlmZddlmZdd lmZdd lmZddlZd Zd Zd ZdZGdddeZGdddeZGdddejZddZ dMddZ!dNddZ"ddZ#ddZ$Gd d!d!e j%Z&dde&j'd"fd#d$Z(d%d&Z)d'd(Z*d)d*Z+dOd+d,Z,d-d.Z-d/d0Z.d1d2Z/d3d4Z0d5d6Z1    "   " dPd7d8Z2dMd9d:Z3Gd;d<dZ5e j6fd?d@Z7dAdBZ8dCdDZ9dEdFZ:dGdHZ;dIdJZrsz5TextChoiceSuggester.GetSuggestion..r cs"g|] }t|dkr|qSrr(r+matchrrr.us"r)rdifflibget_close_matcheslower)rargr#rr0r GetSuggestiones  z!TextChoiceSuggester.GetSuggestionr)rrrrrr r'r6rrrrr?s   rc@s eZdZdS)ArgumentWrapperN)rrrrrrrr7zsr7cCstdtjdtj|S)Nz(\b[a-zA-Z][-a-zA-Z_0-9]*)z\1)resubrMARKDOWN_ITALIC)msgrrr_ApplyMarkdownItalic~s r<FcCsz|jp|j}|rt|}|jdkrdj|dS|jdkr$dj|dS|jtjkr0dj|dS|jdkr;dj|dS|S) zCreate the usage help string for a positional arg. Args: arg: parser_arguments.Argument, The argument object to be displayed. markdown: bool, If true add markdowns. Returns: str, The string representation for printing. +z{var} [{var} ...])var*z [{var} ...]z[-- {var} ...]?z[{var}])metavardestupperr<nargsformatargparse REMAINDER)r5markdownr>rrrGetPositionalUsages         rIcCs|dur |jp |j}|r|drdnd}t|jtjr*|jt |j|p)|}|dkr0dS|r6t |}|dkr@||}d}|j dvrMd|d}d}||S) z-Returns a usage-separator + metavar for flag.N--= r)r@r?[]) rArBrC startswith isinstancetyper ArgTypeUsageGetUsageMetavarboolr<rD)flagrAnamerH separatorrrr_GetFlagMetavars   rXcCs2t|}|drd|vrd|ddd}|S)z0Returns value quoted, with preference for "...".'"r )reprrO)valuequotedrrr _QuoteValuesr_cCs|S)zMockable flag name list filter.r)namesrrr_FilterFlagNamessrac@seZdZdZdZdZdS) InvertedValuerr N)rrrNORMALINVERTEDBOTHrrrrrbsrbTc Cs|tjurddt|jD}n|tjur ddt|jD}nt|j}t|}|jp0|j}|r5|r^z|d}Wn t yFd}Ynw|rN|j dkrP|St |||d}dj ||dS|j dkrx|rqd d d|D} | Sd |} | Sg} |D] } t ||| |d }| d j |rtjnd| |rtjnd|d q|d | } |jrt|dt|ddst|jtrd |j} nt|jtrd ddtt|jD} n|j} t| } |rtdtjtjtjd| rd | } | d | 7} | S)a=Returns the usage string for a flag arg. Args: arg: parser_arguments.Argument, The argument object to be displayed. brief: bool, If true, only display one version of a flag that has multiple versions, and do not display the default value. markdown: bool, If true add markdowns. inverted: InvertedValue, If INVERTED display the --no-* inverted name. If NORMAL display the normal name. If BOTH, display both. value: bool, If true display flag name=value for non-Boolean flags. Returns: str, The string representation for printing. cSg|] }|dddqS)rJz--[no-]r replacer,xrrrr.z GetFlagUsage..cSrg)rJ--no-r rhrjrrrr.rlrrrVz{flag}{metavar})rUrA, cSsg|] }tj|tjqSr)r MARKDOWN_BOLDrjrrrr.s)rVrHz{bb}{flag}{be}{flag_metavar})bbrUbe flag_metavar is_requiredrequiredF,cSsg|] \}}d||qS)z{0}={1}rE)r,kvrrrr.s rMrNz```{}```z ; default={0})rbrfsortedoption_stringsrerarArBrC IndexErrorrDrXrEjoinappendrrpdefaultgetattrrPlistdictr) iteritemsr_r8searchr: MARKDOWN_CODE)r5briefrHinvertedr]r`rA long_stringrsusage usage_listrVr default_textrrr GetFlagUsagesn       % !        rcCs|jddddS)z(Returns the inverted flag name for flag.rrJrmr )r{ri)rUrrr_GetInvertedFlagNamesrcCs|r|dr |S|dS)N.)endswith) help_messagerrr _PunctuatesrcCsl||vr|S|d}r||ddkr|d|dS|ddkr-t|d|St|d|S)z-Appends extra_help_message into help_message. r rL r)rfindr)rextra_help_message newline_indexrrr_AppendExtraHelpsrc s(t|d|j}t|r|}|rt|nd}|jr|S|js"|jr'd}dn(|jr4|j}t|dgnz|j j}Wn t yGd}dYnwt|j dgg}t |dr~|j \}}}t ||vr}|d||jr}|jdvr}|dt|n.|js|js|jrn$|jd ur|d t|nt|tjr|d |jd t||r7|jp|j}|d kr7t|d|}t|tdkrd} nd} t|tr"t |} t|tjst | } g}| D]\} } | vrqt| } dj| | d|t!d}||q|d|t!|dj|| d"|dn|dj|| d"fdd|Ddt|dd}t|t#j$ro|jrM|jd nd}|oVt%&|}|j j'||j(|d}|ro|t#)||t*d "|}|+}|r|rt,||}n|r|}n|}|-dd.S) z.rQ) field_nameru flag_namerz + )/rhelpcallabletextwrapdedentris_group is_positionalr!rQAttributeErrorhasattrrr)r*r~rErrDrrPrStoreTrueFalseActionr{rArBrClenrr collections OrderedDictrz_CHOICE_OFFSETr}rrR format_utilNamespaceFormatGetUsageHelpTextrtIndentAsciiDoc_ARG_DETAILS_OFFSETrstriprristrip)r5rrrr! extra_helpprop_rArchoices_iteritemsrVr dedented_desc choice_helparg_typearg_namertype_help_textr stripped_helpall_helprrr GetArgDetails1s                      rcCs8|jrdS|jr dS|jr|jD] }t|rdSqdS)zHReturns True if arg is a positional or group that contains a positional.FT)rrr arguments _IsPositional)r5arrrrs rcCsp|sdS|drd|dddfS|drd|ddfS|d r,d |d dfS|d r4d Sd|fS)z.Arg name usage string key function for sorted.)rrrmr NrkrJrc-r rr r)rOisalpharnrrr_GetArgUsageSortKeys    rcCsnd}|jD]}|jr q|jrt|}|sdS|rdS|}q|r5t|ts5|j|jkr5t|}|j|_|S)zt |ddr>t j} nt j} t|||| |d} | rU|rU|jsUt| } | S|jr\dnd} g} g}g}|durmd }g}nd}|jryt|jtd n|j}|D]Y}|jr|sq~|jrt|} | r| }|js|jtjkr|t||||d q~t|r| |q~t||||d } | sq~|jr| |vr|| q~|rt| } | |vr|| q~g}g}d }d}| rd }| D]&}t|||d } | sq|jsd }| }t| } | |kr|d7}|| q|rd|dd||d<|r(|| ||rS|rH|s?| r7|r:|r?|d|| |n |rS|rS|d|r_|t|td }n||}|rq|rq|d|d|} |jrd| S|st|dkrt| } | S)aReturns the argument usage string for arg or all nested groups in arg. Mutually exclusive args names are separated by ' | ', otherwise ' '. Required groups are enclosed in '(...)', otherwise '[...]'. Required args in a group are separated from the optional args by ' : '. Args: arg: The argument to get usage from. brief: bool, If True, only display one version of a flag that has multiple versions, and do not display the default value. definition: bool, Definition list usage if True. markdown: bool, Add markdown if True. optional: bool, Include optional flags if True. top: bool, True if args is the top level group. remainder_usage: [str], Append REMAINDER usage here instead of the return. value: bool, If true display flag name=value for non-Boolean flags. hidden: bool, Include hidden args if True. Returns: The argument usage string for arg or all nested groups in arg. r)rHinverted_synopsisF)rrHrr] | rLNTkey)rHr]rr)rHrr z{}{}r[rNrz[optional flags]z({}))rrrrDrFrGrrIrPrrrbrfrrerdrrtris_mutex sort_argsrzrrr~rrrEr}rr)r5r definitionrHoptionaltopremainder_usager]rrrrseppositional_argsrequired_usageoptional_usageinclude_remainder_usagerrpositional_usageall_other_usagenestingoptional_positionals usage_orig all_usagerrrrs                 rcs:tr ddfdd |ttdS) zReturns the list of all flags in arg. Args: arg: The argument to get flags from. optional: Do not include required flags if True. Returns: The list of all/optional flags in arg. --helprTcs|jrdS|jr |r|r|j}|jD] }||d|dqdSt|dd}|r*|}|jrF|jsH|jsJr:|r:|jsLt |jddSdSdSdSdS)z%GetFlags() helper that adds to flags.Nr )levelru show_invertedr) rrrtrrr{r is_globaladdrz)r5rrur_GetFlagsHelperflagsrrrrs2  z!GetFlags.._GetFlagsHelperrN)rT)setrrzr)r5rrrrGetFlagss    rc@r)SectionzA positional/flag section. Attribute: heading: str, The section heading. args: [Argument], The sorted list of args in the section. cCs||_||_dSr)headingr)rrrrrrrs zSection.__init__Nrrrrrrs rc stt}t}|s|rdh}|D]s}|jrqt|r/d}|vr'g|<||q|jrX|sX|jr:|jn|gD]}|j rV|jsV|j d} |sV| drV| | q=q|j r^d}nt |ddped}t|d rw|j|vrqq| |j|vrg|<||qg} |rd ntj|rdddgtfd d Dnddgfd d Dfdd} D]}|vrq| t| |t||dq| |fS)aReturns the positional/flag sections in document order. Args: arguments: [Flag|Positional], The list of arguments for this command or group. is_root: bool, True if arguments are for the CLI root command. is_group: bool, True if arguments are for a command group. sort_top_level_args: bool, True if top level arguments should be sorted. Returns: ([Section] global_flags) global_flags - The sorted list of global flags if command is not the root. rzPOSITIONAL ARGUMENTSrrJREQUIREDcategoryNOTHERrBGLOBALcg|]}|vr|qSrrr+initial_categoriesrrr. sz"GetArgSections..crrrr+rrrr.scsf|dkr%ttdgrd}|Svrd}|Sdvr!d}|Sd}|Sd|vs-d|vr/|S|dS)z4Returns the arg section heading for an arg category.rFLAGSz OTHER FLAGSrzOPTIONAL FLAGS ARGUMENTSz FLAGS)r)rother_flags_heading) categoriescommonremaining_categoriesrr_GetArgHeadingsz&GetArgSections.._GetArgHeading)rr)rrrrrr~rrrr{rOrrtrrrBrCOMMONLY_USED_FLAGSrzrr7) ris_rootrsort_top_level_argsdests global_flagsr5rrrUsectionsrr)rrrrrGetArgSectionsst             r csfddfdd}d|dtjd||d|d d d d }t||t|d krI|d||fd|d||dSd||f|d|t|t|dd|fdS)aHelper function that does two-column writing. If the first column is too long, the second column begins on the next line. Args: prefix: str, Text for the first column. message: str, Text for the second column. indent: int, Width of the first column. length: int, Width of both columns, added together. spacing: str, Space to put on the front of prefix. writer: file-like, Receiver of the written output. cs|dSr)writes)writerrrWDszWrapWithPrefix..Wcs|ddS)Nrrr)rrrWlnGszWrapWithPrefix..Wlnz %%%dsrLF)break_on_hyphenswidthrz&| z&|z |rcz%s%sz%%%dsz %%%ds %%sr N)r}r TextWrapperwraprir)prefixmessageindentlengthspacingrrr)rrrWrapWithPrefix6s&     "rcsd}tdkoddk}|rdnd}t}|dg}|s9|t|dddd  } }t fd d t |D} t fd d t |D} g} | rf| d | rm| || sq| r~|dd| d} nt|dd} d|} dj|d}||| d| rtdd| ttd|d| rtd|d| ttd|d| rtdd| ttd|d|dt|S)a1Return the command Usage string. Args: command: calliope._CommandCommon, The command object that we're helping. argument_interceptor: parser_arguments.ArgumentInterceptor, the object that tracks all of the flags for this command or group. Returns: str, The command usage string. rLrcr topiccommandzUsage: TF)rrrc3&|]\}}s |js|VqdSrIsHiddenrr,rV help_inforrr  zGetUsage..c3rrr r"r$rrr%r&groupz<%s>rN)rz {command} r$rz group may bez )rrz %s may bezoptional flags may be)LoadAllSubElementsr}GetPathrioStringIOr r~rGetSubGroupHelpsGetSubCommandHelpsrzr)rrrEr HELP_INDENT LINE_WIDTH GetHelpHintgetvalue)rargument_interceptor command_pathr command_idbuf usage_parts group_helps command_helpsgroupscommands all_subtypesoptional_flags usage_msg non_optionrr$rGetUsagegsx            r?csfddfdd}fdd}||sdSt}|vr%||||vr/||||S)aConstructs an alternative Usage markdown string organized into categories. The string is formatted as a series of tables; first, there's a table for each category of subgroups, next, there's a table for each category of subcommands. Each table element is printed under the category defined in the surface definition of the command or group with a short summary describing its functionality. In either set of tables (groups or commands), if there are no categories to display, there will be only be one table listing elements lexicographically. If both the sets of tables (groups and commands) have no categories to display, then an empty string is returned. Args: command: calliope._CommandCommon, The command object that we're helping. categories: A dictionary mapping category name to the set of elements belonging to that category. Returns: str, The command usage markdown string organized into categories. r command_groupc s&d}t||dkrtj||vrd}|d|djd|dddtt ||D]Z\}}|sE|d j|d |d t|d d dD]=}d}|j dkrc|j dd}n|j dkrp|j dd}n|j dkr}|j dd}n|j }|dj|j dd|dqRq6dS)z=Writes the markdown string to the buffer passed by reference.Fr Trz!# Available {type}s for {group}: rLr)rQr'z ### {category} )r---------------------- | --- cS|jSrrnerrrzJGetCategoricalUsage.._WriteTypeUsageTextToBuffer..rNalpha beta preview {name} | {description} rrV description)rrUNCATEGORIZED_CATEGORYr rEr}splitr)rzr)rrV short_helpri)r5rkey_namesingle_category_is_otherrelementselementrRr$rr_WriteTypeUsageTextToBuffers>      z8GetCategoricalUsage.._WriteTypeUsageTextToBuffercsT|s|sdStt|t|ttjgkr(dSdS)zQEnsures the categorization has real categories and is not just all Uncategorized.FT)keysrrrrP)r)command_group_key command_keyrr_ShouldCategorizes   z.GetCategoricalUsage.._ShouldCategorizer)r*r+r1)rrrWr[r5r)rrYrZrGetCategoricalUsages #  r\cCsl|dj|d|d|dt|dddD]}|r#q|dj|jd d |jd qd S) aZHelper method to GetUncategorizedUsage(). The elements are written to a markdown table with a special heading. Element names are printed in the first column, and help snippet text is printed in the second. No categorization is performed. Args: command: calliope._CommandCommon, The command object that we're helping. elements: an iterable over backend.CommandCommon, The sub-elements that we're printing to the table. element_type: str, The type of elements we are dealing with. Usually 'groups' or 'commands'. writer: file-like, Receiver of the written output. z(# Available {element_type} for {group}: rL) element_typer'rAcSrBrrnrCrrrrE+rFz*_WriteUncategorizedTable..rrMrrrNN) r rEr}r)rzr!rVrirR)rrUr]rrVrrr_WriteUncategorizedTables r^cCsNt}|jrt||jd||jr#|dt||jd||S)aConstructs a Usage markdown string for uncategorized command groups. The string is formatted as two tables, one for the subgroups and one for the subcommands. Each sub-element is printed in its corresponding table together with a short summary describing its functionality. Args: command: calliope._CommandCommon, the command object that we're helping. Returns: str, The command Usage markdown string as described above. r9rr:)r*r+r9r^valuesr:r r1)rr5rrrGetUncategorizedUsage5s  r`cCsdjd|dS)NzUFor detailed information on this command and its flags, run: {command_path} --help rL)r3)rEr}r)r$rrrr0Osr0cCs|rW|}dd|D}z"|d}d|d|}d||dd}t|}WntyAd|}d}Ynw|sQd||dd}||pU|fSdS) aExtracts short help and long help from a docstring. If the docstring contains a blank line (i.e., a line consisting of zero or more spaces), everything before the first blank line is taken as the short help string and everything after it is taken as the long help string. The short help is flowing text with no line breaks, while the long help may consist of multiple lines, each line beginning with an amount of whitespace determined by dedenting the docstring. If the docstring does not contain a blank line, the sequence of words in the docstring is used as both the short help and the long help. Corner cases: If the first line of the docstring is empty, everything following it forms the long help, and the sequence of words of in the long help (without line breaks) is used as the short help. If the short help consists of zero or more spaces, None is used instead. If the long help consists of zero or more spaces, the short help (which might or might not be None) is used instead. Args: docstring: The docstring from which short and long help are to be taken Returns: a tuple consisting of a short help string and a long help string cSsg|]}|qSr)r)r,rrrrr.rsz&ExtractHelpStrings..rrLNrr )rr) splitlinesindexr}rrr ValueError) docstringunstripped_doc_linesstripped_doc_linesempty_line_indexrR raw_long_help long_helprrrExtractHelpStringsVs    rj)F)NNFr/)FFFTFNTF)>r __future__rrrrFrrr2enumr*r8sysrgooglecloudsdk.callioperrrr googlecloudsdk.calliope.conceptsr rr)r/r.rrobjectrrArgumentr7r<rIrXr_raEnumrbrdrrrrrrrrrrrrrr stdoutrr?r\r^r`r0rjrrrrs~        ;    L }    * g1[T