o
    Ni}                     @  sR  d Z ddlmZ ddlZddl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 ddlmZmZmZmZ ddlmZ dd	lmZ dd
lmZmZmZ ddlmZ ddlZddlmZ ddlm Z  ddl!m"Z" ddl#m$Z$ ddl%m&Z&m'Z'm(Z( ddl)m*Z* ddl+m,Z, ddl-m.Z. ddl/m0Z0 ddl1m2Z2 ddl3m4Z4 ddl5m6Z6 ddl7m8Z8m9Z9 ddl:m;Z;m<Z<m=Z=m>Z>m?Z? ddl@mAZAmBZB ddlCmDZD ddlEmFZF erddlGmHZH ddlImJZJmKZK ddlLmMZM dd lNmOZO dd!lPmQZQmRZR dd"lSmTZT e8UeVZWeXd#ZYeXd$ZZd%Z[G d&d' d'ej\Z]d|d-d.Z^d}d0d1Z_G d2d3 d3ej\Z`d~d5d6ZaG d7d8 d8ZbG d9d: d:e*ZcddAdBZdG dCdD dDe<ZeddGdHZfddIdJZgdddOdPZhddTdUZi	K	VdddZd[ZjG d\d] d]ekZlddadbZm	cdddhdiZndddndoZo	c	jdddpdqZpG drds dse=ZqddudvZrddwdxZsddzd{ZtdS )a_  Extension that adds an autosummary:: directive.

The directive can be used to generate function/method/attribute/etc. summary
lists, similar to those output eg. by Epydoc and other API doc generation tools.

An :autolink: role is also provided.

autosummary directive
---------------------

The autosummary directive has the form::

    .. autosummary::
       :nosignatures:
       :toctree: generated/

       module.function_1
       module.function_2
       ...

and it generates an output table (containing signatures, optionally)

    ========================  =============================================
    module.function_1(args)   Summary line from the docstring of function_1
    module.function_2(args)   Summary line from the docstring
    ...
    ========================  =============================================

If the :toctree: option is specified, files matching the function names
are inserted to the toctree with the given prefix:

    generated/module.function_1
    generated/module.function_2
    ...

Note: The file names contain the module:: or currentmodule:: prefixes.

.. seealso:: autosummary_generate.py


autolink role
-------------

The autolink role functions as ``:obj:`` when the name referred can be
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
    )annotationsN)	Parameter)path)
ModuleType)TYPE_CHECKINGAnyClassVarcast)nodes)
directives)RSTStateMachineStructstate_classes)
StringList)addnodes)Config)BuildEnvironment)PycodeError)INSTANCEATTR
DocumenterOptions)DocumenterBridge)import_module)mock)__)Project)ModuleAnalyzer)SphinxComponentRegistry)loggingrst)NullReporterSphinxDirective
SphinxRolenew_documentswitch_source_input)getmrosignature_from_str)Matcher)nested_parse_to_nodes)Sequence)Nodesystem_message)Sphinx)	Extension)ExtensionMetadata
OptionSpec)HTML5Translatorz	\.(?:\s+)z::\s*$)zet al.ze.g.zi.e.c                   @     e Zd ZdS )autosummary_tocN__name__
__module____qualname__ r7   r7   S/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/ext/autosummary/__init__.pyr2   r       r2   selfnodes.NodeVisitornodereturnNonec                 C  s   t j)z-Hide autosummary toctree list in HTML output.)r
   SkipNoder:   r<   r7   r7   r8   autosummary_toc_visit_htmlv   s   rA   r*   c                 C  s   d S Nr7   r@   r7   r7   r8   autosummary_noop{   s   rC   c                   @  r1   )autosummary_tableNr3   r7   r7   r7   r8   rD      r9   rD   r0   c                 C  s   zXt tj|d }t tj|d }t tj|d }t ttj |}|D ]2}t tj|d }t tj|d }t	t|D ]\}	}
t
|
tjrT|
 dd}t|||	< q;q#W dS  tyb   Y dS w )z0Make the first column of the table non-breaking.r        N)r	   r
   tabletgrouptbodylistrowentry	paragraph	enumerate
