
    -PhOD                        d Z ddlZddlZddlZddlZddlZddlmZ ddlm	Z	 ddl
mZmZmZmZmZmZ ddlmZmZ ddlmZ dd	lmZ dd
lma ddlmZmZ ddlmZ  ej        e          Z dZ!d Z"d Z#d Z$d Z%d Z&dZ'd Z(d Z)d Z*t2          fdZ+d$dZ,ddl-m.Z. ddl/m0Z0 ddl1m2Z2  G d d          Z3 G d de3e2          Z4 G d  d!e3e0          Z5d" Z6d# Z7dS )%ak  
========
numpydoc
========

Sphinx extension that handles docstrings in the Numpy standard format. [1]

It will:

- Convert Parameters etc. sections to field lists.
- Convert See Also section to a See also entry.
- Renumber references.
- Extract the signature from the docstring, if it can't be determined
  otherwise.

.. [1] https://github.com/numpy/numpydoc

    N)Callable)deepcopy)Textcitationcommentinline	referencesection)desc_contentpending_xref)logging   )__version__)get_doc_object)get_validation_checksvalidate)DEFAULT_LINKS   c                 Z    t          | d          r | j        |fi |n | j        |fi |S )zTriage node.traverse (docutils <0.18.1) vs node.findall.

    TODO: This check can be removed when the minimum supported docutils version
    for numpydoc is docutils>=0.18.1
    findall)hasattrr   traverse)node	conditionkwargss      Q/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/numpydoc/numpydoc.py_traverse_or_findallr   *   sK     4##	0Y))&)))T]9////    c                    t                      }|D ]m}|                                }t          j        d| j        j        z  |t          j                  }|r(|                    |                    d                     n|rt          j
                    }	|	                    |                    d                     d|	                                d t                   z   }
|D ]o}|
dz   |z   }t          |          D ]S\  }}||                             d| dd| d          ||<   ||                             d| d	d| d	          ||<   Tnd S d S )
Nz^\.\. +\[(%s)\]r   utf8R-[z]_z.. [])setstriprematchconfignumpydoc_citation_re
IGNORECASEaddgrouphashlibsha256updateencode	hexdigestHASH_LEN	enumeratereplace)appwhatnameobjoptionslines
referenceslinemshaprefixrnew_ris                 r   rename_referencesrD   7   sy    J ' 'zz||H!@@$
 
  	'NN1771::&&& 
Jn

