o
    b*Y                     @   s   d Z ddlmZmZ ddlZddlZddlmZ dd Zdd Z	d	d
 Z
dd Zdd Zdd ZdddZG dd dZG dd deZG dd deZG dd deZG dd deZeeeeedZdS ) z'Utility methods for docstring checking.    )absolute_importprint_functionN)utilsc                 C   s   t | t | d S )zThe number of leading spaces in a string

    :param str s: input string

    :rtype: int
    :return: number of leading spaces
     )lenlstrip)s r	   b/var/www/secure340b-portal/env/lib/python3.10/site-packages/pylint/extensions/_check_docs_utils.pyspace_indentation   s   r   c                 C   sP   | j r| j jng }|D ]}t|tjr%|jdkr%t|jtjr%|jj  S qdS )a  Get 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)	
decoratorsnodes
isinstanceastroid	AttributeattrnameexprNamename)noder   	decoratorr	   r	   r
   get_setters_property_name'   s   

r   c                 C   sL   d}t | }t| }|r$|r$|| j}|D ]}t|r#|} |S q|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)r   r   Znode_frame_classgetattrr   Zdecorated_with_property)r   Z	property_Zproperty_nameZ
class_nodeZclass_attrsattrr	   r	   r
   get_setters_property<   s   


r   c                 C   s*   | j }|du r	dS t|tjo|j du  S )a  Check 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   ZConst)Zreturn_nodereturnsr	   r	   r
   returns_somethingT   s   
r   c                 C   s6   t | jtjr| jj}t |tjtjfrt|S d S N)	r   excr   Callfuncr   r   r   
safe_infer)r   r"   r	   r	   r
   _get_raise_targetf   s
   
r$   c                    s:  g }t  jtjrt j}|r|jg}no jdu rD j}|r1t |tjs1|j}|r1t |tjr&|rC|j	rCt
|j	}dd |D }nAt }t |tjrS|jg}n2t |tjr|tjD ]%}| |krhq_t|j}|rt |tjtjfrt|r||j q_z
 fdd|D W S  tjy   t  Y S w )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)
    Nc                 s   s     | ]}|t jur|jV  qd S r   )r   ZUninferabler   .0r    r	   r	   r
   	<genexpr>   s    z%possible_exc_types.<locals>.<genexpr>c                    s   h | ]
}t  |s|qS r	   )r   Znode_ignores_exceptionr%   r   r	   r
   	<setcomp>   s    z%possible_exc_types.<locals>.<setcomp>)r   r    r   r   r   r#   r   parentExceptHandlertypeZunpack_inferr$   ClassDefFunctionDefZnodes_of_classReturnframer   InstanceZinherit_from_std_exappendZInferenceErrorset)r   ZexcsinferredhandlerZinferred_excstargetretvalr	   r(   r
   possible_exc_typesn   sH   



r9   defaultc                 C   s>   t tttfD ]}|| }| r|  S qt|t}|| S r   )SphinxDocstringEpytextDocstringGoogleDocstringNumpyDocstringis_validDOCSTRING_TYPESget	Docstring)	docstringZdefault_typeZdocstring_typeinstancer	   r	   r
   docstringify   s   rE   c                   @   s   e Zd ZedejejB ZdZ	 dd Z	dd Z
dd Zd	d
 Zdd Zdd Zdd Zdd Zdd Zdd Zdd Zdd ZdS )rB   z=
        For\s+the\s+(other)?\s*parameters\s*,\s+see
        Nc                 C   s   |pd}|  | _d S )N )
expandtabsdoc)selfrH   r	   r	   r
   __init__   s   zDocstring.__init__c                 C      dS NFr	   rI   r	   r	   r
   r?         zDocstring.is_validc                 C   s   t  S r   r3   rM   r	   r	   r
   
exceptions   s   zDocstring.exceptionsc                 C   rK   rL   r	   rM   r	   r	   r
   
has_params   rN   zDocstring.has_paramsc                 C   rK   rL   r	   rM   r	   r	   r
   has_returns   rN   zDocstring.has_returnsc                 C   rK   rL   r	   rM   r	   r	   r
   	has_rtype   rN   zDocstring.has_rtypec                 C   rK   rL   r	   rM   r	   r	   r
   has_property_returns   rN   zDocstring.has_property_returnsc                 C   rK   rL   r	   rM   r	   r	   r
   has_property_type   rN   zDocstring.has_property_typec                 C   rK   rL   r	   rM   r	   r	   r
   
has_yields   rN   zDocstring.has_yieldsc                 C   rK   rL   r	   rM   r	   r	   r
   has_yields_type   rN   zDocstring.has_yields_typec                 C   s   t  t  fS r   rO   rM   r	   r	   r
   match_param_docs   s   zDocstring.match_param_docsc                 C   s   | j | jd uS r   )re_for_parameters_seesearchrH   rM   r	   r	   r
   params_documented_elsewhere   s   z%Docstring.params_documented_elsewhere)__name__