isinstanceTextastextreplace
IndexError)r:   r<   rH   rI   rJ   rowsrL   
col1_entryparjsubnodenew_textr7   r7   r8   autosummary_table_visit_html   s$   r[   c                   @     e Zd ZdZdddZdS )FakeApplicationr   r=   r>   c                 C  s8   d | _ d | _i | _d | _t | _tdi | _t | _	d S )N )

doctreedirevents
extensionssrcdirr   configr   projectr   registry)r:   r7   r7   r8   __init__   s   zFakeApplication.__init__Nr=   r>   )r4   r5   r6   	verbosityrf   r7   r7   r7   r8   r]      s    r]   c                      s   e Zd Zd fddZ  ZS )FakeDirectiver=   r>   c                   sX   t dd}t |d}t }|jdddd t|}t |d}t |d t d	| d S )
N   )	tab_width)settingsautodoc_class_signaturemixedenvr7   )documentr   )r   r]   rc   addr   superrf   r   )r:   rl   rp   appro   state	__class__r7   r8   rf      s   


zFakeDirective.__init__rg   )r4   r5   r6   rf   __classcell__r7   r7   ru   r8   ri      s    ri   rs   r,   objr   parenttype[Documenter]c                   s   ddl m}m} t r|S |durt| |d}n|}t|dr)|t |jn|t d fdd| j	j
 D }|rK|jdd	 d
 |d S |S )zGet an autodoc.Documenter class suitable for documenting the given
    object.

    *obj* is the Python object to be documented, and *parent* is an
    another Python object (e.g. a module or a class) to which *obj*
    belongs to.
    r   )DataDocumenterModuleDocumenterNr4   r^   c                   s    g | ]}|  d dr|qS )r^   F)can_document_member).0clsrx   
parent_docr7   r8   
<listcomp>   s    
z"get_documenter.<locals>.<listcomp>c                 S     | j S rB   )priority)r   r7   r7   r8   <lambda>       z get_documenter.<locals>.<lambda>)keyrE   )sphinx.ext.autodocr{   r|   inspectismoduleget_documenterhasattrri   r4   re   documentersvaluessort)rs   rx   ry   r{   r|   parent_doc_clsclassesr7   r   r8   r      s   

r   c                   @  sv   e Zd ZU dZdZdZdZdZej	ej
ejejej
dZded< d%d
dZd&ddZd'ddZd(dd Zd)d"d#Zd$S )*Autosummaryz
    Pretty table containing short signatures and summaries of functions etc.

    autosummary can also optionally generate a hidden toctree:: node.
    r   FT)captiontoctreenosignatures	recursivetemplatezClassVar[OptionSpec]option_specr=   
list[Node]c                 C  s  t | j| jjjt | j| j| _dd | jD }| 	|}| 
|}d| jv rt| jj}| jd  }g }t| jj}| jj}|D ]E\}	}
}}|||}t||}tt||}|| jjvr|t| j|drttd}ntd}tj|||  d qC|| qC|rt  }||d< d	d |D |d
< d|d< d |d< | jd|d< |t!dd| d| jvrd| jv rtjtd|d d |S )Nc                 S  s8   g | ]}|  rtd |  d r|   d qS )z^[~a-zA-Z_]r   )stripresearchsplitr~   xr7   r7   r8   r      s
    z#Autosummary.run.<locals>.<listcomp>r   Fz5autosummary references excluded document %r. Ignored.zMautosummary: stub file not found %r. Check your autosummary_generate setting.locationincludefilesc                 S  s   g | ]}d |fqS rB   r7   )r~   docnr7   r7   r8   r         entriesrE   maxdepthglobr   r^   z;A captioned autosummary requires :toctree: option. ignored.)"r   ro   rt   rp   reporterr   linenobridgecontent	get_items	get_tableoptions	posixpathdirnamedocnamer   r'   rc   exclude_patternsautosummary_filename_mapgetjoinnormpath
found_docsstrdoc2pathr   loggerwarningget_locationappendr   r   r2   )r:   namesitemsr
   r   tree_prefixdocnamesexcludedfilename_map_name_sig_summary	real_namer   msgtocnoder7   r7   r8   run   sH   




