HEX

File: //usr/lib/python3/dist-packages/sphinx/ext/napoleon/__pycache__/docstring.cpython-310.pyc
o

�$�a]��	@s�dZddlZddlZddlZddlmZddlmZmZm	Z	m
Z
mZmZm
Z
ddlmZddlmZddlmZddlmZmZdd	lmZdd
lmZddlmZe�e�Z e�!d�Z"e�!d
�Z#e�!d�Z$e�!d�Z%e�!d�Z&e�!d�Z'e�!d�Z(e�!d�Z)e�!d�Z*e�!d�Z+e�!d�Z,dZ-ifde.de	e.e.fde.fdd�Z/Gdd�d�Z0de
e.de
e.fd d!�Z1d"e.de
e.fd#d$�Z2d-d%e.d&e.de.fd'd(�Z3difde.d&e.de4de.fd)d*�Z5Gd+d,�d,e0�Z6dS).z�
    sphinx.ext.napoleon.docstring
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


    Classes for docstring parsing and formatting.


    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
�N)�partial)�Any�Callable�Dict�List�Tuple�Type�Union)�Sphinx��Config)�modify_iter)�_�__)�logging)�stringify_annotation)�get_type_hintsz
\.\. \S+::z^(\s|\w)+:\s*$z(.+?)\(\s*(.*[^\s]+)\s*\)z^[=\-`:\'"~^_*+#<>]{2,}\s*$z(?<!:):(?!:)z>((?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:`.+?`)|(?:``.+?``))z5(?:(?::(?:[a-zA-Z0-9]+[\-_+:.])*[a-zA-Z0-9]+:)?`.+?`)z^(\*|\+|\-)(\s+\S|\s*$)zP^(?P<paren>\()?(\d+|#|[ivxlcdm]+|[IVXLCDM]+|[a-zA-Z])(?(paren)\)|\.)(\s+\S|\s*$)z_(,\sor\s|\sor\s|\sof\s|:\s|\sto\s|,\sand\s|\sand\s|,\s|[{]|[}]|"(?:\\"|[^"])*"|'(?:\\'|[^'])*')z^default[^_0-9A-Za-z].*$)�None�True�False�Ellipsis�_type�translations�returncCs$||vr||S|dkrdSd|S)z0Convert type specification to reference in reST.rz:obj:`None`�:class:`%s`�)rrrr�?/usr/lib/python3/dist-packages/sphinx/ext/napoleon/docstring.py�_convert_type_spec9s
rc@s�eZdZdZe�dej�Z			d�dee	e
e	fdedede	d	e	d
e
de
ddfd
d�Zde	fdd�Zde
e	fdd�Zd�dede
e	fdd�Zde
e	fdd�Zde
e	fdd�Zd�dededee	e	e
e	ffdd �Z		d�deded!ede
ee	e	e
e	ffd"d#�Zdee	e
e	ffd$d%�Zd�d&ede
ee	e	e
e	ffd'd(�Zde
e	fd)d*�Zde	fd+d,�Zde
e	fd-d.�Zde
e	fd/d0�Zd�d1e
e	d2ede
e	fd3d4�Zd	e	de	fd5d6�Z d7e
e	de
e	fd8d9�Z!d:e	d1e
e	de
e	fd;d<�Z"d�d=e	d1e
e	d>e	de
e	fd?d@�Z#	Bd�dCe
ee	e	e
e	fdDe	dEe	de
e	fdFdG�Z$dHe	dIe	dJe
e	de
e	fdKdL�Z%dMe	dCe
ee	e	e
e	fde
e	fdNdO�Z&d�dQedefdRdS�Z'dTe	defdUdV�Z(d1e
e	defdWdX�Z)d1e
e	defdYdZ�Z*d�d1e
e	d\ede
e	fd]d^�Z+d�dTe	dedefd_d`�Z,d1e
e	defdadb�Z-defdcdd�Z.defdedf�Z/d�dgdh�Z0d�didj�Z1d:e	dke	de
e	fdldm�Z2de
e	fdndo�Z3dke	de
e	fdpdq�Z4dke	de
e	fdrds�Z5dke	de
e	fdtdu�Z6dke	de
e	fdvdw�Z7dke	de
e	fdxdy�Z8dke	de
e	fdzd{�Z9dke	d|ede
e	fd}d~�Z:dke	de
e	fdd��Z;dke	de
e	fd�d��Z<dke	de
e	fd�d��Z=dke	de
e	fd�d��Z>dke	de
e	fd�d��Z?dke	de
e	fd�d��Z@dke	de
e	fd�d��ZAdke	de
e	fd�d��ZBdke	de
e	fd�d��ZCdke	de
e	fd�d��ZDdke	de
e	fd�d��ZEdke	de
e	fd�d��ZFdTe	dee	e	e	ffd�d��ZGd�e	d�eHde	fd�d��ZId1e
e	de
e	fd�d��ZJdHe	de	fd�d��ZKdS)��GoogleDocstringaVConvert Google style docstrings to reStructuredText.

    Parameters
    ----------
    docstring : :obj:`str` or :obj:`list` of :obj:`str`
        The docstring to parse, given either as a string or split into
        individual lines.
    config: :obj:`sphinx.ext.napoleon.Config` or :obj:`sphinx.config.Config`
        The configuration settings to use. If not given, defaults to the
        config object on `app`; or if `app` is not given defaults to the
        a new :class:`sphinx.ext.napoleon.Config` object.


    Other Parameters
    ----------------
    app : :class:`sphinx.application.Sphinx`, optional
        Application object representing the Sphinx process.
    what : :obj:`str`, optional
        A string specifying the type of the object to which the docstring
        belongs. Valid values: "module", "class", "exception", "function",
        "method", "attribute".
    name : :obj:`str`, optional
        The fully qualified name of the object.
    obj : module, class, exception, function, method, or attribute
        The object to which the docstring belongs.
    options : :class:`sphinx.ext.autodoc.Options`, optional
        The options given to the directive: an object with attributes
        inherited_members, undoc_members, show_inheritance and noindex that
        are True if the flag option of same name was given to the auto
        directive.


    Example
    -------
    >>> from sphinx.ext.napoleon import Config
    >>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True)
    >>> docstring = '''One line summary.
    ...
    ... Extended description.
    ...
    ... Args:
    ...   arg1(int): Description of `arg1`
    ...   arg2(str): Description of `arg2`
    ... Returns:
    ...   str: Description of return value.
    ... '''
    >>> print(GoogleDocstring(docstring, config))
    One line summary.
    <BLANKLINE>
    Extended description.
    <BLANKLINE>
    :param arg1: Description of `arg1`
    :type arg1: int
    :param arg2: Description of `arg2`
    :type arg2: str
    <BLANKLINE>
    :returns: Description of return value.
    :rtype: str
    <BLANKLINE>

    zX^\s*((?::(?P<role>\S+):)?`(?P<name>~?[a-zA-Z0-9_.-]+)`| (?P<name2>~?[a-zA-Z0-9_.-]+))\s*N��	docstring�config�app�what�name�obj�optionsrc