4;;v&&'''s}}yy11 	J 	JASL1$E$U++ J J4 8++IIII}5}}}EEa 8++K1KKKIIaJ
J 
J	J 	Jr   c           	         | j         }d } ||          s|j         }|dS  ||          t          j        t          ||ddd                    }|D ]k}|j        s
|j        d d d         D ]P}t          |t                    s|j                                        t                                          k    r  dS QldS )Nc                 :    t          | t          t          f          S N)
isinstancer
   r   )r   s    r   is_docstring_sectionz<_is_cite_in_numpydoc_docstring.<locals>.is_docstring_sectionV   s    $, 7888r   FT)include_selfdescendsiblings)
parent	itertoolschainr   childrenrH   r   	rawsourcer&   DEDUPLICATION_TAG)citation_nodesection_noderI   sibling_sectionssibling_sectionchilds         r   _is_cite_in_numpydoc_docstringrY   P   s    !'L9 9 9 #"<00 #*5 #"<00 
 ! 	
 	
 	
  , 	 	' 	$-ddd3 	 	EeW-- $$&&*;*A*A*C*CCCttt D		 5r   c                    t          |t                    D ]&}t          |          s|d         }|d                                                             d          \  }}}t          |          t          dz   k    sJ t          |          }|                    |d         |           |d         D ]}|j	        |         }	|	d         fd}
t          |	j
        |
          D ]/}|                    |d         t          d| d                     0|	                    |                                           (d S )Nr   r"   r   backrefsc                 r    t          | t                    o!| d                                         d dk    S )Nr   r#   r$   )rH   r   astext)r   ref_texts    r   matching_pending_xrefz1relabel_references.<locals>.matching_pending_xref   s8    t\22 <Q((OOOO;r   r#   r$   )r   r   rY   r]   	partitionlenr3   r   r5   idsrN   copy)r6   docrT   
label_noder@   _	new_labelnew_textid_refr_   	xref_noder^   s               @r   relabel_referencesrl   u   s_   -c8<< 3 3-m<< 	"1%
)!}3355??DD96{{hl****	??:a=(333 , 	3 	3C'#,C1vH     2#*>STT G G	!!)A,____0E0EFFFFKK(--//2222	33 3r   c                 n   t                      t          |t          d          D ]"}|d         D ]}                    |           #t          |t          d          D ]"}|d         D ]}                    |           #t          |t
          d          D ]}fd|d         D             |d<   d S )NT)rK   rb   c                     g | ]}|v |	S  ro   ).0ri   known_ref_idss     r   
<listcomp>z"clean_backrefs.<locals>.<listcomp>   s*     %
 %
 %
}8L8LC8L8L8Lr   r[   )r%   r   r	   r,   r   r   )r6   rd   docnamerj   ri   rT   rq   s         @r   clean_backrefsrt      s   EEM#CDAAA # #u: 	# 	#Cc""""	# $C>>> # #u: 	# 	#Cc""""	#-c8TJJJ 
 
%
 %
 %
 %
(4%
 %
 %
j!!
 
r   z    !! processed by numpydoc !!c           	           t           |v rd S  j        j        }t          |t                    r	 ||         }n# t
          $ r d}Y nw xY w j        j         j        j        | j        j         j        j	         j        j
         j        j         j        j        d}|                    |pi            d}|dk    rqd}	t          j        |	t          j        t          j        z            }
|
                    d|                    |                                        |          |d d <   nA	 t+          |||                    |          | j                  }t/          |                              |          |d d <   n*# t0          $ r t2                              d|            w xY w j        j        r j        j        }|r|                    |          nd	}|st=          |           fd
d         D             }d |D              j        j        z  rQd|d}|D ].}|d          j        j        v r|d|d          d|d          dz  }/t2                              |           tA           |||||           |dt           gz  }d S )NT)	use_plotsshow_class_membersshow_inherited_class_membersclass_members_toctreeattributes_as_param_listxref_param_typexref_aliasesxref_ignore
modulez(^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s* )r)   builderz,[numpydoc] While processing docstring for %rFc                     g | ]F}j         j                            |d                    xrt          j        d                   D|GS )r   	docstring)r)   numpydoc_validation_overridesgetr'   search)rp   errr6   	overridesreports     r   rr   z%mangle_docstrings.<locals>.<listcomp>   so        *-)Q)U)U #A* * I Ii1DEE  r   errorsc                     h | ]
}|d          S )r   ro   )rp   r   s     r   	<setcomp>z$mangle_docstrings.<locals>.<setcomp>   s    ---sCF---r   z>[numpydoc] Validation warnings while processing docstring for z:
r   z  z: r   z..)!rS   r)   %numpydoc_show_inherited_class_membersrH   dictKeyErrornumpydoc_use_plotsnumpydoc_show_class_membersnumpydoc_class_members_toctree!numpydoc_attributes_as_param_listnumpydoc_xref_param_typenumpydoc_xref_aliases_completenumpydoc_xref_ignorer0   r'   compiler+   DOTALLsubjoinsplitr   r   str	Exceptionloggererrornumpydoc_validation_checksnumpydoc_validation_excluderr   r   warningrD   )r6   r7   r8   r9   r:   r;   rx   cfgu_NLpatterntitle_rerd   excluderexclude_from_validationr   msgr   r   r   s   `                @@r   mangle_docstringsr      s	   E!!#&:#S .55 0	0+G+M(( 	0 	0 	0+/(((	0 Z2!jD(D!$!J$'J$P:>
Az6	 	C JJw}"Dx@:gr}ry'@AA<<DIIe$4$455;;DAAaaa	 T499U++C  C 3xx~~d++E!!!HH 	 	 	LLGNNN	 :0 	( z>H?G&Rhood&;&;&;U#* ( "#     %h/   .-f---
0UU (5)-5 5 5   & = =q6SZ%JJJ#<A#<#<#a&#<#<#<<CNN3''' c4sGU;;;	d%&&EEEs   : A	A	.AF 'F)c                    t          j        |          r-t          |d          rdt          j        |j                  v rdS t          |t                    st          |d          sd S t          |d          sd S t          |ddi          }|d	         pt          t          |d
d                     }|rt          j        dd|          }|dfS d S )N__init__zinitializes x; see )r   r   __argspec_is_invalid___doc__rw   F)r)   	Signature__text_signature__z^[^(]*r   )inspectisclassr   pydocgetdocr   rH   r   r   _clean_text_signaturegetattrr'   r   )r6   r7   r8   r9   r:   sigretannrd   s           r   mangle_signaturer      s    s C$$ EL$>$>>>vsH%% 6M)N)N t3	"" t
&:E%B
C
C
CC
k
 3)400 C  fXr3''Bw r   c                    | d S t          j        d          }|                    |                                           \  }}| ||         }| |d         } t          j        dd| d          } t          j        dd| d          } || z   d	z   S )