zAutosummary.runnamer   prefixeslist[str | None]tuple[str, Any, Any, str]c                 C  s   t | jjW zt||W W  d    S  ty\ } z<zt||W W  Y d }~W  d    S  tyW } z|jrCg |j|j}ng |j|}t|j	d |d d }~ww d }~ww 1 s`w   Y  d S )Nr   )
r   rc   autosummary_mock_importsimport_by_nameImportExceptionGroupimport_ivar_by_nameImportError	__cause__
exceptionsargs)r:   r   r   excexc2errorsr7   r7   r8   r     s$   
zAutosummary.import_by_namers   r,   rx   r   ry   	full_namer   c                 C  s   t |||}|| j|S )zGet an autodoc.Documenter class suitable for documenting the given
        object.

        Wraps get_documenter and is meant as a hook for extensions.
        )r   r   )r:   rs   rx   ry   r   docclsr7   r7   r8   create_documenter+  s   zAutosummary.create_documenterr   	list[str]list[tuple[str, str, str, str]]c                 C  sV  t | j}g }d}|D ]}|}|dr"|dd }|dd }z| j||d\}}}	}
W n, ty[ } z tdd	 |jD }tj	t
d
|d||  d W Y d}~qd}~ww t | j_|}t|tsv|
d |t|
d d  }| | jj||	|}| stj	t
d||  d ||dd|f q| stj	t
d||  d ||dd|f qzt| |_|j  W n ty } ztd| d|_W Y d}~nd}~ww z|jdd}W n t y   | }Y nw |sd}nt!d|t| }t"||d}d|_#|$d t%| jjj&dd | j'j(}|||||f q|S )z}Try to import the given names, and return a list of
        ``[(name, signature, summary_string, real_name), ...]``.
        2   ~   N.rE   )r   c                 S  s"   h | ]}d t |j d| qS )z* z: )typer4   r~   er7   r7   r8   	<setcomp>H  s   " z(Autosummary.get_items.<locals>.<setcomp>z4autosummary: failed to import %s.
Possible hints:
%s
r   z::zfailed to parse name %sr^   zfailed to import object %sz$[autodoc] module analyzer failed: %sF)show_annotation
   	max_chars))get_import_prefixes_from_envro   
startswithr   r   r   rK   r   r   r   r   r   r   r   r   resultrP   r   lenr   rs   
parse_namer   import_objectr   
for_moduleget_real_modnameanalyzerfind_attr_docsr   debugformat_signature	TypeErrormaxmangle_signature_extra_indentadd_contentextract_summarydatart   rp   )r:   r   r   r   max_item_charsr   display_namer   rx   ry   modnamer   r   r   
documentererrsigr   summaryr7   r7   r8   r   5  sv   






zAutosummary.get_itemsr   c                   s  t  }d|d< td}tjddgd}|| tjddd}|| |tjddd	 |tjdd
d	 td |  d fdd}|D ]2\}}}	}
d}dj	vrld| d| d|
 dt
| }nd| d| d|
 d}|	}||| qM||gS )zGenerate a proper list of table nodes for autosummary:: directive.

        *items* is a list produced by :meth:`get_items`.
        z\X{1}{2}\X{1}{2}specr^   zautosummary longtabler      )colsr   )colwidthZ   column_textsr   r=   r>   c               	     s   t d}j \}}| D ]I}t|g| d| d}tj|- tj|dd}|r:t|d t j	r:|d }nt 	d}|
t d| W d    n1 sRw   Y  q 
| d S )Nr^   :z:<autosummary>F)allow_section_headingsr   )r
   rL   state_machineget_source_and_liner   r$   rt   r(   rP   rN   r   rM   )r  rL   sourcelinetextvl	col_nodesr<   bodyr:   r7   r8   
append_row  s   


z)Autosummary.get_table.<locals>.append_rowrx   r   z:py:z:`z <z>`\ z>`N)r  r   r=   r>   )r   tabular_col_specrD   r
   rH   r   rI   colspecrJ   r   r   escape)r:   r   
table_specrH   
real_tablegroupr  r   r  r  r   	qualifiercol1col2r7   r  r8   r     s(   




$zAutosummary.get_tableN)r=   r   )r   r   r   r   r=   r   )
rs   r,   rx   r   ry   r   r   r   r=   r   )r   r   r=   r   )r   r   r=   r   )r4   r5   r6   __doc__required_argumentsoptional_argumentsfinal_argument_whitespacehas_contentr   unchanged_required	unchangedflagr   __annotations__r   r   r   r   r   r7   r7   r7   r8   r      s"   
 