CsJ||_||_|jsddlm}|jr|jjn|�|_|s5t�|�r$d}nt�|�r,d}n	t|�r3d}nd}||_	||_
||_||_t
|t�rK|��}	n|}	t|	dd�d	�|_g|_d
|_d|_t|d�sgg|_t|d��sid
|j�d|j�dt|jd��d|j�dt|jd��dt|jd��dt|jd��d|j�d|j�dt|jd��dt|jd��d|j�d|j�d|j�dt|jd��d|j�d|j�id|j�d|j �d |j �d!|j!�d"|j!�d#|j"�d$|j"�d%|j#�d&|j$�d't|jd'��d(t|jd(��d)t|jd)��d*t|jd)��d+|j%�d,|j%�d-|j&�d.|j&��|_'|�(�|�)�dS)/Nrr�class�module�function�objectcSs|��S�N)�rstrip)�srrr�<lambda>��z*GoogleDocstring.__init__.<locals>.<lambda>)�modifierF�_directive_sections�	_sections�args�	arguments�	attention�
attributes�caution�danger�error�example�examples�hint�	importantzkeyword argszkeyword arguments�methods�note�noteszother parameters�
parameters�receive�receivesr�returns�raise�raises�
referenceszsee also�tip�todo�warning�warnings�warn�warns�yield�yields)*�_config�_app�sphinx.ext.napoleonrr!�inspect�isclass�ismodule�callable�_what�_name�_obj�_opt�
isinstance�str�
splitlinesr
�
_line_iter�
_parsed_lines�_is_in_section�_section_indent�hasattrr1�_parse_parameters_sectionr�_parse_admonition�_parse_attributes_section�_parse_examples_section� _parse_keyword_arguments_section�_parse_methods_section�_parse_notes_section�_parse_other_parameters_section�_parse_receives_section�_parse_returns_section�_parse_raises_section�_parse_references_section�_parse_see_also_section�_parse_warns_section�_parse_yields_sectionr2�_load_custom_sections�_parse)
�selfr r!r"r#r$r%r&r�linesrrr�__init__�s�




