o
    g[                     @   s   d Z ddlZddlmZ ddlZddlmZ ddlmZ dd Zdd	 Z	d
d Z
dd Zdd Zdedee f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.    N)List)nodes)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	   a/home/ubuntu/cloudmapper/venv/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)
decoratorsr   
isinstance	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: 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   r   node_frame_classgetattrr   decorated_with_property)r   	property_property_name
class_nodeclass_attrsattrr	   r	   r
   get_setters_propertyB   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   Const)return_nodereturnsr	   r	   r
   returns_somethingZ   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_targetl   s
   
r*   targetreturnc                 C   s   d}t || S )Nz(\s*,(?:\s*or\s)?\s*|\s+or\s+))resplit)r+   
delimitersr	   r	   r
   _split_multiple_exc_typest   s   r0   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 )aK  
    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: nodes.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%   )astroidUninferabler   .0r&   r	   r	   r
   	<genexpr>   s    z%possible_exc_types.<locals>.<genexpr>c                    s   h | ]
}t  |s|qS r	   )r   node_ignores_exceptionr3   r   r	   r
   	<setcomp>   s    z%possible_exc_types.<locals>.<setcomp>)r   r&   r   r   r   r)   r   parentExceptHandlertyper1   unpack_inferr*   ClassDefFunctionDefnodes_of_classReturnframer    Instanceinherit_from_std_exappendInferenceErrorset)r   excsinferredhandlerinferred_excsr+   retvalr	   r7   r
   possible_exc_typesy   sH   



rM   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)	docstringdefault_typedocstring_typeinstancer	   r	   r
   docstringify   s   r[   c                   @   s   e Zd ZU edejejB ZdZe	e
d< 	 dd Zdef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 ) rV   z=
        For\s+the\s+(other)?\s*parameters\s*,\s+see
        Fsupports_yieldsc                 C   s   |pd}|  | _d S )N )
expandtabsdoc)selfr_   r	   r	   r
   __init__   s   zDocstring.__init__r,   c                 C   s   d| j j d| j dS )N<z:'''z'''>)	__class____name__r_   r`   r	   r	   r
   __repr__   s   zDocstring.__repr__c                 C      dS NFr	   re   r	   r	   r
   rS         zDocstring.is_validc                 C   s   t  S r%   rF   re   r	   r	   r
   
exceptions   s   zDocstring.exceptionsc                 C   rg   rh   r	   re   r	   r	   r
   
has_params   ri   zDocstring.has_paramsc                 C   rg   rh   r	   re   r	   r	   r
   has_returns   ri   zDocstring.has_returnsc                 C   rg   rh   r	   re   r	   r	   r
   	has_rtype   ri   zDocstring.has_rtypec                 C   rg   rh   r	   re   r	   r	   r
   has_property_returns   ri   zDocstring.has_property_returnsc                 C   rg   rh   r	   re   r	   r	   r
   has_property_type   ri   zDocstring.has_property_typec                 C   rg   rh   r	   re   r	   r	   r
   
has_yields   ri   zDocstring.has_yieldsc                 C   rg   rh   r	   re   r	   r	   r
   has_yields_type   ri   zDocstring.has_yields_typec                 C   s   t  t  fS r%   rj   re   r	   r	   r
   match_param_docs   s   zDocstring.match_param_docsc                 C   s   | j | jd uS r%   )re_for_parameters_seesearchr_   re   r	   r	   r
   params_documented_elsewhere   s   z%Docstring.params_documented_elsewhereN)rd   
__module____qualname__r-   compileXSrt   r\   bool__annotations__ra   strrf   rS   rk   rl   rm   rn   ro   rp   rq   rr   rs   rv   r	   r	   r	   r
   rV      s(   
 
rV   c                   @   s  e Zd ZdZde dZdjeedZde dZde d	e d
Ze	
ee	je	jB Zde dZe	
ee	je	jB Zde dZe	
ee	je	jB Zd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 )%rO   zt
        [~!.]?               # Optional link style prefix
        \w(?:\w|\.[^\.])*    # Valid python name
        z	
        zw                     # a container type
        [\(\[] [^\n\s]+ [\)\]]        # with the contents of the container
    zm
        (?:{container_type}|{type})
        (?:(?:\s+(?:of|or)\s+|\s*,\s*)(?:{container_type}|{type}))*
    )r;   container_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+
        )?

        (\w+)                   # Parameter name
        \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?:Fc                 C   sJ   t | j| jp#| j| jp#| j| jp#| j| jp#| j| jS r%   )r|   re_param_in_docstringru   r_   re_raise_in_docstringre_rtype_in_docstringre_returns_in_docstringre_property_type_in_docstringre   r	   r	   r
   rS   C  s   zSphinxDocstring.is_validc                 C   s8   t  }t| j| jD ]}|d}|t| q|S N   )rF   r-   finditerr   r_   groupupdater0   )r`   typesmatch