__module____qualname__recompileXSrY   supports_yieldsrJ   r?   rP   rQ   rR   rS   rT   rU   rV   rW   rX   r[   r	   r	   r	   r
   rB      s&    
rB   c                   @   s   e Zd ZdZdjedZdeZdjeedZe	eej
ejB ZdjedZe	eej
ejB ZdjedZe	eej
ejB Zd	jedZe	eej
ejB Ze	d
Ze	dZdZdd Zdd Zdd Zdd Zdd Zdd Zdd Zdd ZdS )r;   zt
        [~!]?                # 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?:Fc                 C   sJ   t | j| jp#| j| jp#| j| jp#| j| jp#| j| jS r   )boolre_param_in_docstringrZ   rH   re_raise_in_docstringre_rtype_in_docstringre_returns_in_docstringre_property_type_in_docstringrM   r	   r	   r
   r?   :  s   zSphinxDocstring.is_validc                 C   s4   t  }t| j| jD ]}|d}|| q|S N   )r3   r_   finditerrh   rH   groupadd)rI   typesmatchZ
raise_typer	   r	   r
   rP   C  s
   
zSphinxDocstring.exceptionsc                 C      | j sdS | j| j d uS rL   )rH   rg   rZ   rM   r	   r	   r
   rQ   L     zSphinxDocstring.has_paramsc                 C      | j sdS t| j| j S rL   )rH   rf   rj   rZ   rM   r	   r	   r
   rR   R  rt   zSphinxDocstring.has_returnsc                 C   ru   rL   )rH   rf   ri   rZ   rM   r	   r	   r
   rS   X  rt   zSphinxDocstring.has_rtypec                 C   s   | j sdS | j  d S )NF:)rH   r   
startswithrM   r	   r	   r
   rT   ^  s   z$SphinxDocstring.has_property_returnsc                 C   ru   rL   )rH   rf   rk   rZ   rM   r	   r	   r
   rU   f  rt   z!SphinxDocstring.has_property_typec                 C   sp   t  }t  }t| j| jD ]}|d}|| |d}|d ur(|| q|t| j	| j ||fS )N   rm   )
r3   r_   rn   rg   rH   ro   rp   updatefindallre_type_in_docstring)rI   params_with_docparams_with_typerr   r   
param_typer	   r	   r
   rX   l  s   



z SphinxDocstring.match_param_docsN)r\   r]   r^   re_typeformatZre_simple_container_typere_xrefre_param_rawr_   r`   ra   rb   rg   re_type_rawr{   re_property_type_rawrk   re_raise_rawrh   ri   rj   rc   r?   rP   rQ   rR   rS   rT   rU   rX   r	   r	   r	   r
   r;      sT    	


		r;   c                   @   s   e Zd ZdZeejdddej	ej
B Zeejdddej	ej
B Zeejdddej	ej
B Zeejdddej	ej
B Zedej	ej
B ZedZdd Zd	S )
r<   a  
    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
    rv   @rm   z
        @                       # initial "at" symbol
        (?:                     # Epytext keyword
        rtype|returntype
        )
        :                       # final colon
        z
@returns?:c                 C   s(   | j sdS |  r| j  d S dS )NFr   )rH   rU   r   rw   rM   r	   r	   r
   rT     s
   z%EpytextDocstring.has_property_returnsN)r\   r]   r^   __doc__r_   r`   r;   r   replacera   rb   rg   r   r{   r   rk   r   rh   ri   rj   rT   r	   r	   r	   r
   r<   {  s(    


r<   c                   @   s  e Zd ZejZejZdjeedZdjeeedZdZ	e
e	de
je
jB e
jB Ze
e	de
je
jB e
jB Ze
djed	e
je
jB e
jB Ze
e	d
e
je
jB e
jB Ze
djed	e
je
jB e
jB Ze
e	de
je
jB e
jB Ze
djed	e
je
jB e
jB Ze
djed	e
je
jB e
jB Ze
e	de
je
jB e
jB ZeZdZdd Zdd Zdd Zdd Zdd Zdd Zdd Z dd  Z!d!d" Z"d#d$ Z#d%d& Z$e%d'd( Z&e%d)d* Z'd+d, Z(d-S ).r=   z
        (?:{type}|{xref})             # a container type
        [\(\[] [^\n]+ [\)\]]          # with the contents of the container
    )r,   xrefzh
        (?:{container_type}|{type}|{xref})
        (?:\s+or\s+(?:{container_type}|{type}|{xref}))*
    )r,   r   re   zy
        ^([ ]*)   {0} \s*:   \s*$     # Google parameter header
        (  .* )                       # section
        (?: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
    rd   Raisesz
        \s*  ({type}) \s* :              # identifier
        \s*  (.*)                        # beginning of optional description
    Returns?z
        \s* ({type}:)?                    # identifier
        \s* (.*)                          # beginning of description
    z~
        ^{type}:                       # indentifier
        \s* (.*)                       # Summary line / description
    Yields?Tc                 C   sL   t | j| jp$| j| jp$| j| jp$| j| jp$| j|  S r   )	rf   re_param_sectionrZ   rH   re_raise_sectionre_returns_sectionre_yields_sectionre_property_returns_line_first_linerM   r	   r	   r
   r?     s   zGoogleDocstring.is_validc                 C   rs   rL   )rH   r   rZ   rM   r	   r	   r
   rQ     rt   zGoogleDocstring.has_paramsc                 C   J   | j sdS | | j}|D ]}| j|}|sq|d}|r" dS qdS NFrx   TrH   _parse_sectionr   re_returns_linerr   ro   )rI   entriesentryrr   Zreturn_descr	   r	   r
   rR        