��������	�
���
������������������� �!�"�%zGoogleDocstring.__init__cCsd�|���S)z�Return the parsed docstring in reStructuredText format.

        Returns
        -------
        unicode
            Unicode version of the docstring.

        �
)�joinru�rtrrr�__str__�s	zGoogleDocstring.__str__cCs|jS)z�Return the parsed lines of the docstring in reStructuredText format.

        Returns
        -------
        list(str)
            The lines of the docstring in a list.

        )r_ryrrrru�s	zGoogleDocstring.lines��indentcCs\g}|j��}|��s,|r|�||�r,|�t|j��|j��}|��s,|r|�||�s|Sr+)r^�peek�_is_section_break�_is_indented�append�next)rtr|ru�linerrr�_consume_indented_block�s
�
�
��
�z'GoogleDocstring._consume_indented_blockcCsPg}|j��r&|j��r&|��s&|�t|j��|j��r&|j��r&|��r|Sr+)r^�has_nextr}�_is_section_headerr�r��rtrurrr�_consume_contiguous�s
��
���z#GoogleDocstring._consume_contiguouscCsHg}|j��}|j��r"|s"|�t|j��|j��}|j��r"|r|Sr+)r^r}r�r�r��rtrur�rrr�_consume_empty�s

�zGoogleDocstring._consume_emptyTF�
parse_type�prefer_typec
Cs�t|j�}|�|�\}}}|d|}}}	|r*t�|�}
|
r*|
�d���}|
�d�}|�|�}|r8|s8||}}|rG|jj	rGt
||jjpEi�}|�|�d}|	g|�
|�|��}|�||j���}|||fS)Nrr{�)r�r^�_partition_field_on_colon�_google_typed_arg_regex�match�group�strip�_escape_args_and_kwargsrP�napoleon_preprocess_typesr�napoleon_type_aliases�_get_indent�_dedentr��	__class__ru)
rtr�r�r��before�colon�afterrXr�_descr�r|�_descsrrr�_consume_fields"





zGoogleDocstring._consume_field�multiplec	Cs||��g}|��s<|�||�\}}}|r*|r*|�d�D]}|�|��||f�qn|s0|s0|r8|�|||f�|��r
|S)N�,)r�r~r��splitr�r�)	rtr�r�r��fieldsrXrr�r$rrr�_consume_fieldss��zGoogleDocstring._consume_fieldscCsbt|j�}|�|�\}}}|r|s||}}||7}|g|�|���}|�||j���}||fSr+)r�r^r�r��_consume_to_endr�rPru)rtr�rr�r�r�rrr�_consume_inline_attribute*s

z)GoogleDocstring._consume_inline_attribute�preprocess_typesc	Cs�|�|���}|rQ|�|d�\}}}dd|}}}|r1|r)|g|dd�}n|dd�}|}|rB|rB|jjrBt||jjp@i�}|�||j���}|||fgSgS)Nrrr{)	r��_consume_to_next_sectionr�rPr�rr�r�ru)	rtr�rur�r�r�rXrr�rrr�_consume_returns_section4s �z(GoogleDocstring._consume_returns_sectioncCs|�|���}|Sr+)r�r�r�rrr�_consume_usage_sectionLsz&GoogleDocstring._consume_usage_sectioncCs*t|j�}|�d�}|��|jvr|}|S)N�:)r�r^r��lowerr2)rt�section�stripped_sectionrrr�_consume_section_headerPs


z'GoogleDocstring._consume_section_headercCs,g}|j��r|�t|j��|j��s|Sr+)r^r�r�r�r�rrrr�Ws


�zGoogleDocstring._consume_to_endcCs8|��g}|��s|�t|j��|��r
||��Sr+)r�r~r�r�r^r�rrrr�]s�z(GoogleDocstring._consume_to_next_sectionru�fullcs.|r	dd�|D�S|�|���fdd�|D�S)NcSsg|]}|���qSr)�lstrip��.0r�rrr�
<listcomp>fsz+GoogleDocstring._dedent.<locals>.<listcomp>csg|]}|�d��qSr+rr���
min_indentrrr�i�)�_get_min_indent)rtrur�rr�rr�ds
zGoogleDocstring._dedentcCsl|�d�rt|jdd�r|dd�d}|dd�dkr$d|dd�S|dd	�d
kr4d|d	d�S|S)Nr�strip_signature_backslashF���z\_r�z**z\*\*r{�*z\*)�endswith�getattrrP�rtr$rrrr�ksz'GoogleDocstring._escape_args_and_kwargs�desccCs||�|�rdg|}|S|d�d�r<|dd�}|�|d�}|�|�}||kr0dg|}|Sd|dg|�|d�}|S)Nrr�::r{�)�_is_listr�r��_get_initial_indent�_indent)rtr��
desc_blockr|�block_indentrrr�_fix_field_descvs

	�

