cf(dZddlmZddlZddlZddlmZddlmZddlm Z d.d Z d/dZ d0dZ d1dZ d2dZd3dZd4dZ d5d6d#ZGd$d"ZGd%d&eZGd'd(eZGd)d*eZGd+d,eZeeeeed-ZdS)7z'Utility methods for docstring checking.) annotationsN)nodes) Uninferable)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 Clib/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_namers~+//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)rrnode_frame_classgetattrrdecorated_with_property)r property_ property_name class_node class_attrsattrs rget_setters_propertyr*2sI-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_somethingr2Js:Gu7EK00JW]d5J KKr nodes.NodeNG!nodes.NodeNG | Uninferable | Nonect|jtjrF|jj}t|tjtjfrtj|SdSN) rexcrCallfuncrrr safe_infer)rr9s 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_typesrBds2J 8J ' ''rset[nodes.ClassDef]cg}tjtjr t jj}|r|g}njj}|r=t|tjs#|j}|rt|tj#|r_|jrX tj |jD]%}|tj ur| |&nL#tj $rYn:wxYwn4t}t|tjr|g}nt|tjr|tjD]}|j |d|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`. NT)future __class__rcHh|]}tj|j|S)rnode_ignores_exceptionr).0r7rs r z%possible_exc_types..s>   /ch??    r)rr7rrrr:parent ExceptHandlertypeastroid unpack_inferrappendInferenceErrorr;ClassDef FunctionDefnodes_of_classReturnr/frameinherit_from_std_exInstancer#set)r exceptionsinferredhandler exceptionr<retvals` rpossible_exc_typesraisJ$(EJ''!G#DH--  $"J G+ %j%2EFF %nG %j%2EFF %  w|  !(!5gl!C!C55I (;;5")))4445)    #4(( fen - - G JJ  1 2 2 G,,U\:: G G999D9))V3&sy11G54S99G!#u~66G"))#....#C)9::G"))#++k*B*B1*EFFF    !     !uu s$?CC.-C.( H66IIdefault docstringnodes.Const | None default_type Docstringcdt|t|f}ttt t fD]1}||}|}||dkr||f}2|dS)Nr)DOCSTRING_TYPESgetrfSphinxDocstringEpytextDocstringGoogleDocstringNumpyDocstringmatching_sections)rcre best_matchdocstring_typeinstanceros r docstringifyrss_((yAA)LLMJ  7 7 ">),,$6688 z!} , 7+X6J a=rceZdZUejdejejzZdZde d< dd Z dd Z dd Z ddZ ddZddZddZddZddZddZddZd dZddZdS)!rfz= For\s+the\s+(other)?\s*parameters\s*,\s+see Fr-supports_yieldsdocrdr NonecN|r|jnd}||_dS)N)r/ expandtabsrv)selfrvrcs r__init__zDocstring.__init__s)&)1r ''))rrc2d|jjd|jdS)N)rF__name__rvr{s r__repr__zDocstring.__repr__s">4>*>>>>>>rr cdS)2Returns the number of matching docstring sections.rrHrs rrozDocstring.matching_sectionssqrset[str]ctSr6rZrs rr[zDocstring.exceptionss uu rcdSNFrHrs r has_paramszDocstring.has_paramsurcdSrrHrs r has_returnszDocstring.has_returnsrrcdSrrHrs r has_rtypezDocstring.has_rtyperrcdSrrHrs rhas_property_returnszDocstring.has_property_returnsrrcdSrrHrs rhas_property_typezDocstring.has_property_typerrcdSrrHrs r has_yieldszDocstring.has_yieldsrrcdSrrHrs rhas_yields_typezDocstring.has_yields_typerrtuple[set[str], set[str]]c:ttfSr6rrs rmatch_param_docszDocstring.match_param_docssuucee|rcD|j|jduSr6)re_for_parameters_seesearchrvrs rparams_documented_elsewherez%Docstring.params_documented_elsewheres )00::$FFrN)rvrdr rwr rr r r rr r-r r)r __module__ __qualname__r?compileXSrru__annotations__r|rror[rrrrrrrrrrHrrrfrfs^&BJ  rt "O!!!! ****????GGGGGGrceZdZdZdedZdeeZdedZded ed Ze j ee j e j zZ d ed Ze j ee j e j zZd edZe j ee j e j zZdedZe j ee j e j zZe j dZe j dZdZd"dZd#dZd$dZd$dZd$dZd$dZd$dZd%d Zd!S)&rkzt [~!.]? # Optional link style prefix \w(?:\w|\.[^\.])* # Valid python name z zw # a container type [\(\[] [^\n\s]+ [\)\]] # with the contents of the container zv (?:{container_type}|{type}) (?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{container_type}|{type}))* )rNcontainer_typez? (?::\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|VdSr6r-rJis r z4SphinxDocstring.matching_sections..=<    GG       r)sumre_param_in_docstringrrvre_raise_in_docstringre_rtype_in_docstringre_returns_in_docstringre_property_type_in_docstringrs rroz!SphinxDocstring.matching_sections;s   *11$(;;*11$(;;*11$(;;,33DH==299$(CC       rrct}tj|j|jD]9}|d}|t|:|SNrh)rZr?finditerrrvgroupupdaterB)r{typesmatch raise_types rr[zSphinxDocstring.exceptionsHs_%%[!;TXFF @ @EQJ LL2:>> ? ? ? ? rr-cV|jsdS|j|jduSr)rvrrrs rrzSphinxDocstring.has_paramsQs/x 5)00::$FFrcl|jsdSt|j|jSr)rvr-rrrs rrzSphinxDocstring.has_returnsWs2x 5D077AABBBrcl|jsdSt|j|jSr)rvr-rrrs rrzSphinxDocstring.has_rtype]s2x 5D.55dh??@@@rcn|jsdS|jd S)NF:)rvr startswithrs rrz$SphinxDocstring.has_property_returnscs6x 58??$$//4444rcl|jsdSt|j|jSr)rvr-rrrs rrz!SphinxDocstring.has_property_typeks2x 5D6==dhGGHHHrrct}t}tj|j|jD]n}|d}|dd}|||d}|||o|tj |j |j||fS)N\ryrh) rZr?rrrvrreplaceaddrfindallre_type_in_docstring)r{params_with_docparams_with_typerr param_types rrz SphinxDocstring.match_param_docsqs%%55[!;TXFF + +E;;q>>D<<b))D    % % %QJ + $$T*** 4+Ddh O OPPP 000rNrrrr)rrrre_typere_simple_container_typeformatre_multiple_simple_typere_xref re_param_rawr?rrrr re_type_rawrre_property_type_rawr re_raise_rawrrrruror[rrrrrrrHrrrkrksB G         %=       G     -   L$'BJ|RTBD[AA  "   K&2:k24"$;??  !    %/BJ/CRTBD[$Q$Q!   "    L'BJ|RTBD[AA&BJz22(bj77O     GGGG CCCC AAAA 5555IIII 111111rrkc6eZdZdZejejdddej ej zZ ejej dddej ej zZ ejejdddej ej zZejejdddej ej zZejdej ej zZejdZd d Zd S) rlaEpytext 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@rhz @ # initial "at" symbol (?: # Epytext keyword rtype|returntype ) : # final colon z @returns?:r r-c|jsdS|r-|jd SdS)NFr)rvrrrrs rrz%EpytextDocstring.has_property_returnssQx 5  ! ! # # 9x((33C888 8urNr)rrr__doc__r?rrkrrrrrrrrrrrrrrrHrrrlrlsN  'BJ$,,S#q9924"$;&2:#++Ca88"$+%/BJ,44S#qAA24"$;%%!'BJ$,,S#q9924"$;'BJ  rt   )bj77      rrlceZdZejZejZdededZdeeeZdZ e 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)8rmz (?:rzj) # a container type [\(\[] [^\n]+ [\)\]] # with the contents of the container z (?:{container_type}|{type}|{xref}) (?:(?:\s+(?:of|or)\s+|\s*,\s*|\s+\|\s+)(?:{container_type}|{type}|{xref}))* )rNxrefrzy ^([ ]*) {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|VdSr6rrs rrz4GoogleDocstring.matching_sections..rr) rre_param_sectionrrvre_raise_sectionre_returns_sectionre_yields_sectionre_property_returns_line _first_liners rroz!GoogleDocstring.matching_sections s   %,,TX66%,,TX66'..tx88&--dh77-44T5E5E5G5GHH       rr-cV|jsdS|j|jduSr)rvrrrs rrzGoogleDocstring.has_paramss/x 5$++DH55TAArc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSNFrTrv_parse_sectionrre_returns_linerr)r{entriesentryr return_descs rrzGoogleDocstring.has_returnsx 5%%d&=>>  E(..u55E ++a..K tt urc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSNFrhTr)r{rrr return_types rrzGoogleDocstring.has_rtype/rrc|}t|j|pM|j|p3|j|p|j| Sr6)rr-rrrrr)r{ first_lines rrz$GoogleDocstring.has_property_returns?s%%''   ! ( ( 4 4 9$++J77 9&--j99 9%,,Z88     rc|jsdSt|j|Sr)rvr-rrrrs rrz!GoogleDocstring.has_property_typeJs<x 5D1778H8H8J8JKKLLLrc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSrrvrrre_yields_linerr)r{rrr yield_descs rrzGoogleDocstring.has_yieldsPx 5%%d&<==  E'--e44E QJ tt urc|jsdS||j}|D]9}|j|}|s|d}|rdS:dSrr)r{rrr yield_types rrzGoogleDocstring.has_yields_type`rrrc6t}||j}|D]m}|j|}|s|d}|d}|r"|t|n|S)Nrhr)rZrr re_raise_linerrrrB)r{rrrrexc_typeexc_descs rr[zGoogleDocstring.exceptionsps%%%%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)Nrhrryr) rZrrextendre_keyword_param_section re_param_linerrrr) r{rrrrr 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/// 000rrch|jdddS)N rhr)rvrr@rs rrzGoogleDocstring._first_lines)x  &&tQ//22r section_match re.Match[str]cLt|ddzSrr rrs rmin_section_indentz"GoogleDocstring.min_section_indents#=&&q))**Q..r_cdSrrH)rs 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) rrvrr splitlinesstriprrrQjoin) r{rrmin_indentationrris_firstline indentations rrzGoogleDocstring._parse_sectionsJ"))$(33  I11-@@!''**5577  D::<< +D11K_,  !"- o- **400ENN499U#3#3444E LL      - NN499U++ , , ,rNrrrrrrrr r )rrr r-)rrr r=))rrrrkrrre_container_typerre_multiple_type_re_section_templater?rrrMrr r rrrrrrrrurorrrrrrrr[rr staticmethodrrrrHrrrmrms%G%G    73D     "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///\/\ %%%%%%rrmc.eZdZdZejedejejzej zZ dZ ejde j de dejejzZejedejejzej zZejde jd ejejzej zZejed ejejzej zZejd e j d ejejzej zZejed ejejzej zZeZdZddZeddZeddZdS)rnz ^([ ]*) {0} \s*?$ # Numpy parameters header \s* [-=]+ \s*?$ # underline ( .* ) # section rz.((['"]\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 )? rrz^)$ # type declaration \s* (.*) # optional description rz6 \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*$rrNrz\s*(\*{0,2}\w+)\s*:.+$) rZrrr r r rr?rr) r{rrrrr re_only_descrrrs rrzNumpyDocstring.match_param_docsst%%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/// 000rrrr cFt|dSrrrs rrz!NumpyDocstring.min_section_indent=s=&&q))***rr#rr-cFttjd|S)Nz\s*-+$)r-r?r)r#s rrz!NumpyDocstring._is_section_headerAsBHY--...rNrr%)r#rr r-)rrrr(r?rrrrr)rre_default_valuermr'r rrrrrrrrurr*rrrHrrrnrns9 "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+++\+///\///rrn)sphinxepytextgooglenumpyrb)rrr r )rrr r)rrr r )r+r,r r-)rr3r r4)r<rr r=)rr3r rC)rb)rcrdrerr rf)r __future__rr?rOr astroid.utilrpylint.checkersrrrr*r2r;rBrarsrfrkrlrmrnrirHrrr8s3 .-"""""" $$$$$$!!!!!!''''*0LLLL$(((( 6666t8A$6G6G6G6G6G6G6G6GrR1R1R1R1R1iR1R1R1j33333333lTTTTTiTTTnt/t/t/t/t/_t/t/t/p  r