zGoogleDocstring.has_returnsc                 C   r   NFrm   Tr   )rI   r   r   rr   return_typer	   r	   r
   rS   -  r   zGoogleDocstring.has_rtypec                 C   s>   |   }t| j|p| j|p| j|p| j| S r   )r   rf   r   rZ   r   r   r   )rI   
first_liner	   r	   r
   rT   =  s   


z$GoogleDocstring.has_property_returnsc                 C   s   | j sdS t| j|  S rL   )rH   rf   r   rr   r   rM   r	   r	   r
   rU   H  s   z!GoogleDocstring.has_property_typec                 C   r   r   rH   r   r   re_yields_linerr   ro   )rI   r   r   rr   Z
yield_descr	   r	   r
   rV   N  r   zGoogleDocstring.has_yieldsc                 C   r   r   r   )rI   r   r   rr   Z
yield_typer	   r	   r
   rW   ^  r   zGoogleDocstring.has_yields_typec                 C   sT   t  }| | j}|D ]}| j|}|sq|d}|d}|r'|| q|S )Nrm   rx   )r3   r   r   re_raise_linerr   ro   rp   )rI   rq   r   r   rr   exc_typeZexc_descr	   r	   r
   rP   n  s   


zGoogleDocstring.exceptionsc           	      C   s   t  }t  }| | j}|| | j |D ](}| j|}|s"q|d}|d}|d}|r8|| |r?|| q||fS )Nrm   rx      )	r3   r   r   extendre_keyword_param_sectionre_param_linerr   ro   rp   )	rI   r|   r}   r   r   rr   
param_namer~   Z
param_descr	   r	   r
   rX   ~  s"   




z GoogleDocstring.match_param_docsc                 C   s   | j  ddd S )N
rm   r   )rH   r   splitrM   r	   r	   r
   r     s   zGoogleDocstring._first_linec                 C   s   t | dd S rl   r   ro   section_matchr	   r	   r
   min_section_indent  s   z"GoogleDocstring.min_section_indentc                 C   rK   rL   r	   )_r	   r	   r
   _is_section_header  s   z"GoogleDocstring._is_section_headerc           	      C   s   | | j}|d u rg S | |}g }g }d}|d D ]3}| s%qt|}||k r/ n#|r5|}d}||krL| |r@ n|rL|d	| g }|| q|r\|d	| |S )NTrx   Fr   )
rZ   rH   r   ro   
splitlinesstripr   r   r2   join)	rI   Z
section_rer   Zmin_indentationr   r   Zis_firstlineindentationr	   r	   r
   r     s4   

zGoogleDocstring._parse_sectionN))r\   r]   r^   r;   r   r   r   Zre_container_typere_multiple_type_re_section_templater_   r`   ra   rb   Mr   r   r   r   r   r   r   r   r   r   rc   r?   rQ   rR   rS   rT   rU   rV   rW   rP   rX   r   staticmethodr   r   r   r	   r	   r	   r
   r=     s    



	

r=   c                   @   s  e Zd ZdZeedejejB ej	B Z
edjejdejejB ZeedejejB ej	B ZedjejdejejB ej	B ZeedejejB ej	B ZedjejdejejB ej	B Zeed	ejejB ej	B ZeZd
Zedd Zedd ZdS )r>   z
        ^([ ]*)   {0}   \s*?$          # Numpy parameters header
        \s*     [-=]+   \s*?$          # underline
        (  .* )                        # section
    r   a  
        \s*  (\w+)                      # identifier
        \s*  :
        \s*  (?:({type})(?:,\s+optional)?)? # optional type declaration
        \n                              # description starts on a new line
        \s* (.*)                        # description
    rd   r   z_
        \s* ({type})$   # type declaration
        \s* (.*)        # optional description
    r   z
        \s* (?:\w+\s+:\s+)? # optional name
        ({type})$                         # type declaration
        \s* (.*)                          # optional description
    r   Tc                 C   s   t | dS rl   r   r   r	   r	   r
   r     s   z!NumpyDocstring.min_section_indentc                 C   s   t td| S )Nz\s*-+$)rf   r_   rr   )r   r	   r	   r
   r     s   z!NumpyDocstring._is_section_headerN)r\   r]   r^   r   r_   r`   r   ra   rb   r   r   r=   r   r   r   r   r   r   r   r   r   rc   r   r   r   r	   r	   r	   r
   r>     sT    
	

r>   )ZsphinxZepytextZgooglenumpyr:   )r:   )r   
__future__r   r   r_   r   Zpylint.checkersr   r   r   r   r   r$   r9   rE   rB   r;   r<   r=   r>   r@   r	   r	   r	   r
   <module>   s6   
46 5  H