�zGoogleDocstring._fix_field_desc�
admonitioncCsf|�|�}t|�dkrd||d��fdgS|r-|�|�|�d�}d|dg|dgSd|dgS)Nr{z
.. %s:: %srr�z.. %s::)�_strip_empty�lenr�r�r�)rtr�rurrr�_format_admonition�s
z"GoogleDocstring._format_admonition�prefix�paddingcCsr|r6|durdt|�}g}t|�D]!\}}|dkr$|�||���q|r.|�||�q|�d�q|S|gS)N� rr)r��	enumerater�r,)rtr�rur��result_lines�ir�rrr�
_format_block�szGoogleDocstring._format_block�param�typer��
field_role�	type_rolec	Cs�g}|D]8\}}}|�|�}t|�r'|�|�}d||f}|�|�||��n	|�d||f�|r<|�d|||f�q|dgS)Nz:%s %s: z:%s %s:z
:%s %s: %sr)r��anyr��extendr�r�)	rtr�r�r�rurXrr��fieldrrr�_format_docutils_params�s

�
z'GoogleDocstring._format_docutils_paramsrXrr�cCs�|�|�}t|�}|r
dnd}|r.|r'd|vrd|||f}n%d|||f}nd||f}n|rBd|vr;d||f}n	d||f}nd}|ra|�|�}|d	r\||d	g|d
d�S|g|S|gS)Nz -- r�`z
**%s** (%s)%sz**%s** (*%s*)%sz**%s**%sz%s%sz*%s*%srr{)r�r�r�)rtrXrr��has_desc�	separatorr�rrr�
_format_field�s(


zGoogleDocstring._format_field�
field_typec
Cs�d|��}dt|�}t|�dk}g}|D]3\}}}|�|||�}	|r>|r2|�|�|d|	��q|�|�|d|	��q|�|�|d|	��q|rU|drU|�d�|S)Nz:%s:r�r{z * r�r)r�r�r�r�r�r�)
rtr�r�r��multirurXrr�r�rrr�_format_fields�s
zGoogleDocstring._format_fieldsr�
peek_aheadcCsZ|j�|d�|}||jjkr+|r|�|�S|d7}|j�|d�|}||jjksdS)Nr{r)r^r}�sentinelr�)rtr�r�rrr�_get_current_indent�s
�z#GoogleDocstring._get_current_indentr�cCs*t|�D]\}}|��s|Sqt|�Sr+)r��isspacer�)rtr�r�r-rrrr��s
�zGoogleDocstring._get_indentcCs |D]}|r
|�|�SqdS�Nr�r�r�rrrr��s
�z#GoogleDocstring._get_initial_indentcCs>d}|D]}|r|�|�}|dur|}q||kr|}q|pdSr�r�)rtrur�r�r|rrrr��s
�zGoogleDocstring._get_min_indentr��ncs�fdd�|D�S)Ncsg|]}d�|�qS)r�rr��r�rrr��r�z+GoogleDocstring._indent.<locals>.<listcomp>r)rtrur�rr�rr��szGoogleDocstring._indentcCs2t|�D]\}}||krdS|��sdSqdS)NTF)r�r�)rtr�r|r�r-rrrrs�zGoogleDocstring._is_indentedcCs�|sdSt�|d�r
dSt�|d�rdSt|�dks#|d�d�r%dS|�|d�}|}|dd�D]}|rB|�|�}||kSq4||kS)NFrTr�r�r{)�_bullet_list_regexr��_enumerated_list_regexr�r�r�)rtrur|�next_indentr�rrrr�	s"
�zGoogleDocstring._is_listcCsz|j����}t�|�}|r%|�d�|jvr%|�|�}|jdd�}||kS|j	r;t
�|�r;|j	D]
}|�|�r:dSq0dS)Nr�r{)r�TF)r^r}r��_google_section_regexr�r�r2r�r�r1�_directive_regex�
startswith)rtr�r��
header_indent�section_indent�directive_sectionrrrr�s




�z"GoogleDocstring._is_section_headercCs8|j��}|j��p|��p|jo|o|�||j�Sr+�r^r}r�r�r`rra)rtr�rrrr~(s
���z!GoogleDocstring._is_section_breakcCs�|jjdurP|jjD]G}t|t�r|j|j|��<q
|ddkr+|j|j|d��<q
|ddkr<|j|j|d��<q
|j�	|d��|j�|j|d��<q
dSdS)Nr{�params_styler�
returns_style)
rP�napoleon_custom_sectionsr[r\�_parse_custom_generic_sectionr2r��"_parse_custom_params_style_section�#_parse_custom_returns_style_section�get)rt�entryrrrrr0s 
�����z%GoogleDocstring._load_custom_sectionscCs|��|_|jr'|jdvr'g}z|��}Wn	tyYnw|j�|�dS|j��r|�	�rbz*|�
�}d|_|��|_
t�|�rJ|g|��}n	|j|��|�}Wd|_d|_
nd|_d|_
w|jsn|��|��}n|��}|j�|�|j��s,dSdS)N)�	attribute�data�propertyTFr)r�r_rXrW�_parse_attribute_docstring�
StopIterationr�r^r�r�r�r`r�rar�r�r�r2r�r�)rt�resr�rurrrrsFs:
�


���zGoogleDocstring._parser�cCs|��}|�||�Sr+)r�r�)rtr�r�rurrrrdhsz!GoogleDocstring._parse_admonitioncCs4|��\}}|�dd|�}|r|�dd|g�|S)Nr�	:type: %s)r�r�r�)rtrr�rurrrr�ms
z*GoogleDocstring._parse_attribute_docstringcCsg}|��D]q\}}}|s|�|�}|jjr6|�||j�}d|}|�|�||��|r5|�d||f�q|�d|�|j	rJd|j	vrJ|�d�|�d�|�
dd|�}|�|�|d��|rr|�d�|�|�d|gd��|�d�q|jjr�|�d�|S)	Nz
:ivar %s: z:vartype %s: %sz.. attribute:: �noindex�   :noindex:rr�r)r��_lookup_annotationrP�napoleon_use_ivar�
_qualify_namerYr�r�r�rZr�r�)rtr�rurXrr�r�r�rrrrets0
�



z)GoogleDocstring._parse_attributes_sectioncCs6td�td�d�}|jj}|�|��|�}|�||�S)N�Example�Examples)r:r;)rrP�$napoleon_use_admonition_for_examplesr�r��_parse_generic_section)rtr��labels�use_admonition�labelrrrrf�s�z'GoogleDocstring._parse_examples_sectioncCs|�|d�S)NF)r
�rtr�rrrr���z-GoogleDocstring._parse_custom_generic_sectioncCs|�||���Sr+)r�r�rrrrr��sz2GoogleDocstring._parse_custom_params_style_sectioncCs|jdd�}|�||�S)NT�r�)r�r��rtr�r�rrrr��sz3GoogleDocstring._parse_custom_returns_style_sectioncCs6ddg}ddg}|��}|�|d�}|||dgS)Nz.. rubric:: Usage:rz.. code-block:: pythonr�)r�r�)rtr��header�blockrurrr�_parse_usage_section�s
z$GoogleDocstring._parse_usage_sectionrcCsX|�|���}|�|�}|rd|}|�|d�}nd|}|r(|dg|dgS|dgS)Nz.. admonition:: %sr�z.. rubric:: %sr)r�r�r�r�)rtr�rrurrrrr
�s
z&GoogleDocstring._parse_generic_sectioncCs0|��}|jjr|j|ddd�S|�td�|�S)N�keyword�kwtype)r�r�zKeyword Arguments)r�rP�napoleon_use_keywordr�r�rrrrrrg�s�z0GoogleDocstring._parse_keyword_arguments_sectioncCsng}|jdd�D],\}}}|�d|�|jr!d|jvr!|�d�|r/|�dg|�|d��|�d�q|S)NF)r�z.. method:: %srrrr�)r�r�rZr�r�)rtr�rurXrr�rrrrh�s
z&GoogleDocstring._parse_methods_sectioncC�|jj}|�td�|�S)N�Notes)rP�!napoleon_use_admonition_for_notesr
r�rtr�rrrrri��z$GoogleDocstring._parse_notes_sectioncC�6|jjr|jdd�}|�|�S|��}|�td�|�S)NT�r�zOther Parameters�rP�napoleon_use_paramr�r�r�rrrrrrj��

z/GoogleDocstring._parse_other_parameters_sectioncCr)NTr�
Parametersrrrrrrc�r!z)GoogleDocstring._parse_parameters_sectionc
Cs�|jddd�}g}|D]M\}}}|j�|�}|r#|�d�r#|�d�}nt�|�r5|�d�}||dd�}|r;d|nd	}|�|�}t|�rMdd
�|�nd	}	|�	d||	f�q|r`|�	d	�|S)NFT)r�r�r$r�r{r�r�rz
    z:raises%s:%s)