0


Rr   sr   c                 C  s   |  dd  S )z+Strip a type hint from argument definition.r  r   )r   r   )r+  r7   r7   r8   strip_arg_typehint  s   r,  c                 C  s   z>t | }t|j }t|D ]!\}}|jtjur!|jtjd}|j	tjur-|jdd}|||< q|j|tjd}t
|W S  tyI   |  Y S w )zCClean up signature using inspect.signautre() for mangle_signature())
annotationN)default)
parametersreturn_annotation)r&   rK   r/  r   rO   r-  r   emptyrS   r.  r   	Exception)r+  r  r/  iparamr7   r7   r8   _cleanup_signature  s   

r5     r  r   intc           
      C  s  t | }tdd|}tdd| }tdd|}tdd|}tdd|}td	d|}td
d|}td|rJtdd|}td|s=td|r]tdd|}td|sPtd|rptdd|}td|scg }g }td}|r||}|s|d}n|d|d |ddd }|s{t	|D ]
\}}t
|||< qt	|D ]
\}}	t
|	||< qtd||d d} |r| sdtd||d d } d|  S t| |d d d k r| dtd||t|  d d d 7 } d|  S )z5Reformat a function signature to a more compact form.z\)\s*->\s.*$)z
^\((.*)\)$z\1z\\\\r^   z\\'z\\"z'[^']*'z"[^"]*"z	\([^)]*\)z<[^>]*>z{[^}]*}z^(.*, |)([a-zA-Z0-9_*]+)\s*=\s*z, r   r  r   Nr   z[%s]      z[, %s]z(%s))r5  r   subr   r   compiler   insertr  rO   r,  limited_joinr   )
r  r   r+  r   optsopt_remr3  argoptr7   r7   r8   r     sT   




r   docr   rp   c                 C  s^  ddd}| r| d	   s| d	 | r| d	   rt| D ]\}}|  s.| d
| }  nq| g kr5dS || |j}t|d	 tjrL|d	    }n[t|d	 tjs[| d	   }nLt	
d| }t|dkrp|d	   }n7d}tt|D ].}d|d
|d  dd }g |d
d
< || |j}|trqxt|tjs nqxtd|}|S )zExtract summary from docstring.rE  r   rl   r   r=   nodes.documentc                 S  s,   t td}td|}t |_|| | |S )NBodyr^   )r   r   r#   r    r   r   )rE  rl   r  r<   r7   r7   r8   parse
  s
   

zextract_summary.<locals>.parser   Nr^   rF   r   z. r   )rE  r   rl   r   r=   rF  )r   poprO   rl   rP   r
   sectionrR   rN   
periods_rer   r   r   rangerstripendswithWELL_KNOWN_ABBREVIATIONSanyfindallr+   
literal_rer<  )rE  rp   rH  r3  piecer<   r  	sentencesr7   r7   r8   r     s>   
	
 
r   ...sepr   overflow_markerc                 C  sx   |  |}t||k r|S d}d}|D ]}|t|t|  7 }||t| k r,|d7 }q |  g t|d| |S )zJoin a number of strings into one, limiting the length to *max_chars*.

    If the string overflows this limit, replace the last fitting item by
    *overflow_marker*.

    Returns: joined_string
    r   r   N)r   r   rK   )rV  r   r   rW  full_strn_charsn_itemsitemr7   r7   r8   r?  @  s   
	
r?  c                      s"   e Zd ZdZd
 fdd	Z  ZS )r   zExceptions raised during importing the target objects.

    It contains an error messages and a list of exceptions as its arguments.
    message
str | Noner   Sequence[BaseException]r=   r>   c                   s   t  | t|| _d S rB   )rr   rf   rK   r   )r:   r\  r   ru   r7   r8   rf   b  s   zImportExceptionGroup.__init__)r\  r]  r   r^  r=   r>   )r4   r5   r6   r"  rf   rw   r7   r7   ru   r8   r   \  s    r   ro   r   r   c                 C  s^   dg}| j d}|r|d| | j d}|r-|r'|d|d |  |S |d| |S )z`
    Obtain current Python import prefixes (for `import_by_name`)
    from ``document.env``
    Nz	py:moduler   zpy:classr   )ref_contextr   r>  )ro   r   