raise_typer	   r	   r
   rk   L  s
   
zSphinxDocstring.exceptionsc                 C      | j sdS | j| j d uS rh   )r_   r   ru   re   r	   r	   r
   rl   U     zSphinxDocstring.has_paramsc                 C      | j sdS t| j| j S rh   )r_   r|   r   ru   re   r	   r	   r
   rm   [  r   zSphinxDocstring.has_returnsc                 C   r   rh   )r_   r|   r   ru   re   r	   r	   r
   rn   a  r   zSphinxDocstring.has_rtypec                 C   s   | j sdS | j  d S )NF:)r_   r   
startswithre   r	   r	   r
   ro   g  s   z$SphinxDocstring.has_property_returnsc                 C   r   rh   )r_   r|   r   ru   re   r	   r	   r
   rp   o  r   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   r   )
rF   r-   r   r   r_   r   addr   findallre_type_in_docstring)r`   params_with_docparams_with_typer   r   
param_typer	   r	   r
   rs   u  s   



z SphinxDocstring.match_param_docsN)rd   rw   rx   re_typere_simple_container_typeformatre_multiple_simple_typere_xrefre_param_rawr-   ry   rz   r{   r   re_type_rawr   re_property_type_rawr   re_raise_rawr   r   r   r\   rS   rk   rl   rm   rn   ro   rp   rs   r	   r	   r	   r
   rO      sR    



		rO   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 )
rP   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
    r   @r   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   )r_   rp   r   r   re   r	   r	   r
   ro     s
   z%EpytextDocstring.has_property_returnsN)rd   rw   rx   __doc__r-   ry   rO   r   replacerz   r{   r   r   r   r   r   r   r   r   r   ro   r	   r	   r	   r
   rP     s(    


rP   c                   @   s  e Zd ZejZejZde d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	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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e de
je
jB e
jB Ze
d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/d0 Z(d1S )2rQ   z
        (?:r   zj)       # a container type
        [\(\[] [^\n]+ [\)\]]          # with the contents of the container
    z{
        (?:{container_type}|{type}|{xref})
        (?:(?:\s+(?:of|or)\s+|\s*,\s*)(?:{container_type}|{type}|{xref}))*
    )r;   xrefr   zy
        ^([ ]*)   {0} \s*:   \s*$     # Google parameter header
        (  .* )                       # section
        (?:Args|Arguments|Parameters)z&Keyword\s(?:Args|Arguments|Parameters)zn
        \s*  \*{0,2}(\w+)             # identifier potentially with asterisks
        \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

        ^zb:           # 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%   )	r|   re_param_sectionru   r_   re_raise_sectionre_returns_sectionre_yields_sectionre_property_returns_line_first_linere   r	   r	   r
   rS     s   zGoogleDocstring.is_validc                 C   r   rh   )r_   r   ru   re   r	   r	   r
   rl     r   zGoogleDocstring.has_paramsc                 C   J   | j sdS | | j}|D ]}| j|}|sq|d}|r" dS qdS NFr   Tr_   _parse_sectionr   re_returns_liner   r   )r`   entriesentryr   return_descr	   r	   r
   rm        