r��	_name_rgxr�r��_xref_regex�findr�r�rxr�)
rtr�r�rurXrr��m�posr�rrrrm�s 



z%GoogleDocstring._parse_raises_sectioncCr)NTr�Receivesrrrrrrk�r!z'GoogleDocstring._parse_receives_sectioncCr)N�
References)rP�&napoleon_use_admonition_for_referencesr
rrrrrrn�rz)GoogleDocstring._parse_references_sectionc
Cs�|��}t|�dk}|rd}n|jj}g}|D]D\}}}|r&|�|d|�}	n|�|||�}	|rE|r;|�|�d|	��q|�|�d|	��q|�|�d|	��|r[|r[|�d|dg�q|rg|drg|�d�|S)	Nr{Frz          * z:returns: * z
:returns: z
:rtype: %sr�)r�r�rP�napoleon_use_rtyper�r�r�r�)
rtr�r�r��	use_rtyperurXrr�r�rrrrls*�
z&GoogleDocstring._parse_returns_sectioncCs|�d|�S�N�seealso)rdrrrrrosz'GoogleDocstring._parse_see_also_sectioncCs|�td�|���S)N�Warns)r�rr�rrrrrp sz$GoogleDocstring._parse_warns_sectioncCs|jdd�}|�td�|�S)NTr�Yields)r�r�rrrrrrq#sz%GoogleDocstring._parse_yields_sectionc	Cs�g}g}d}d}tt�|��D]A\}}|r|�|�qt�|�}|ddkrK|rKd}||��|���}|�|d|����|�||��d��q|�|�qd�|��	�|d�|��	�fS)NrFr�rT)
r��_xref_or_code_regexr�r��_single_colon_regex�search�start�endrxr�)	rtr��before_colon�after_colonr��found_colonr��sourcer&rrrr�'s$
�z)GoogleDocstring._partition_field_on_colon�	attr_name�klasscCsV|r)d|vr)|�d�r|dd�}z|j}Wnty"|j}Ynwd||fS|S)N�.�~r{z~%s.%s)r��__qualname__�AttributeError�__name__)rtr:r;�qrrrr=s


