3 ^^X@sdZddlZddlZddlmZddZddZdd Zd d Zd d Z ddZ dddZ GdddZ Gddde Z Gddde ZGddde ZGdddeZe eeee dZdS)z'Utility methods for docstring checking.N)utilscCst|t|jdS)zThe number of leading spaces in a string :param str s: input string :rtype: int :return: number of leading spaces  )lenlstrip)srE/tmp/pip-build-8app2_gc/pylint/pylint/extensions/_check_docs_utils.pyspace_indentationsr cCsP|jr|jjng}x8|D]0}t|tjr|jdkrt|jtjr|jjSqWdS)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) decoratorsZnodes isinstanceastroid AttributeattrnameexprNamename)noder Z decoratorrrrget_setters_property_name%s     rcCsLd}t|}tj|}|rH|rH|j|j}x|D]}tj|r0|}Pq0W|S)a+Get the property node for the given setter node. :param node: The node to get the property for. :type node: astroid.FunctionDef :rtype: astroid.FunctionDef or None :returns: The node relating to the property of the given setter node, or None if one could not be found. N)rrZnode_frame_classgetattrrZdecorated_with_property)rZ property_Z property_nameZ class_nodeZ class_attrsattrrrrget_setters_property:s     rcCs*|j}|dkrdSt|tjo&|jdk 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)valuer r ZConst)Z return_nodeZreturnsrrrreturns_somethingRs rcCs6t|jtjr2|jj}t|tjtjfr2tj|SdS)N) r excr Callfuncrrr safe_infer)rrrrr_get_raise_targetds  rc s:g}tjtjr,tjj}|r*|jg}n܈jdkrj}x|rXt|tj rX|j}q>W|r~|j r~tj |j }dd|D}nt }t|tj r|jg}njt|tj rxZ|jtjD]J}|j|krqtj|j}|ot|tjtj fotj|r|j|jqWyfdd|DStjk r4tSXdS)aZ Gets all of 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. :type node: astroid.node_classes.NodeNG :returns: A list of exception types possibly raised by :param:`node`. :rtype: set(str) Ncss|]}|tjk r|jVqdS)N)r Z Uninferabler).0rrrr sz%possible_exc_types..csh|]}tj|s|qSr)rZnode_ignores_exception)rr)rrr sz%possible_exc_types..)r rr rrrrparent ExceptHandlertypeZ unpack_inferrClassDef FunctionDefZnodes_of_classReturnframerZInstanceZinherit_from_std_exappendZInferenceErrorset)rZexcsinferredhandlerZ inferred_excstargetretvalr)rrpossible_exc_typesls8           r0defaultcCs>x(ttttgD]}||}|jr|SqWtj|t}||S)N)SphinxDocstringEpytextDocstringGoogleDocstringNumpyDocstringis_validDOCSTRING_TYPESget Docstring)Z docstringZ default_typeZdocstring_typeinstancerrr docstringifys  r;c@seZdZejdejejBZdZddZ ddZ ddZ d d Z d d Z d dZddZddZddZddZddZddZdS)r9z= For\s+the\s+(other)?\s*parameters\s*,\s+see NcCs|pd}|j|_dS)N) expandtabsdoc)selfr>rrr__init__szDocstring.__init__cCsdS)NFr)r?rrrr6szDocstring.is_validcCstS)N)r*)r?rrr exceptionsszDocstring.exceptionscCsdS)NFr)r?rrr has_paramsszDocstring.has_paramscCsdS)NFr)r?rrr has_returnsszDocstring.has_returnscCsdS)NFr)r?rrr has_rtypeszDocstring.has_rtypecCsdS)NFr)r?rrrhas_property_returnsszDocstring.has_property_returnscCsdS)NFr)r?rrrhas_property_typeszDocstring.has_property_typecCsdS)NFr)r?rrr has_yieldsszDocstring.has_yieldscCsdS)NFr)r?rrrhas_yields_typeszDocstring.has_yields_typecCs ttfS)N)r*)r?rrrmatch_param_docsszDocstring.match_param_docscCs|jj|jdk S)N)re_for_parameters_seesearchr>)r?rrrparams_documented_elsewheresz%Docstring.params_documented_elsewhere)__name__ __module__ __qualname__recompileXSrJsupports_yieldsr@r6rArBrCrDrErFrGrHrIrLrrrrr9s r9c@seZdZdZdjedZdjeZdjeedZej eej ej BZ djedZ ej e ej ej BZdjedZej eej ej BZd jedZej eej ej BZej d Zej d Zd Zd dZddZddZddZddZddZddZddZdS)r2zt [~!.]? # Optional link style prefix \w(?:\w|\.[^\.])* # Valid python name z {type} # a container type [\(\[] [^\n\s]+ [\)\]] # with the contents of the container )r$zw (?::\w+:)? # optional tag `{}` # what to reference a : # initial colon (?: # Sphinx keywords param|parameter| arg|argument| key|keyword ) \s+ # whitespace (?: # optional type declaration ({type}|{container_type}) \s+ )? (\w+) # Parameter name \s* # whitespace : # final colon )r$container_typez :type # Sphinx keyword \s+ # whitespace ({type}) # Parameter name \s* # whitespace : # final colon z :type: # Sphinx keyword \s+ # whitespace {type} # type declaration aW : # initial colon (?: # Sphinx keyword raises?| except|exception ) \s+ # whitespace ({type}) # exception type \s* # whitespace : # final colon z:rtype:z :returns?:FcCsJt|jj|jpF|jj|jpF|jj|jpF|jj|jpF|jj|jS)N)boolre_param_in_docstringrKr>re_raise_in_docstringre_rtype_in_docstringre_returns_in_docstringre_property_type_in_docstring)r?rrrr68s zSphinxDocstring.is_validcCs8t}x,tj|j|jD]}|jd}|j|qW|S)N)r*rPfinditerrXr>groupadd)r?typesmatchZ raise_typerrrrAAs  zSphinxDocstring.exceptionscCs|js dS|jj|jdk S)NF)r>rWrK)r?rrrrBJszSphinxDocstring.has_paramscCs|js dSt|jj|jS)NF)r>rVrZrK)r?rrrrCPszSphinxDocstring.has_returnscCs|js dSt|jj|jS)NF)r>rVrYrK)r?rrrrDVszSphinxDocstring.has_rtypecCs|js dS|jjjd S)NF:)r>r startswith)r?rrrrE\sz$SphinxDocstring.has_property_returnscCs|js dSt|jj|jS)NF)r>rVr[rK)r?rrrrFdsz!SphinxDocstring.has_property_typecCstt}t}xHtj|j|jD]4}|jd}|j||jd}|dk r|j|qW|jtj|j |j||fS)Nr\) r*rPr]rWr>r^r_updatefindallre_type_in_docstring)r?params_with_docparams_with_typerar param_typerrrrIjs   z SphinxDocstring.match_param_docsN)rMrNrOre_typeformatZre_simple_container_typere_xref re_param_rawrPrQrRrSrW re_type_rawrgre_property_type_rawr[ re_raise_rawrXrYrZrTr6rArBrCrDrErFrIrrrrr2s8      r2c@seZdZdZejejjdddej ej BZ ejej jdddej ej BZ ejejjdddej ej BZejejjdddej ej BZejdej ej BZejdZddZd S) r3a Epytext 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 rb@r\z @ # initial "at" symbol (?: # Epytext keyword rtype|returntype ) : # final colon z @returns?:cCs(|js dS|jr$|jjjd SdS)NFrr)r>rFrrc)r?rrrrEs z%EpytextDocstring.has_property_returnsN)rMrNrO__doc__rPrQr2rnreplacerRrSrWrorgrpr[rqrXrYrZrErrrrr3ys  r3c@seZdZejZejZdjeedZdjeeedZdZ e j e jde j e j Be jBZe j e jde j e j Be jBZe j djed e j e j Be jBZe j e jd e j e j Be jBZe j d jed e j e j Be jBZe j e jd e j e j Be jBZe j d jed e j e j Be jBZe j djed e j e j Be jBZe j e jde j e j Be jBZeZdZddZddZddZddZddZddZddZ dd Z!d!d"Z"d#d$Z#d%d&Z$e%d'd(Z&e%d)d*Z'd+d,Z(d-S).r4z (?:{type}|{xref}) # a container type [\(\[] [^\n]+ [\)\]] # with the contents of the container )r$xrefzo (?:{container_type}|{type}|{xref}) (?:\s+(?:of|or)\s+(?:{container_type}|{type}|{xref}))* )r$rurUzy ^([ ]*) {0} \s*: \s*$ # Google parameter header ( .* ) # section z(?:Args|Arguments|Parameters)z&Keyword\s(?:Args|Arguments|Parameters)a) \s* \*{{0,2}}(\w+) # identifier potentially with asterisks \s* ( [(] {type} (?:,\s+optional)? [)] )? \s* : # optional type declaration \s* (.*) # beginning of optional description )r$Raisesz \s* ({type}) \s* : # identifier \s* (.*) # beginning of optional description zReturns?z \s* ({type}:)? # identifier \s* (.*) # beginning of description z~ ^{type}: # indentifier \s* (.*) # Summary line / description zYields?TcCsLt|jj|jpH|jj|jpH|jj|jpH|jj|jpH|jj|jS)N) rVre_param_sectionrKr>re_raise_sectionre_returns_sectionre_yields_sectionre_property_returns_line _first_line)r?rrrr6 s zGoogleDocstring.is_validcCs|js dS|jj|jdk S)NF)r>rwrK)r?rrrrBszGoogleDocstring.has_paramscCsL|js dS|j|j}x0|D](}|jj|}|s2q|jd}|rdSqWdS)NFrdT)r>_parse_sectionryre_returns_linerar^)r?entriesentryraZ return_descrrrrCs    zGoogleDocstring.has_returnscCsL|js dS|j|j}x0|D](}|jj|}|s2q|jd}|rdSqWdS)NFr\T)r>r}ryr~rar^)r?rrra return_typerrrrD+s    zGoogleDocstring.has_rtypecCs>|j}t|jj|p8|jj|p8|jj|p8|jj| S)N)r|rVrwrKrxryrz)r? first_linerrrrE;s    z$GoogleDocstring.has_property_returnscCs|js dSt|jj|jS)NF)r>rVr{rar|)r?rrrrFFsz!GoogleDocstring.has_property_typecCsL|js dS|j|j}x0|D](}|jj|}|s2q|jd}|rdSqWdS)NFrdT)r>r}rzre_yields_linerar^)r?rrraZ yield_descrrrrGLs    zGoogleDocstring.has_yieldscCsL|js dS|j|j}x0|D](}|jj|}|s2q|jd}|rdSqWdS)NFr\T)r>r}rzrrar^)r?rrraZ yield_typerrrrH\s    zGoogleDocstring.has_yields_typecCsXt}|j|j}x@|D]8}|jj|}|s.q|jd}|jd}|r|j|qW|S)Nr\rd)r*r}rx re_raise_linerar^r_)r?r`rrraexc_typeZexc_descrrrrAls     zGoogleDocstring.exceptionsc Cst}t}|j|j}|j|j|jxX|D]P}|jj|}|sFq0|jd}|jd}|jd}|rr|j||r0|j|q0W||fS)Nr\rd) r*r}rwextendre_keyword_param_section re_param_linerar^r_) r?rhrirrra param_namerjZ param_descrrrrI|s        z GoogleDocstring.match_param_docscCs|jjjdddS)N r\r)r>rsplit)r?rrrr|szGoogleDocstring._first_linecCst|jddS)Nr\)rr^) section_matchrrrmin_section_indentsz"GoogleDocstring.min_section_indentcCsdS)NFr)_rrr_is_section_headersz"GoogleDocstring._is_section_headerc Cs|j|j}|dkrgS|j|}g}g}d}xt|jdjD]b}|jsLq>t|}||kr^P|rj|}d}||kr|j|r~P|r|jdj |g}|j|q>W|r|jdj ||S)NTrdFr) rKr>rr^ splitlinesstripr rr)join) r?Z section_rerZmin_indentationrrZis_firstline indentationrrrr}s4   zGoogleDocstring._parse_sectionN))rMrNrOr2rkrmrlZre_container_typere_multiple_type_re_section_templaterPrQrRrSMrwrrrxrryr~r{rzrrTr6rBrCrDrErFrGrHrArIr| staticmethodrrr}rrrrr4sf      r4c@seZdZdZejejdejejBej BZ ejdje j dejejBZ ejejdejejBej BZejdje jdejejBej BZejejdejejBej BZejdje j dejejBej BZejejd ejejBej BZeZd Zed d Zed dZdS)r5z ^([ ]*) {0} \s*?$ # Numpy parameters header \s* [-=]+ \s*?$ # underline ( .* ) # section z(?:Args|Arguments|Parameters)a \s* (\w+) # identifier \s* : \s* (?:({type})(?:,\s+optional)?)? # optional type declaration \n # description starts on a new line \s* (.*) # description )r$rvz_ \s* ({type})$ # type declaration \s* (.*) # optional description zReturns?z \s* (?:\w+\s+:\s+)? # optional name ({type})$ # type declaration \s* (.*) # optional description zYields?TcCst|jdS)Nr\)rr^)rrrrrsz!NumpyDocstring.min_section_indentcCsttjd|S)Nz\s*-+$)rVrPra)rrrrr sz!NumpyDocstring._is_section_headerN)rMrNrOrrPrQrlrRrSrrwr4rrrxrkrryr~rzrrTrrrrrrrr5s4 r5)ZsphinxZepytextZgooglenumpyr1)r1)rsrPr Zpylint.checkersrr rrrrr0r;r9r2r3r4r5r7rrrrs0  4 65H