Nz^[^(]*\(rM   z^\$(self|module|type)(,\s|$)r   r   )countz(^|(?<=,\s))/,\s\**))r'   r   r   spanr   )r   start_patternstartend	start_sigs        r   r   r     s    
{tJ{++M%%c**//11JE3E#II
c"f+C
&0"c
C
C
CC
&&S
:
:
:Cs?S  r   c                    t          | d          sd S |a|                     d           |                     dt                     |                     dt
                     |                     dt                     |                     dt                     |                     dt                     | 	                    dd d	           | 	                    d
dd           | 	                    dddt          t          f           | 	                    ddd           | 	                    ddd           | 	                    ddd           | 	                    dd	d           | 	                    dt                      d           | 	                    dt                      d           | 	                    dt                      d           | 	                    dt                      d	           | 	                    dt                      d	           |                     t                     |                     t                     t           dd}|S )Nadd_config_valuezsphinx.ext.autosummaryzconfig-initedzautodoc-process-docstringzautodoc-process-signaturezdoctree-readzdoctree-resolvedr   Fr   Tr   )typesr   r*   z[a-z0-9_.-]+r   r   numpydoc_xref_aliasesr   r   numpydoc_validation_excluder   )versionparallel_read_safe)r   r   setup_extensionconnectupdate_configr   r   rl   rt   r   boolr   r%   
add_domainNumpyPythonDomainNumpyCDomainr   )r6   get_doc_object_metadatas      r   setupr     s,   3*++ t %N0111KK///KK+->???KK+-=>>>KK 2333KK"N333-tU;;;6dCCC/tD$<     94FFF/FFF<dDIII3UDAAA0$&&$???/===5suudCCC6uEEE8$&&%HHH NN$%%%NN<   &dCCHOr   c                 n   || j         }t          |j                  }t          j                    D ]\  }}||vr|||<   ||_        t          |j                  |_        t          |j	        t                    rt          d|j	        d          d|_        |j	        r=t          j        d                    d |j	        D                                 }||_        |j                                        D ]>\  }}t          j        d                    d |D                                 |j        |<   ?dS )z-Update the configuration with default values.NzBnumpydoc_validation_exclude must be a container of strings, e.g. [z].|c              3      K   | ]}|V  d S rG   ro   rp   exps     r   	<genexpr>z update_config.<locals>.<genexpr>U  s"      HHccHHHHHHr   c              3      K   | ]}|V  d S rG   ro   r   s     r   r   z update_config.<locals>.<genexpr>[  s"      ..cc......r   )r)   r   r   r   itemsr   r   r   rH   r   r   
ValueErrorr   r'   r   r   r   )r6   r)   r   keyvalueexclude_exprcheckpatternss           r   r   r   8  sq   ~
 &.f.J%K%K"#)++ 8 8
U44427*3/,JF) )>)) )F%
 &4c:: 
>7> > >
 
 	
 +/F') ;zIIHHV%GHHHHH
 
 /;+!?EEGG 
 
x68jII..X.....7
 7
,U33
 