�zGoogleDocstring._qualify_namecCs�|rDd}t|�D]
\}}|r|}nq|dkrg}d}ttt|���D]}||}|r/|}nq#|dks<|dt|�krD|||d�}|S)Nr�rr{)r��reversed�ranger�)rtrur4r�r�r5rrrr�Hs&��zGoogleDocstring._strip_emptycCst|jjr8|jdvr8|jr8t|d�s,t|jdi�}|�t|jdi�p"i�t|jd|�|_||jvr8t	|j|�SdS)N)r(r'�	exception�_annotations�autodoc_type_aliasesr�r)
rP�napoleon_attr_annotationsrWrYrbr��updaterrEr)rtrX�localnsrrrr[s
��
z"GoogleDocstring._lookup_annotation�NNrrNN)r{�TF)TFF�Fr+)r�r�)r)r�)rN)Lr@�
__module__r>�__doc__�re�compile�Xr#r	r\r�SphinxConfigr
rrvrzru�intr�r�r��boolrr�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�r�rr�r�r~rrrsrdr�rerfr�r�r�rr
rgrhrirjrcrmrkrnrlrorprqr�rrr�rrrrrrFs�>�������
�L	
���
�


� 
$
���
�"
�	 

"	

			r�tokenscs2t�|�}d��fdd���fdd�}t||��S)N��optional�defaultc3s��d}d}	z|��}Wn
tyYdSw|dkr|}q|��s#q|�vr7|�|�|dur5|�|�dS|dur@|Vd}|dkrI|d7}n|dkrQ|d8}|V|dkrZdSq)NrT�, �{r{�})�popleft�
IndexErrorr��
appendleft)rU�open_braces�previous_token�token)�keywordsrr�
takewhile_setos<��


�z,_recombine_set_tokens.<locals>.takewhile_setc3sR�	z|��}Wn
tyYdSw|dkr%|�d�d��|��Vn|Vq)NTrZr)r\r]r^rx)rUra)rcrr�combine_set�s��
�z*_recombine_set_tokens.<locals>.combine_set)�collections�deque�list)rU�token_queuerdr)rbrcr�_recombine_set_tokensks

$
ri�speccs(dd��t�fdd�t�|�D��}|S)NcSs2t�|�r|dd�}|dd�}|d|gS|gS)N��r�)�_default_regexr�)�itemrX�otherrrr�postprocess�s


