yIf9t\dZddlmZddlZddlZddlmZddlZddlmZddl m Z ddl m Z d;d Z ddZd?dZd@dZdAdZdBdZdCd$ZdDd(ZdEd*Z dFdGd0ZGd1d/ZGd2d3eZGd4d5eZGd6d7eZGd8d9eZeeeeed:ZdS)Hz'Utility methods for docstring checking.) annotationsN)Iterable)nodes)UninferableBase)utilssstrreturnintcft|t|dz S)zThe number of leading spaces in a string. :param str s: input string :rtype: int :return: number of leading spaces  )lenlstrip)rs W/var/www/piapp/venv/lib/python3.11/site-packages/pylint/extensions/_check_docs_utils.pyspace_indentationrs' q66C && &&nodenodes.FunctionDef str | Nonec|jr |jjng}|D]T}t|tjr8|jdkr-t|jtjr|jjcSUdS)aGet the name of the property that the given node is a setter for. :param node: The node to get the property name for. :type node: str :rtype: str or None :returns: The name of the property that the node is a setter for, or None if one could not be found. setterN) decoratorsr isinstance AttributeattrnameexprNamename)rr decorators rget_setters_property_namer sz+//A&&rJ'' y%/ 2 2 '"h..9>5:66/>& & & & 4rnodes.FunctionDef | Nonecd}t|}tj|}|r9|r7||j}|D]}tj|r|}n|S)a'Get the property node for the given setter node. :param node: The node to get the property for. :type node: nodes.FunctionDef :rtype: nodes.FunctionDef or None :returns: The node relating to the property of the given setter node, or None if one could not be found. N)r rnode_frame_classgetattrrdecorated_with_property)r property_ property_name class_node class_attrsattrs rget_setters_propertyr+4sI-d33M'--J/9/A/A$)/L/L   D,T22    r return_node nodes.Returnboolc`|j}|dSt|tjo|jdu S)aCheck if a return node returns a value other than None. :param return_node: The return node to check. :type return_node: astroid.Return :rtype: bool :return: True if the return node returns a value other than None, False otherwise. NF)valuerrConst)r,returnss rreturns_somethingr3Ls7Gu7EK00JW]d5J KKr nodes.NodeNG%nodes.NodeNG | UninferableBase | Nonect|jtjrF|jj}t|tjtjfrtj|SdSN) rexcrCallfuncrrr safe_infer)rr:s r_get_raise_targetr<^sR$(EJ''*x} dUZ9 : : *#D)) ) 4rtarget list[str]c0d}tj||S)Nz(\s*,(?:\s*or\s)?\s*|\s+or\s+))resplit)r= delimiterss r_split_multiple_exc_typesrCfs2J 8J ' ''rset[nodes.ClassDef]cg}tjtjr t jj}|r|g}njj}|r=t|tjs#|j}|rt|tj#|rf|jr_ tj |jD],}t|ts| |-nJ#tj $rYn8wxYwn2t}t|tjr|g}nt|tjr|tjD]}|j ||kr#t j|j}|rt j|rxt|tjr| |t|tjr.| |dd fd|DS#tj $rt1cYSwxYw)aGets all the possible raised exception types for the given raise node. .. note:: Caught exception types are ignored. :param node: The raise node to find exception types for. :returns: A list of exception types possibly raised by :param:`node`. N __class__rcHh|]}tj|j|S)rnode_ignores_exceptionr).0r8rs r z%possible_exc_types..s>   /ch??    r)rr8rrrr;parent ExceptHandlertypeastroid unpack_inferrappendInferenceErrorr<ClassDef FunctionDefnodes_of_classReturnr0frameinherit_from_std_exInstancer$set)r exceptionsinferredhandler exceptionr=retvals` rpossible_exc_typesraksJ$(EJ''!G#DH--  $"J  + %j%2EFF %nG %j%2EFF %  w|  !(!5gl!C!C55I%iAA5")))4445)    #4(( fen - - G JJ  1 2 2 G,,U\:: G G9$99;;&((&sy11G54S99G!#u~66G"))#....#C)9::G"))#++k*B*B1*EFFF    !     !uu s%AC""C54C5- H;;IIcVt|tjo|jtkSr7)rrr1r0Ellipsis)rs r _is_ellipsisrds dEK ( ( CTZ8-CCrrIterable[nodes.NodeNG]comment_annotationsIterable[nodes.NodeNG | None]c#Ktj||D]5\}}|rt|s|V|rt|s|V1dV6dSr7) itertools zip_longestrd)rrfann comment_anns r_merge_annotationsrms&1+?RSS[  |C(( IIII  k!:!:     JJJJ r args_nodenodes.Argumentslist[nodes.NodeNG]c |jpd}|jjpd}|j}||jpgz }||jz }t t |t ||S)aGet a merged list of annotations. The annotations can come from: * Real type annotations. * A type comment on the function. * A type common on the individual argument. :param args_node: The node to get the annotations for. :returns: The annotations. rH)rrLtype_comment_argstype_comment_posonlyargstype_comment_kwonlyargslistrm)rnplain_annotationsfunc_comment_annotationsrfs r_annotations_listrxs~"-3(/AGR#<96<"<9<<   79L M M    rset[str]ct}t|}d}|jrx|j}t |js&t |j}||||z}||z }t |j|D]!\}}|r||j"|j r[t |j }t |j ||||zD]!\}}|r||j"||z }|j r\|j r||j n:t ||kr'||r||j |dz }|j rx|j }t |j s&t |j }||||z}||z }t |j |D]!\}}|r||j"|jr\|jr||jn:t ||kr'||r||j|dz }|SNr)rZrx posonlyargsposonlyargs_annotationsanyrzipaddrargsvarargvarargannotation kwonlyargskwonlyargs_annotationskwargkwargannotation) rnresultrannotation_offsetr~num_argsarg annotationrs rargs_with_annotationrs UUF#I..K %"+"C9455 *9011H&1!$5$@@' #  ) "9#8:QRR % %OC % 38$$$~ &y~&&" N ),=,HH I   % %OC % 38$$$X%#  % # JJy' ( ( ( (    1 1 1kBS6T 1 JJy' ( ( (  "  %!*!A9344 *9/00H%0!$5$@@& "  ) "9#79OPP % %OC % 38$$$#  $ # JJy ' ' ' '    1 1 1kBS6T 1 JJy ' ' '  "  Mrdefault docstringnodes.Const | None default_type Docstringcdt|t|f}ttt t fD]1}||}|}||dkr||f}2|dSr{)DOCSTRING_TYPESgetrSphinxDocstringEpytextDocstringGoogleDocstringNumpyDocstringmatching_sections)rr best_matchdocstring_typeinstancers r docstringifyrs_((yAA)LLMJ  7 7 ">),,$6688 z!} , ,+X6J a=rceZdZUejdejejzZdZde d< dd Z dd Z dd Z ddZ ddZddZddZddZddZddZddZd dZddZdS)!rz= For\s+the\s+(other)?\s*parameters\s*,\s+see Fr.supports_yieldsdocrr NonecN|r|jnd}||_dS)N)r0 expandtabsr)selfrrs r__init__zDocstring.__init__)s)&)1r ''))rr c2d|jjd|jdS)N)rF__name__rrs r__repr__zDocstring.__repr__-s">4>*>>>>>>rr cdS)2Returns the number of matching docstring sections.rrHrs rrzDocstring.matching_sections0sqrryctSr7rZrs rr[zDocstring.exceptions4s uu rcdSNFrHrs r has_paramszDocstring.has_params7urcdSrrHrs r has_returnszDocstring.has_returns:rrcdSrrHrs r has_rtypezDocstring.has_rtype=rrcdSrrHrs rhas_property_returnszDocstring.has_property_returns@rrcdSrrHrs rhas_property_typezDocstring.has_property_typeCrrcdSrrHrs r has_yieldszDocstring.has_yieldsFrrcdSrrHrs rhas_yields_typezDocstring.has_yields_typeIrrtuple[set[str], set[str]]c:ttfSr7rrs rmatch_param_docszDocstring.match_param_docsLsuucee|rcD|j|jduSr7)re_for_parameters_seesearchrrs rparams_documented_elsewherez%Docstring.params_documented_elsewhereOs )00::$FFrN)rrr rr r r r r ryr r.r r)r __module__ __qualname__r@compileXSrr__annotations__rrrr[rrrrrrrrrrHrrrrs^&BJ  rt "O!!!! ****????GGGGGGrc eZdZdZdedZdedededed Zded Zd eded Zej eej ej zZ d ed Z ej e ej ej zZdedZej eej ej zZdedZej eej ej zZej dZej dZdZd#dZd$dZd%dZd%dZd%dZd%dZd%dZd&d!Zd"S)'rzt [~!.]? # Optional link style prefix \w(?:\w|\.[^\.])* # Valid python name z zw # a container type [\(\[] [^\n\s]+ [\)\]] # with the contents of the container (?:|4) (?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:))* z? (?::\w+:)? # optional tag `z0` # what to reference a# : # initial colon (?: # Sphinx keywords param|parameter| arg|argument| key|keyword ) \s+ # whitespace (?: # optional type declaration (z) \s+ )? ((\\\*{0,2}\w+)|(\w+)) # Parameter name with potential asterisks \s* # whitespace : # final colon zx :type # Sphinx keyword \s+ # whitespace (z) # Parameter name \s* # whitespace : # final colon zo :type: # Sphinx keyword \s+ # whitespace z # type declaration z : # initial colon (?: # Sphinx keyword raises?| except|exception ) \s+ # whitespace (z) # exception type \s* # whitespace : # final colon z:rtype:z :returns?:Fr r c `td|j|j|j|j|j|j|j|j|j|jfDS)rc34K|]}t|VdSr7r.rJis r z4SphinxDocstring.matching_sections..<    GG       r)sumre_param_in_docstringrrre_raise_in_docstringre_rtype_in_docstringre_returns_in_docstringre_property_type_in_docstringrs rrz!SphinxDocstring.matching_sectionss   *11$(;;*11$(;;*11$(;;,33DH==299$(CC       rryct}tj|j|jD]9}|d}|t|:|SNr|)rZr@finditerrrgroupupdaterC)rtypesmatch raise_types rr[zSphinxDocstring.exceptionss_%%[!;TXFF @ @EQJ LL2:>> ? ? ? ? rr.cV|jsdS|j|jduSr)rrrrs rrzSphinxDocstring.has_paramss/x 5)00::$FFrcl|jsdSt|j|jSr)rr.rrrs rrzSphinxDocstring.has_returnss2x 5D077AABBBrcl|jsdSt|j|jSr)rr.rrrs rrzSphinxDocstring.has_rtypes2x 5D.55dh??@@@rcn|jsdS|jd S)NF:)rr startswithrs rrz$SphinxDocstring.has_property_returnss6x 58??$$//4444rcl|jsdSt|j|jSr)rr.rrrs rrz!SphinxDocstring.has_property_types2x 5D6==dhGGHHHrrct}t}tj|j|jD]n}|d}|dd}|||d}|||o|tj |j |j||fS)N\rr|) rZr@rrrrreplacerrfindallre_type_in_docstring)rparams_with_docparams_with_typerr param_types rrz SphinxDocstring.match_param_docss%%55[!;TXFF + +E;;q>>D<<b))D    % % %QJ% $$T*** 4+Ddh O OPPP 000rNrrrr)rrrre_typere_simple_container_typere_multiple_simple_typere_xref re_param_rawr@rrrr re_type_rawrre_property_type_rawr re_raise_rawrrrrrr[rrrrrrrHrrrrSs] G        $'.3KNU     G     -   L$'BJ|RTBD[AA  "   K&2:k24"$;??  !    %/BJ/CRTBD[$Q$Q!   "    L'BJ|RTBD[AA&BJz22(bj77O     GGGG CCCC AAAA 5555IIII 111111rrc6eZdZdZejejdddej ej zZ ejej dddej ej zZ ejejdddej ej zZejejdddej ej zZejdej ej zZejdZd d Zd S) raEpytext is similar to Sphinx. See the docs: http://epydoc.sourceforge.net/epytext.html http://epydoc.sourceforge.net/fields.html#fields It's used in PyCharm: https://www.jetbrains.com/help/pycharm/2016.1/creating-documentation-comments.html#d848203e314 https://www.jetbrains.com/help/pycharm/2016.1/using-docstrings-to-specify-types.html r@r|z @ # initial "at" symbol (?: # Epytext keyword rtype|returntype ) : # final colon z @returns?:r r.c|jsdS|r-|jd SdS)NFr)rrrrrs rrz%EpytextDocstring.has_property_returnssQx 5  ! ! # # 9x((33C888 8urNr)rrr__doc__r@rrrrrrrrrrrrrrrrrHrrrrsN  'BJ$,,S#q9924"$;&2:#++Ca88"$+%/BJ,44S#qAA24"$;%%!'BJ$,,S#q9924"$;'BJ  rt   )bj77      rrc eZdZejZejZdededZdedededededed ZdZe j e de j e j ze jzZe j e de j e j ze jzZe j d ed e j e j ze jzZe j e d e j e j ze jzZe j d ed e j e j ze jzZe j e de j e j ze jzZe j dede j e j ze jzZe j dede j e j ze jzZe j e de j e j ze jzZeZdZd0dZd1dZd1dZd1dZd1dZd1dZd1dZ d1dZ!d2d!Z"d3d#Z#d4d%Z$e%d5d(Z&e%d6d*Z'd7d.Z(d/S)8rrrzj) # a container type [\(\[] [^\n]+ [\)\]] # with the contents of the container rrzy ^([ ]*) {0} \s*: \s*$ # Google parameter header ( .* ) # section (?:Args|Arguments|Parameters)z&Keyword\s(?:Args|Arguments|Parameters)z} \s* ((?:\\?\*{0,2})?[\w\\]+) # identifier potentially with asterisks or escaped `\` \s* ( [(] z (?:,\s+optional)? [)] )? \s* : # optional type declaration \s* (.*) # beginning of optional description Raisesz \s* (zg) \s* : # identifier \s* (.*) # beginning of optional description Returns? \s* (za:)? # identifier \s* (.*) # beginning of description z ^za: # identifier \s* (.*) # Summary line / description Yields?Tr r c ztd|j|j|j|j|j|j|j|j|j|fDS)rc34K|]}t|VdSr7rrs rrz4GoogleDocstring.matching_sections..prr) rre_param_sectionrrre_raise_sectionre_returns_sectionre_yields_sectionre_property_returns_line _first_liners rrz!GoogleDocstring.matching_sectionsns   %,,TX66%,,TX66'..tx88&--dh77-44T5E5E5G5GHH       rr.cV|jsdS|j|jduSr)rrrrs rrzGoogleDocstring.has_params{s/x 5$++DH55TAArc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSNFrTr_parse_sectionrre_returns_linerr)rentriesentryr return_descs rrzGoogleDocstring.has_returnsx 5%%d&=>>  E(..u55E ++a..K tt urc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSNFr|Tr)rrrr return_types rrzGoogleDocstring.has_rtyper!rc|}t|j|pM|j|p3|j|p|j| Sr7)rr.rrrrr)r first_lines rrz$GoogleDocstring.has_property_returnss%%''   ! ( ( 4 4 9$++J77 9&--j99 9%,,Z88     rc|jsdSt|j|Sr)rr.rrrrs rrz!GoogleDocstring.has_property_types<x 5D1778H8H8J8JKKLLLrc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSrrrrre_yields_linerr)rrrr yield_descs rrzGoogleDocstring.has_yieldsx 5%%d&<==  E'--e44E QJ tt urc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSr#r))rrrr yield_types rrzGoogleDocstring.has_yields_typer,rryc6t}||j}|D]m}|j|}|s|d}|d}|r"|t|n|S)Nr|r)rZrr re_raise_linerrrrC)rrrrrexc_typeexc_descs rr[zGoogleDocstring.exceptionss%%%%d&;<< B BE&,,U33E {{1~~H{{1~~H B 6x@@AAA rrct}t}||j}|||j|D]}|j|}|s|d}|dd}|d}|d}|r| ||r| |||fS)Nr|rrr) rZrrextendre_keyword_param_section re_param_linerrrr) rrrrrr param_namer param_descs rrz GoogleDocstring.match_param_docss$'EE%(UU%%d&;<<t**4+HIIJJJ 0 0E&,,U33E QJ#++D"55JQJQJ 1 $$Z000 0##J/// 000rr ch|jdddS)N r|r)rrrArs rrzGoogleDocstring._first_lines)x  &&tQ//22r section_match re.Match[str]cLt|ddzSrrrr<s rmin_section_indentz"GoogleDocstring.min_section_indents#=&&q))**Q..r_cdSrrH)rBs r_is_section_headerz"GoogleDocstring._is_section_headers ur section_rere.Pattern[str]r>c@||j}|gS||}g}g}d}|dD]}|st |}||krne|r|}d}||krC||rnB|r*|d |g}|||r(|d ||S)NTrFr;) rrrAr splitlinesstriprrDrQjoin) rrEr<min_indentationrris_firstline indentations rrzGoogleDocstring._parse_section sD"))$(33  I11-@@!''**5577  D::<< +D11K_,, !"- o--**400ENN499U#3#3444E LL      - NN499U++ , , ,rNrrrrrr<r=r r )rBr r r.)rErFr r>))rrrrrrre_container_typere_multiple_type_re_section_templater@rformatrrMrr6r7rr0rrrrr*rrrrrrrrrr[rr staticmethodrArDrrHrrrrs%G%G    '*13DGNQX   "rz##$DEE rt bd *rz##$MNN rt bd   BJ     rt bd  M"rz##I..rt bd0BBJ     rt bd M$##K00"$+2D!bj     rt bd O *rz      rt bd   # ##J//rt1C%NO     BBBB       MMMM    111143333///\/\ %%%%%%rrc.eZdZdZejedejejzej zZ dZ ejde j de dejejzZejedejejzej zZejde jd ejejzej zZejed ejejzej zZejd e j d ejejzej zZejed ejejzej zZeZdZddZeddZeddZdS)rz ^([ ]*) {0} \s*?$ # Numpy parameters header \s* [-=]+ \s*?$ # underline ( .* ) # section r z.((['"]\w+\s*['"])|(\d+)|(True)|(False)|(None))z \s* (?P\*{0,2}\w+)(\s?(:|\n)) # identifier with potential asterisks \s* (?P ( (z) # default type declaration (,\s+optional)? # optional 'optional' indication )? ( {(z,?\s*)+} # set of default values )? (?:$|\n) )? ( \s* (?P.*) # optional description )? r rz^)$ # type declaration \s* (.*) # optional description r z6 \s* (?:\w+\s+:\s+)? # optional name (zc)$ # type declaration \s* (.*) # optional description rTr rct}t}||j}|||j|D]}|j|}|stjd|}|r-|d}|d}d} n^|d}|d} |d}| tjd|r|} |s| r| }| r| ||r| |||fS)zIMatches parameter documentation section to parameter documentation rules.z\s*(\*{0,2}\w+)\s*:?\n\s*\w*$r8rNr9z\s*(\*{0,2}\w+)\s*:.+$) rZrrr5r6r7rr@rr) rrrrrr re_only_descr8r9rs rrzNumpyDocstring.match_param_docsusp%%55%%d&;<<t**4+HIIJJJ 0 0E&,,U33E 8$DeLLL ,"[[66 "[[66 ! "[[66 "[[66 "[[66 %"(3Le*T*T%!+J",j,!+J 1 $$Z000 0##J/// 000rr<r=r cFt|dSrr?r@s rrAz!NumpyDocstring.min_section_indents=&&q))***rrMr r.cFttjd|S)Nz\s*-+$)r.r@r)rMs rrDz!NumpyDocstring._is_section_headersBHY--...rNrrO)rMr r r.)rrrrRr@rrSrrrTrre_default_valuerrQr7rrr0rrrr*rrrUrArDrHrrrr1s9 "rz##$DEE rt bd MBJ   ,      " rt %M*"rz##I..rt bd0BBJ %    rt bd M$##K00"$+2D!bj   *    rt bd O# ##J//rt1C%NO(1(1(1(1T+++\+///\///rr)sphinxepytextgooglenumpyr)rr r r )rrr r)rrr r!)r,r-r r.)rr4r r5)r=r r r>)rr4r rD)rr4r r.)rrerfrer rg)rnror rp)rnror ry)r)rrrr r r)r  __future__rrir@collections.abcrrOr astroid.utilrpylint.checkersrrr r+r3r<rCrardrmrxrrrrrrrrrHrrrds .-"""""" $$$$$$((((((!!!!!!''''*0LLLL$(((( 6666rDDDD    28888x8A$6G6G6G6G6G6G6G6GrP1P1P1P1P1iP1P1P1f33333333lRRRRRiRRRjt/t/t/t/t/_t/t/t/p  r