|ha dZddlZddlZddlZddlZGddej ddZdeejzej_ Gddej dd Z dee jze j_ Gd d e Z dee jze j_ Gd d e ZGddejZGddejZej$dej&dej(dej*dej,diZdZdZdZdZd0dZdZdZdZdZ d Z!d!Z"d"Z#d#Z$d$Z%d%Z&d&Z'd'Z(d(Z)d)Z*d*Z+d+Z,d,Z-d-Z.d.Z/d/Z0y)1aKDocstring parsing module for Python Fire. The following features of docstrings are not supported. TODO(dbieber): Support these features. - numpy docstrings may begin with the function signature. - whitespace may be important for proper structuring of a docstring - I've seen `argname` (with single backticks) as a style of documenting arguments. The `argname` appears on one line, and the description on the next. - .. Sphinx directives such as .. note:: are not understood. - After a section ends, future contents may be included in the section. E.g. :returns: This is what is returned. Example: An example goes here. - @param is sometimes used. E.g. @param argname (type) Description @return (type) Description - The true signature of a function is not used by the docstring parser. It could be useful for determining whether something is a section header or an argument for example. - This example confuses types as part of the docstrings. Parameters argname : argtype Arg description - If there's no blank line after the summary, the description will be slurped up into the summary. - "Examples" should be its own section type. aka "Usage". - "Notes" should be a section type. - Some people put parenthesis around their types in RST format, e.g. :param (type) paramname: - :rtype: directive (return type) - Also ":rtype str" with no closing ":" has come up. - Return types are not supported. - "# Returns" as a section title style - ":raises ExceptionType: Description" ignores the ExceptionType currently. - "Defaults to X" occurs sometimes. - "True | False" indicates bool type. Nc eZdZy) DocstringInfoN__name__ __module__ __qualname__N/var/www/html/test/engine/venv/lib/python3.12/site-packages/fire/docstrings.pyrr:r r)summary descriptionargsreturnsyieldsraisesNc eZdZy)ArgInfoNrr r r rrBr r rnametyperc eZdZy) KwargInfoNrr r r rrJsr rc"eZdZdZdZdZdZy) Namespacez4A dict with attribute (dot-notation) access enabled.c.||vr t||<||Sr)rselfkeys r __getattr__zNamespace.__getattr__Rs $+d3i 9r c|||<yrr )rr values r __setattr__zNamespace.__setattr__Ws DIr c||vr||=yyrr rs r __delattr__zNamespace.__delattr__Zs d{ s)r N)rrr__doc__r!r$r&r r r rrOs< r rc eZdZdZdZdZdZdZy)SectionsrN)rrrARGSRETURNSYIELDSRAISESTYPEr r r r)r)_s $ ' & & $r r)ceZdZdZdZdZy)Formatsrr*r+N)rrrGOOGLENUMPYRSTr r r r4r4gs & % #r r4)argumentarg parameterparamr )return)yield)raiseexcept exceptionthrowerrorwarn)rc | tS|jjd}t|}t }d|j _d|j _d|j _d|j _ d|j_ g|j_ g|j_ g|_g|_d|_g|j"_ g|j$_ g|j&_ t)|D]A\}}|dz|k}|dkDr||dz nd}|r||dznd}t+|||} t-| |C|jjr%dj/|jjnd} t1|jj|j_ t3j4dj/|jj} | sd} t7|j"j} t7|j$j} t7|j&j}|jDcgc]]}t9|j:t=t7|j>jt7|jj_}}|jA|jDcgc]]}tC|j:t=t7|j>jt7|jj_c}t| | |xsd| || Scc}wcc}w) a Returns DocstringInfo about the given docstring. This parser aims to parse Google, numpy, and rst formatted docstrings. These are the three most common docstring styles at the time of this writing. This parser aims to be permissive, working even when the docstring deviates from the strict recommendations of these styles. This parser does not aim to fully extract all structured information from a docstring, since there are simply too many ways to structure information in a docstring. Sometimes content will remain as unstructured text and simply gets included in the description. The Google docstring style guide is available at: https://github.com/google/styleguide/blob/gh-pages/pyguide.md The numpy docstring style guide is available at: https://numpydoc.readthedocs.io/en/latest/format.html Information about the rST docstring format is available at: https://www.python.org/dev/peps/pep-0287/ The full set of directives such as param and type for rST docstrings are at: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html Note: This function does not claim to handle all docstrings well. A list of limitations is available at the top of the file. It does aim to run without crashing in O(n) time on all strings on length n. If you find a string that causes this to crash or run unacceptably slowly, please consider submitting a pull request. Args: docstring: The docstring to parse. Returns: A DocstringInfo containing information about the docstring. N Tr*r r)r rrrrr)"rstripsplitlenrsectiontitle indentationline1_indentationformatr permittedlinesrrkwargs current_argrrr enumerate_create_line_info _consume_linejoin_strip_blank_linestextwrapdedent _join_linesrr_cast_to_known_typerextendr) docstringrP lines_lenstateindexlinehas_next previous_line next_line line_infor rrrrr9rs r parserfvsJ ? //  ! !$ '%%j) +%%--"%--$(%--!%-- %--%--%%*%,%%--%,,%,,u%$keTqy9$H(- E%!)$tM$,eai $I!$ =AI)U# $.3]]-@-@CHHU]](( )d'.u/@/@/F/FG% %*;*;*A*A BC+ K  ++ ,' u||)) *& u||)) *&BG M:=  88-k#((...IJcoo334 6 M$ M++AFO:= 88-k#((...IJcoo3346OP  <4     MOs!A"MA"M!cd}t|}|r.||kr)t||r|dz }|r||krt||r||d}|r/t|dr!|j|rt|dr!|S)zRemoves lines containing only blank characters before and after the text. Args: lines: A list of lines. Returns: A list of lines without trailing or leading blank lines. rr*N)rI _is_blankpop)rPstart num_liness r rWrWs %%j) %)# %,(? QJE %)# %,(? -% )E"I& IIK )E"I& ,r c,| xs|jSr)isspaceras r riris  #T\\^#r c&|syd}g}g}|D]O}|j}|rd}|j|)|s,dj|}|j|g}Q|r"dj|}|j|dj|S)aJoins lines with the appropriate connective whitespace. This puts a single space between consecutive lines, unless there's a blank line, in which case a full blank line is included. Args: lines: A list of lines to join. Returns: A string, the lines joined together. NFTrFz )rGappendrV)rPstarted group_texts group_linesra stripped_line group_texts r rZrZs   '++ dJJLMg' XXk* :&  +&Jz" [ !!r cB|j|jzD]}|j|k(s|cSt}||_g|j_g|j _|r|jj||S|jj||S)aGets or creates a new Arg. These Arg objects (Namespaces) are turned into the ArgInfo namedtuples returned by parse. Each Arg object is used to collect the name, type, and description of a single argument to the docstring's function. Args: state: The state of the parser. name: The name of the arg to create. is_kwarg: A boolean representing whether the argument is a keyword arg. Returns: The new Arg. )rrQrrrrPrrq)r_ris_kwargr9s r _get_or_create_arg_by_namerysZZ%,, &c xx4 j  # #(#((.#//  LL * JJc *r c|j}d}tj||tj||duS)anReturns whether name is a valid arg name. This is used to prevent multiple words (plaintext) from being misinterpreted as an argument name. Any line that doesn't match the pattern for a valid argument is treated as not being an argument. Args: name: The name of the potential arg. Returns: True if name looks like an arg name, False otherwise. z^[a-zA-Z_]\w*$N)rGrematch)r arg_patterns r _is_arg_namer~.s: $"+((; +t $D 00r c|j}t|dkryt|dr;dj|dd}|j dj d}|d|fSy)a=Returns text as a name and type, if text looks like an arg name and type. Example: _as_arg_name_and_type("foo (int)") == "foo", "int" Args: text: The text, which may or may not be an arg name and type. Returns: The arg name and type, if text looks like an arg name and type. None otherwise. r+NrrFr*z{([z])})rHrIr~rVlstriprstrip)texttokens type_tokens r _as_arg_name_and_typerBsj ::<&[1_ &)&*%J""5)007J !9j  r ctjd|}|Dcgc]#}|js|j%}}|D]}t|ry|sy|Scc}w)a Converts names_str to a list of arg names. Example: _as_arg_names("a, b, c") == ["a", "b", "c"] Args: names_str: A string with multiple space or comma separated arg names. Returns: A list of arg names, or None if names_str doesn't look like a list of arg names. z,| N)r{rHrGr~) names_strnamesrs r _as_arg_namesrYsa ((5) $%$) :DTZZ\4::< :% :d      , ;s AAc*|y|jdS)aGCanonicalizes a string representing a type if possible. # TODO(dbieber): Support additional canonicalization, such as string/str, and # boolean/bool. Example: _cast_to_known_type("str.") == "str" Args: name: A string representing a type, or None. Returns: A canonicalized version of the type string. N.)r)rs r r[r[os \  S r c:|jjdd}t|dkDr1|\}}t|j rUt ||j }|j jj|j ||_ yt|}|rq|\}}t ||}|jjj||j jj|j ||_ y|jr3|jj jj|dyy|jr3|jj jj|dyy)z1Consume a single line from a Google args section.:r*rN) remainingrHrIr~rGryrrPrqrRrr) rer_ split_linefirstsecondr9arg_name_and_typearg_nametype_strs r _consume_google_args_liners;""((a0*_qME6EKKM" &uekkm 2e/6 .((9 h' $$V\\^4       ' ' - - 4 4Z] C   ##))00A?r c t|||jj|jjrd|j r0|jj j|j ni|jj rSd|j_nA|jj j|jnd|j_|jjr|jjtjk(rt|}|j}|jjt j"k(rW|d}t%|||ddk(}t'|dk(r(|j(j j|d||_n?|jjt j,k(r|d}t%||}||_|jjtj.k(rt1|j ry|jjt j"k(r|jjtj2k(r t5||y|jjtjk(rH|j*jj j|j j7y|jjtj.k(rP|j j7}t9|rt%||}||_yt;|r|jd d\}}t=|} | r@| D]:} t%|| }|j(j j|||_<y|j*rH|j*jj j|j j7yy|j*rH|j*jj j|j j7yyy|jjt j>k(r>|j@j j|j j7y|jjt jBk(r>|jDj j|j j7y|jjt jFk(r>|jHj j|j j7y|jjt j,k(r~|jjtjk(rV|j*J|j*j(j j|j j7yyy) a-Consumes one line of text, updating the state accordingly. When _consume_line is called, part of the line may already have been processed for header information. Args: line_info: Information about the current and next line of the docstring. state: The state of the docstring parser. NFrhrr )rxr,r*r)%_update_section_staterJrKr rOrrPrqr remaining_rawnewrNr4r7_get_directiverHr)r.ryrIrrRr2r6_line_is_hyphensr5rrGr~_line_is_numpy_parameter_typerr/rr0rr1r) rer_ directivedirective_tokensrr9 line_stripped possible_args type_data arg_namesrs r rUrUs} 5) ]]  }}    ""9#6#67 ==  "'  $$Y%<%<=#EMM ]]5==//7;;>y)I ( }}hmm+ b !d &  #A&%/ c  ! # .q12e    - b !d &ud 3ce mmgmm+y**+  ]]HMM) }}w~~- 51    , ##))001D1D1J1J1LM    .))//1m m $) > ( 3#0#6#6sA#> y!-0 # $h,UH=C HHNN ! !) , #E  $       ) ) / / 6 6##))+ -        ' ' - - 4 4!!'') + 9 /< }}h... MMy2288:; }}hoo- LLi11779: }}hoo- LLi11779: }}hmm+ }}w{{*    ** * "")))*=*=*C*C*EF ,r cdt}||_|j|_|j|_|j|_t |t |jz |_||j_|du}|r|jnd|j_|r%t |t |jz nd|j_||j_|du}|r%t |t |jz nd|j_|S)zAReturns information about the current line and surrounding lines.N) rrarGstrippedrrrIrrLnextprevious)rardrcrenext_line_existsprevious_line_existss r rTrTsk)).zz|)%NN)!**)d)c$++-&88)!)..d*1AIOO-t)..2Bc)ns9++-.. ..))&d2&: - -   !"?C   r c d}t||}|xr t|}|rStj|j_||j_t||_|j|_ d}t|}|rStj|j_||j_t||_|j|_ d}t|}|rJtj|j_||j_d|_|j|_ d}|rRd|j_|j |j_|j"j |j_yd|j_y)zUses line_info to determine the current section of the docstring. Updates state and line_info.remaining. Args: line_info: Information about the current line. state: The state of the parser. FTN)_google_section_permitted_google_sectionr4r5rJrNrK_get_after_google_headerrr _rst_sectionr7_get_after_directive_numpy_sectionr6rrLrrM)rer_section_updatedgoogle_section_permittedgoogle_section rst_section numpy_sections r rrs4/6y%H+J 0J.">>EMM(EMM29=I'11IOY'+";;EMM%EMM.y9I'11IO +-"==EMM'EMMI'11IOEMM ) 5 5EMM&/nn&@&@EMM#EMMr c|jjy|j|jjkxs#|j|jjkS)a Returns whether a new google section is permitted to start here. Q: Why might a new Google section not be allowed? A: If we're in the middle of a Google "Args" section, then lines that start "param:" will usually be a new arg, rather than a new section. We use whitespace to determine when the Args section has actually ended. A Google section ends when either: - A new google section begins at either - indentation less than indentation of line 1 of the previous section - or <= indentation of the previous section - Or the docstring terminates. Args: line_info: Information about the current line. state: The state of the parser. Returns: True or False, indicating whether a new Google section is permitted at the current line. T)rJrLrM)rer_s r rrAsS* ]]&    5==#<#< < E  " "U]]%D%D DFr cT|j}|j}|||ddfvS)zReturns whether title is a match for a specific section_title. Example: _matches_section_title('Yields', 'yield') == True Args: title: The title to check for matching. section_title: A specific known section title to check against. Nrh)lower)rK section_titles r _matches_section_titler\s3 ++-%%%'- 5%*- --r c<t|D]}t||syy)aReturns whether title is a match any known title for a specific section. Example: _matches_section_title('Yields', Sections.YIELDS) == True _matches_section_title('param', Sections.Args) == True Args: title: The title to check for matching. section: A specific section to check all possible titles for. Returns: True or False, indicating whether title is a match for the specified section. TF)SECTION_TITLESr)rKrJrs r _matches_sectionrks*&g.me]3  r c:tD]}t||s|cSy)zReturns a section matched by the possible title, or None if none match. Args: possible_title: A string that may be the title of a new section. Returns: A Section type if one matches, or None if no section type matches. N)rr)possible_titlerJs r _section_from_possible_titlers' g0 n r cl|jjd}|jd|}t|S)acChecks whether the current line is the start of a new Google-style section. This docstring is a Google-style docstring. Google-style sections look like this: Section Name: section body goes here Args: line_info: Information about the current line. Returns: A Section type if one matches, or None if no section type matches. rN)rfindr)re colon_indexrs r rrs7##((-+&&| 4. %n 55r c\|jjd}|j|dzdS)z6Gets the remainder of the line, after a Google header.rr*N)rr)rers r rrs0##((-+   [1_- ..r cx|jjdr|jjdddSy)aAGets a directive from the start of the line. If the line is ":param str foo: Description of foo", then _get_directive(line_info) returns "param str foo". Args: line_info: Information about the current line. Returns: The contents of a directive, or None if the line doesn't start with a directive. rr+r*N)r startswithrH)res r rrs9""3'    # #C +A .. r cb|jjdd}t|dkDr|dSy)z2Gets the remainder of the line, after a directive.rr+rhr)rrHrI)resectionss r rrs3    % %c1 -(]Q B< r cZt|}|r|jd}t|Sy)axChecks whether the current line is the start of a new RST-style section. RST uses directives to specify information. An RST directive, which we refer to as a section here, are surrounded with colons. For example, :param name:. Args: line_info: Information about the current line. Returns: A Section type if one matches, or None if no section type matches. rN)rrHr)rerrs r rrs0Y')__&q)N ' 77 r c.|xr|jd S)z=Returns whether the line is entirely hyphens (and not blank).-)rGros r rrs %djjo%%r ctt|jj}|r|j}t |Sy)agChecks whether the current line is the start of a new numpy-style section. Numpy style sections are followed by a full line of hyphens, for example: Section Name ------------ Section body goes here. Args: line_info: Information about the current line. Returns: A Section type if one matches, or None if no section type matches. N)rrrrr)renext_line_is_hyphensrs r rrs5*)..*A*AB((N ' 77 r c|jj}d|vrA|jj}|j}d|jjvr||kDryyy)aReturns whether the line contains a numpy style parameter type definition. We look for a line of the form: x : type And we have to exclude false positives on argument descriptions containing a colon by checking the indentation of the line above. Args: line_info: Information about the current line. Returns: True if the line is a numpy parameter type definition, False otherwise. rFT)rrGrrLra)rerprevious_indentcurrent_indents r rrs`%%++--M((44O**N i  %%%.?*J   r )F)1r' collectionsenumr{rX namedtuplerrI_fields__new__ __defaults__rrdictrEnumr)r4r.r/r0r1r2rrfrWrirZryr~rrr[rrUrTrrrrrrrrrrrrrr r r rs#J KIK &-s=3H3H/I%I "K') 'W__)==!(3y/@/@+A!A     tyy  dii  MMC k OOZ OOO MM9 Zz.$!"H 81(.,&@2` F.)XF6 .( 6&/ $&& ,r