z(_tokenize_type_spec.<locals>.postprocessc3s&�|]}�|�D]}|r|VqqdSr+r)r��	raw_tokenrn�rprr�	<genexpr>�s����z&_tokenize_type_spec.<locals>.<genexpr>)rg�_token_regexr�)rjrUrrrr�_tokenize_type_spec�s
�rura�locationcCsFdd�}|�d�s|�d�rd}|S||�s4|�d�r |�d�s4|�d�r*|�d�s4|�d�r8|�d�r8d	}|S|�d�rKtjtd
�||d�d	}|S|�d�r^tjtd�||d�d	}|S|�d�sh|�d�rvtjtd
�||d�d	}|S|�d�s�|�d�r�tjtd�||d�d	}|S|dvr�d}|St�|�r�d}|Sd}|S)NcSs$zt|�WdStyYdSw)NFT)�complex�
ValueError)rarrr�
is_numeric�s
��z_token_type.<locals>.is_numericr��	delimiterrZr[�"�'�literalz-invalid value set (missing closing brace): %s�rvz-invalid value set (missing opening brace): %sz4malformed string literal (missing closing quote): %sz4malformed string literal (missing opening quote): %srV�control�	referencer%)r�r��loggerrJrr$r�)rarvry�type_rrr�_token_type�sx	-��������&
��
������
�
��r�cspdd��t|�}t|�}�fdd�|D�}dd���fdd�dd�d	d�d
d�d��d��fd
d�|D��}|S)NcSsP|�||�}|tvr|dkrd}n
|dkr|dkrd}t�|�dur&||}|S)Nr�	:obj:`%s`z...z:obj:`%s <Ellipsis>`)r��_SINGLETONSr$r�)r%r�default_translation�translationrrr�convert_obj�sz-_convert_numpy_type_spec.<locals>.convert_objcsg|]	}|t|��f�qSr)r�)r�rar~rrr�s��z,_convert_numpy_type_spec.<locals>.<listcomp>cS�d|S)Nz``%s``r��xrrrr.r/z*_convert_numpy_type_spec.<locals>.<lambda>cs�|�d�S)Nrrr�)r�rrrr.scSr�)Nz*%s*rr�rrrr.
r/cS�|Sr+rr�rrrr.�cSr�r+rr�rrrr.r�)r}r%rrzr�rc3s"�|]\}}��|�|�VqdSr+)r�)r�rar�)�
convertersrrrss� z+_convert_numpy_type_spec.<locals>.<genexpr>)rurirx)rrvrrU�combined_tokens�types�	convertedr)r�r�rvrr�_convert_numpy_type_spec�s
��r�cs eZdZdZ			d'deeeefdedededed	e	d
e	ddf�fdd
�
Z
defdd�Zdedef�fdd�Zd(de
de
deeeeeffdd�Zd)de
deeeeeeffdd�Zdefdd�Zde
fdd�Zde
fdd �Zd!edeefd"d#�Zd$eedeefd%d&�Z�ZS)*�NumpyDocstringa�
Convert NumPy style docstrings to reStructuredText.

    Parameters
    ----------
    docstring : :obj:`str` or :obj:`list` of :obj:`str`
        The docstring to parse, given either as a string or split into
        individual lines.
    config: :obj:`sphinx.ext.napoleon.Config` or :obj:`sphinx.config.Config`
        The configuration settings to use. If not given, defaults to the
        config object on `app`; or if `app` is not given defaults to the
        a new :class:`sphinx.ext.napoleon.Config` object.


    Other Parameters
    ----------------
    app : :class:`sphinx.application.Sphinx`, optional
        Application object representing the Sphinx process.
    what : :obj:`str`, optional
        A string specifying the type of the object to which the docstring
        belongs. Valid values: "module", "class", "exception", "function",
        "method", "attribute".
    name : :obj:`str`, optional
        The fully qualified name of the object.
    obj : module, class, exception, function, method, or attribute
        The object to which the docstring belongs.
    options : :class:`sphinx.ext.autodoc.Options`, optional
        The options given to the directive: an object with attributes
        inherited_members, undoc_members, show_inheritance and noindex that
        are True if the flag option of same name was given to the auto
        directive.


    Example
    -------
    >>> from sphinx.ext.napoleon import Config
    >>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True)
    >>> docstring = '''One line summary.
    ...
    ... Extended description.
    ...
    ... Parameters
    ... ----------
    ... arg1 : int
    ...     Description of `arg1`
    ... arg2 : str
    ...     Description of `arg2`
    ... Returns
    ... -------
    ... str
    ...     Description of return value.
    ... '''
    >>> print(NumpyDocstring(docstring, config))
    One line summary.
    <BLANKLINE>
    Extended description.
    <BLANKLINE>
    :param arg1: Description of `arg1`
    :type arg1: int
    :param arg2: Description of `arg2`
    :type arg2: str
    <BLANKLINE>
    :returns: Description of return value.
    :rtype: str
    <BLANKLINE>

    Methods
    -------
    __str__()
        Return the parsed docstring in reStructuredText format.

        Returns
        -------
        str
            UTF-8 encoded version of the docstring.

    __unicode__()
        Return the parsed docstring in reStructuredText format.

        Returns
        -------
        unicode
            Unicode version of the docstring.

    lines()
        Return the parsed lines of the docstring in reStructuredText format.

        Returns
        -------
        list(str)
            The lines of the docstring in a list.

    Nrr r!r"r#r$r%r&rc	s$dg|_t��|||||||�dS)Nz