currmodule	currclassr7   r7   r8   r   g  s   r   rB   r   r   Sequence[str | None]r   c                 C  s  g }g }|D ]j}|dur)|  | dr)td}tj|| | | dddd qz|r4| d|  }n| }t|dd\}}}	||||	fW   S  tyU   || Y q typ }
 z|| ||
 W Y d}
~
qd}
~
ww t	
tjd	d
 |D g }tdd| |)z~Import a Python object that has the given *name*, under one of the
    *prefixes*.  The first name that succeeds is used.
    Nr   zKSummarised items should not include the current module. Replace %r with %r.autosummaryimport_cycle)r   subtypeT)grouped_exceptionc                 s  s    | ]}|j V  qd S rB   )r   r   r7   r7   r8   	<genexpr>  s    z!import_by_name.<locals>.<genexpr>zno module named %sz or )r   r   r   r   removeprefix_import_by_namer   r   r   	functoolsreduceoperatoriaddr   )r   r   triedr   prefixr   prefixed_namerx   ry   r  r   r   r7   r7   r8   r   |  s4   
r   Trf  booltuple[Any, Any, str]c                 C  s  g }z|  d}d|dd }|rAzt|}t||d ||fW W S  tttfy@ } z||jp4| W Y d}~nd}~ww d}d}t	t
dt|d D ]5}|}d|d| }zt| W n ty} } z||jpq| W Y d}~nd}~ww |tjv r nqP|t|k rd}	tj| }
||d D ]	}|
}	t|
|}
q|
|	|fW S tj| d|fW S  ttttfy } z|| |rtd|dt|j |d}~ww )z+Import a Python object given its full name.r   NrE   r   r^   r   )r   r   r   getattrr   rT   AttributeErrorr   r   reversedrL  r   sysmodules
ValueErrorKeyErrorr   r   )r   rf  r   
name_partsr  modr   last_jrX   ry   rx   obj_namer7   r7   r8   ri    sR   



ri  c              
   C  s   z[|  dd\} }t| |\}}}}t|}t|dkr|f}|D ]7}	tt|	d|}
|
  t }|dd |
j	D O }|dd |
j
D O }||v rX|d | t||f  W S q!W t tttfym } zt|d}~w tyt    w )	zImport an instance variable that has the given *name*, under one of the
    *prefixes*.  The first name that succeeds is used.
    r   r   r   r5   c                 S     h | ]\}}|qS r7   r7   r~   qualnameattrr7   r7   r8   r     r   z&import_ivar_by_name.<locals>.<setcomp>c                 S  r~  r7   r7   r  r7   r7   r8   r     r   N)rsplitr   r%   r   r   r   rs  analyzeset	attr_docsr   r   r   rx  r   r   )r   r   rf  r  r   rx   ry   r  candidate_objectscandidate_objr   found_attrsr   r7   r7   r8   r     s.   r   c                   @  r\   )AutoLinkzSmart linking role.

    Expands to ':obj:`text`' if `text` is an object that can be imported;
    otherwise expands to '*text*'.
    r=   'tuple[list[Node], list[system_message]]c                   s   | j jjd}|d usJ |d| j| j| j| j| j| j	\}}|r&||fS t
|dks.J ttj|d }zt| j }|d   fdd|D }t | W ||fS  tyu   ttj|d }tj| j| |d d|d< Y ||fS w )	Nrx   r   r   	reftargetc                   s0   g | ]}|d u s  | ds |ks|qS )Nr   )r   )r~   ro  r   r7   r8   r     s    z AutoLink.run.<locals>.<listcomp>r   r  )ro   domainspython_domainrolerawtextr  r   inlinerr   r   r   r	   r   pending_xrefr   r   r   r
   literalemphasisrR   )r:   
pyobj_roleobjectsr   r  r   r  r7   r  r8   r     s0   