zGoogleDocstring.has_returnsc                 C   r   NFr   Tr   )r`   r   r   r   return_typer	   r	   r
   rn   ,  r   zGoogleDocstring.has_rtypec                 C   s>   |   }t| j|p| j|p| j|p| j| S r%   )r   r|   r   ru   r   r   r   )r`   
first_liner	   r	   r
   ro   <  s   


z$GoogleDocstring.has_property_returnsc                 C   s   | j sdS t| j|  S rh   )r_   r|   r   r   r   re   r	   r	   r
   rp   G  s   z!GoogleDocstring.has_property_typec                 C   r   r   r_   r   r   re_yields_liner   r   )r`   r   r   r   
yield_descr	   r	   r
   rq   M  r   zGoogleDocstring.has_yieldsc                 C   r   r   r   )r`   r   r   r   
yield_typer	   r	   r
   rr   ]  r   zGoogleDocstring.has_yields_typec                 C   sX   t  }| | j}|D ]}| j|}|sq|d}|d}|r)|t| q|S )Nr   r   )rF   r   r   re_raise_liner   r   r   r0   )r`   r   r   r   r   exc_typeexc_descr	   r	   r
   rk   m  s   

zGoogleDocstring.exceptionsc           	      C   s   t  }t  }| | j}|| | j |D ](}| j|}|s"q|d}|d}|d}|r8|| |r?|| q||fS )Nr   r      )	rF   r   r   extendre_keyword_param_sectionre_param_liner   r   r   )	r`   r   r   r   r   r   
param_namer   
param_descr	   r	   r
   rs   }  s"   




z GoogleDocstring.match_param_docsc                 C   s   | j  ddd S )N
r   r   )r_   r   r.   re   r	   r	   r
   r     s   zGoogleDocstring._first_linec                 C   s   t | dd S r   r   r   section_matchr	   r	   r
   min_section_indent  s   z"GoogleDocstring.min_section_indentc                 C   rg   rh   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 )NTr   Fr   )
ru   r_   r   r   
splitlinesstripr   r   rD   join)	r`   
section_rer   min_indentationr   r   is_firstlineindentationr	   r	   r
   r     s4   

zGoogleDocstring._parse_sectionN))rd   rw   rx   rO   r   r   re_container_typer   re_multiple_type_re_section_templater-   ry   rz   r{   Mr   r   r   r   r   r   r   r   r   r   r\   rS   rl   rm   rn   ro   rp   rq   rr   rk   rs   r   staticmethodr   r   r   r	   r	   r	   r
   rQ     s    	

rQ   c                   @   s  e Zd ZdZeedejejB ej	B Z
edej dejejB ZeedejejB ej	B Zed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	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 )rR   z
        ^([ ]*)   {0}   \s*?$          # Numpy parameters header
        \s*     [-=]+   \s*?$          # underline
        (  .* )                        # section
    r   zz
        \s*  (\w+)                                                          # identifier
        \s*  :
        \s*  (?:(a  )(?:,\s+optional)?)?     # optional type declaration
        \n                                                                  # description starts on a new line
        \s* (.*)                                                            # description
    r   r   z^)$   # type declaration
        \s* (.*)                           # optional description
    r   z6
        \s* (?:\w+\s+:\s+)? # optional name
        (zc)$   # type declaration
        \s* (.*)                                # optional description
    r   Tc                 C   s   t | dS r   r   r   r	   r	   r
   r      s   z!NumpyDocstring.min_section_indentc                 C   s   t td| S )Nz\s*-+$)r|   r-   r   )r   r	   r	   r
   r     s   z!NumpyDocstring._is_section_headerN)rd   rw   rx   r   r-   ry   r   rz   r{   r   r   rQ   r   r   r   r   r   r   r   r   r   r\   r   r   r   r	   r	   r	   r
   rR     sN    
	
rR   )sphinxepytextgooglenumpyrN   )rN   )r   r-   typingr   r1   r   pylint.checkersr   r   r   r   r$   r*   r~   r0   rM   r[   rV   rO   rP   rQ   rR   rT   r	   r	   r	   r
   <module>   s:   
49 5  B