.. index::)r1�superrv)rtr r!r"r#r$r%r&�r�rrrvtszNumpyDocstring.__init__cCsnz|jdurt�|j�nd}Wntyd}Ynw|j}|dur(|dur(dS|dur.d}d�|d|g�S)Nrr�zdocstring of %s)rYrS�getfile�	TypeErrorrXrx)rt�filepathr$rrr�
_get_locationzs�zNumpyDocstring._get_locationcs6t�j�d|vrd��fdd�|�d�D��S�|�S)NrYc3s�|]}�|�VqdSr+r)r�r���funcrrrs�s�z9NumpyDocstring._escape_args_and_kwargs.<locals>.<genexpr>)r�r�rxr�r�r�r�rr��sz&NumpyDocstring._escape_args_and_kwargsTFr�r�c	Cs�t|j�}|r|�|�\}}}n|d}}|��|��}}|�|�}|r,|s,|�|�}|r5|s5||}}|jjrFt||�	�|jj
pCid�}|�|�d}|�|�
|��}|�||j���}|||fS)Nr)rvrr{)r�r^r�r�r�rrPr�r�r�r�r�r�r�r�ru)	rtr�r�r�rXrrr|r�rrrr��s(





�
zNumpyDocstring._consume_fieldr�cCs|jdd�S)NT)r�)r�)rtr�rrrr��rz'NumpyDocstring._consume_returns_sectioncCs"t|j�}t�|�st|j�|Sr+)r�r^r�r�rrrrr��s


z&NumpyDocstring._consume_section_headercCsN|j�d�\}}|j��p&|��p&ddg||gkp&|jo&|o&|�||j�S)Nr�rr�)rt�line1�line2rrrr~�s����z NumpyDocstring._is_section_breakcCsj|j�d�\}}|��}||jvrt|t�rtt�|��S|j	r3t
�|�r3|j	D]
}|�|�r2dSq(dS)Nr�TF)r^r}r�r2r[r\rT�_numpy_section_regexr�r1r�r�)rtr��	underliner�rrrr��s


�z!NumpyDocstring._is_section_headerr�cCs4|��}z|�|�WSty|�d|�YSwr-)r�� _parse_numpydoc_see_also_sectionrxr�)rtr�rurrrro�s�z&NumpyDocstring._parse_see_also_section�contentcsg�dtdtttff�fdd��dtdttddf��fdd	�}�fd
d��d}g}|D]x}|��s4q-�j�|�}|rq||��d����d�rq|||�|d|���||��d�}}|�dd
�d
��g}|dspg}q-|�d�s�|||�d}d|vr�|�d�D]}|��r�||g�q�q-|��r�|}q-|dur�|�	|���q-|||��s�gS�fdd��D��g}d}	�D]=\}
}}|r�d||
f}
nd|
}
|s�|	r�|dg7}||
g7}n
|dd|
7<|r�|��
d�|�g�7}d}	q�d}	q�|dg7}��d|�S)a
        Derived from the NumpyDoc implementation of _parse_see_also.

        See Also
        --------
        func_name : Descriptive text
            continued text
        another_func_name : Descriptive text
        func_name1, func_name2, :meth:`func_name`, func_name3

        �textrcsL�j�|�}|r |��}|ddur|ddfS|d|dfStd|��)zMatch ':role:`name`' or 'name'r{Nr�r�z%s is not a item name)r#r��groupsrx)r�r&�gryrr�parse_item_name�szHNumpyDocstring._parse_numpydoc_see_also_section.<locals>.parse_item_namer$�restNcs6|sdS�|�\}}��|t|�|f�|dd�=dSr+)r�rg)r$r��role)�itemsr�rr�	push_item�s
zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.push_itemcsn�jj}|dus
|s|||fS|�||�}�j�|�}|s"|||fS|��}|d}|dp1|d}|||fS)Nr�r$�name2)rPr�r�r#r��	groupdict)r��descriptionr�r�
translatedr�r��new_funcryrr�	translate�s


zBNumpyDocstring._parse_numpydoc_see_also_section.<locals>.translater�r{rr�r�csg|]\}}}�|||��qSrr)r�r�r�r�)r�rrr�"s
��zCNumpyDocstring._parse_numpydoc_see_also_section.<locals>.<listcomp>Tz:%s:`%s`r�rr�z, %sFr.)
r\rrr�r#r�r5r�r�r�r�rxr�)rtr�r��current_funcr�r�r&r�ru�
last_had_descr$r�r��linkr)r�r�rtr�rr��sl 
"�


����

�

z/NumpyDocstring._parse_numpydoc_see_also_sectionrJrKrL)r@rMr>rNr	r\rrRr
rrvr�r�rTrr�r�r�r~r�ror��
__classcell__rrr�rr�s>\�������
�
�	"r�r+)7rNrerSrO�	functoolsr�typingrrrrrrr	�sphinx.applicationr
�
sphinx.configrrR�sphinx.ext.napoleon.iteratorsr
�
sphinx.localerr�sphinx.utilr�sphinx.util.inspectr�sphinx.util.typingr�	getLoggerr@r�rPr�r�r�r�r2r1r$r�r�rtrmr�r\rrrirur��dictr�r�rrrr�<module>sb$





��
���"
+8 ;$