r   )ViewList)CDomain)PythonDomainc                   (     e Zd Zi Z fdZd Z xZS )ManglingDomainBasec                 b     t                      j        |i | |                                  d S rG   )superr   wrap_mangling_directives)selfakw	__class__s      r   r   zManglingDomainBase.__init__k  s7    !"r"""%%'''''r   c                     t          | j                                                  D ](\  }}t          | j        |         |          | j        |<   )d S rG   )listdirective_mangling_mapr   wrap_mangling_directive
directives)r   r8   objtypes      r   r   z+ManglingDomainBase.wrap_mangling_directiveso  s[    !$"="C"C"E"EFF 	 	MD'$;%w% %DOD!!	 	r   )__name__
__module____qualname__r   r   r   __classcell__)r   s   @r   r   r   h  sM        ( ( ( ( (      r   r   c                   *    e Zd ZdZddddddddZg ZdS )r   npfunctionclass	attribute)r   r   	exceptionmethodclassmethodstaticmethodr   N)r   r   r   r8   r   indicesro   r   r   r   r   v  s<        D!"   GGGr   r   c                   "    e Zd ZdZddddddZdS )r   znp-cr   r   r   object)r   membermacrotypevarN)r   r   r   r8   r   ro   r   r   r   r     s1        D r   r   c                    g }|j         }|j        }d}t          |           D ]\  }}|t          |          dz
  k     rO||                                         s5|dz  }|t          |          dz
  k     r||                                         5|                    ||                    |                                r|t          |          dz
  k     r|dz  }t          |          t          |           k    sJ |S )a  Create items for mangled lines.

    This function tries to match the lines in ``lines`` with the items (source
    file references and line numbers) in ``content_old``. The
    ``mangle_docstrings`` function changes the actual docstrings, but doesn't
    keep track of where each line came from. The mangling does many operations
    on the original lines, which are hard to track afterwards.

    Many of the line changes come from deleting or inserting blank lines. This
    function tries to match lines by ignoring blank lines. All other changes
    (such as inserting figures or changes in the references) are completely
    ignored, so the generated line numbers will be off if ``mangle_docstrings``
    does anything non-trivial.

    This is a best-effort function and the real fix would be to make
    ``mangle_docstrings`` actually keep track of the ``items`` together with
    the ``lines``.

    Examples
    --------
    >>> lines = ["", "A", "", "B", "   ", "", "C", "D"]
    >>> lines_old = ["a", "", "", "b", "", "c"]
    >>> items_old = [
    ...     ("file1.py", 0),
    ...     ("file1.py", 1),
    ...     ("file1.py", 2),
    ...     ("file2.py", 0),
    ...     ("file2.py", 1),
    ...     ("file2.py", 2),
    ... ]
    >>> content_old = ViewList(lines_old, items=items_old)
    >>> match_items(lines, content_old)  # doctest: +NORMALIZE_WHITESPACE
    [('file1.py', 0), ('file1.py', 0), ('file2.py', 0), ('file2.py', 0),
     ('file2.py', 2), ('file2.py', 2), ('file2.py', 2), ('file2.py', 2)]
    >>> # first 2 ``lines`` are matched to 'a', second 2 to 'b', rest to 'c'
    >>> # actual content is completely ignored.

    Notes
    -----
    The algorithm tries to match any line in ``lines`` with one in
    ``lines_old``.  It skips over all empty lines in ``lines_old`` and assigns
    this line number to all lines in ``lines``, unless a non-empty line is
    found in ``lines`` in which case it goes to the next line in ``lines_old``.

    r   r   )datar   r4   ra   r&   append)r;   content_old	items_new	lines_old	items_oldjrC   r=   s           r   match_itemsr    s   \ I I!I	AU##  4 #i..1$$$Yq\-?-?-A-A$FA #i..1$$$Yq\-?-?-A-A$1&&&::<< 	AI 222FAy>>SZZ''''r   c                 ,      G  fdd           }|S )Nc                       e Zd Z fdZdS )*wrap_mangling_directive.<locals>.directivec                    | j         j        j        j        }d }| j        rGt          j        d| j        d                   }|                    d                                          }|s| j        d         }t          | j
                  }t          |j        |d d |           | j
        r6t          || j
                  }t          ||| j
        j                  | _
                            |           S )Nz^(.*\s+)?(.*?)(\(.*)?r      )r   rN   )statedocumentsettingsenv	argumentsr'   r(   r-   r&   r   contentr   r6   r  r   rN   run)r   r  r8   r>   r;   r   base_directiver   s         r   r  z.wrap_mangling_directive.<locals>.directive.run  s    *%.2CD~ *H5t~a7HIIwwqzz'')) )~a(&&EcgwdD%HHH| X#E4<88'U4<CVWWW!%%d+++r   N)r   r   r   r  )r  r   s   r   	directiver    s3        	, 	, 	, 	, 	, 	, 	, 	,r   r  ro   )r  r   r  s   `` r   r   r     sE    , , , , , , , ,N , , ,( r   rG   )8r   r.   r   rO   r   r'   collections.abcr   rc   r   docutils.nodesr   r   r   r   r	   r
   sphinx.addnodesr   r   sphinx.utilr   r   r   docscrape_sphinxr   r   r   xrefr   	getLoggerr   r   r3   r   rD   rY   rl   rt   rS   r   r   r   r   r   docutils.statemachiner   sphinx.domains.cr   sphinx.domains.pythonr   r   r   r   r  r   ro   r   r   <module>r)     s   &        				 $ $ $ $ $ $       N N N N N N N N N N N N N N N N 6 6 6 6 6 6 6 6             , , , , , , 5 5 5 5 5 5 5 5      		8	$	$
 
 
J J J2" " "J3 3 36
 
 
" 6 K' K' K'\  ,	! 	! 	!  . ! ! ! !H$
 $
 $
 $
V + * * * * * $ $ $ $ $ $ . . . . . .           *L       %w   ; ; ;|    r   