zAutoLink.runN)r=   r  )r4   r5   r6   r"  r   r7   r7   r7   r8   r    s    r  r]  c                   s8   d fdd}d } j jD ]}d||v r|  S qd S )	Nsuffixr   r=   tuple[str, ...]c                   s(    j  | d}|d u rdS |jS )Nr   )restructuredtext)re   get_source_parsersr   rh  	supported)r  parser_classrs   r7   r8   get_supported_format  s   z,get_rst_suffix.<locals>.get_supported_formatr  )r  r   r=   r  )rc   source_suffix)rs   r  r  r7   r  r8   get_rst_suffix  s   r  c              
     s&  | j j}|du r| jj  fdd jD }n4|du rn/t| j jfdd|D }|d d  D ]}tt	| j
|sJttd| || q1|sOd S t| }|d u r`ttd d S dd	lm} | j j}t| j j |||| j
| || j j| j jd
 W d    d S 1 sw   Y  d S )NTc                   s0   g | ]}t j |rt j|d dqS )F)base)osr   isfiler   r   r   )ro   r7   r8   r   '  s    z,process_generate_options.<locals>.<listcomp>Fc                   s*   g | ]}|| t s d  nd qS )r   r^   )rN  tuple)r~   genfile)extr7   r8   r   -  s    "z(autosummary_generate: file not found: %szcautosummary generates .rst files internally. But your source_suffix does not contain .rst. Skipped.r   )generate_autosummary_docs)r  	base_pathrs   imported_members	overwriteencoding)rc   autosummary_generatebuilderro   r   rK   r  r   r  r   rb   r   r   r   remover  sphinx.ext.autosummary.generater  autosummary_imported_membersr   r   autosummary_generate_overwritesource_encoding)rs   genfilesrM   r  r  r  r7   )ro   r  r8   process_generate_options"  s<   


"r  r.   c                 C  s   |  d | jtttfttfttfttfttfd | jtttfttfttfttfttfd | dt | 	dt
  | dt | di d | di d	 | d
ddtth | ddd | ddd d | dg dt | dddt tjddS )Nzsphinx.ext.autodoc)htmllatexr  mantexinforc  autolinkzbuilder-initedautosummary_contextro   r   r  r  Tr  r^   r   c                 S  r   rB   )autodoc_mock_imports)rc   r7   r7   r8   r   _  r   zsetup.<locals>.<lambda>r  autosummary_ignore_module_all)versionparallel_read_safe)setup_extensionadd_noder2   rA   rC   rD   r[   add_directiver   add_roler  connectr  add_config_valuerq  rK   sphinx__display_version__r  r7   r7   r8   setupH  s8   
r  )r:   r;   r<   r2   r=   r>   )r:   r;   r<   r*   r=   r>   )r:   r0   r<   rD   r=   r>   )rs   r,   rx   r   ry   r   r=   rz   )r+  r   r=   r   )r6  )r  r   r   r7  r=   r   )rE  r   rp   r   r=   r   )r6  rU  )
rV  r   r   r   r   r7  rW  r   r=   r   )ro   r   r=   r   )rB   )r   r   r   rb  r=   r   )T)r   r   rf  rq  r=   rr  )rB   T)r   r   r   rb  rf  rq  r=   r   )rs   r,   r=   r]  )rs   r,   r=   r>   )rs   r,   r=   r.   )ur"  
__future__r   rj  r   rl  r  r   r   rv  r   r   typesr   typingr   r   r   r	   docutilsr
   docutils.parsers.rstr   docutils.parsers.rst.statesr   r   r   docutils.statemachiner   r  r   sphinx.configr   sphinx.environmentr   sphinx.errorsr   r   r   r   r   sphinx.ext.autodoc.directiver   sphinx.ext.autodoc.importerr   sphinx.ext.autodoc.mockr   sphinx.localer   sphinx.projectr   sphinx.pycoder   sphinx.registryr   sphinx.utilr   r   sphinx.util.docutilsr    r!   r"   r#   r$   sphinx.util.inspectr%   r&   sphinx.util.matchingr'   sphinx.util.parsingr(   collections.abcr)   docutils.nodesr*   r+   sphinx.applicationr,   sphinx.extensionr-   sphinx.util.typingr.   r/   sphinx.writers.html5r0   	getLoggerr4   r   r=  rK  rR  rO  commentr2   rA   rC   rD   r[   r]   ri   r   r   r,  r5  r   r   r?  r2  r   r   r   ri  r   r  r  r  r  r7   r7   r7   r8   <module>   s    0






% 
_

;8
"/"
$
&