
    Ri `                       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	m
Z
 ddlmZ ddlmZ ddlmZ ddl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  ddl!m"Z" er(ddl#m$Z$m%Z% ddlm&Z&m'Z' ddl(m)Z)m*Z*m+Z+ ddl,m-Z- ddl.m/Z/m0Z0  ejb                  e2      Z3 ejh                  dejj                        Z6 ejh                  dejj                        Z7d/dZ8 G d de       Z9 G d de9      Z: G d de9      Z; G d de9      Z< G d  d!e9      Z= G d" d#e9      Z> ej~                         Z@ G d$ d%      ZA G d& d'      ZB G d( d)ej                        ZD G d* d+e      ZEd0d,ZFd1d-ZGd1d.ZHy)2zfMimic doctest in Sphinx.

The extension automatically execute code snippets and checks their results.
    )annotationsN)StringIO)TYPE_CHECKING)nodes)
directives)InvalidSpecifierSpecifierSet)Version)bold)Builder)__)logging)SphinxDirective)relpath)CallableSet)AnyClassVar)ElementNodeTextElement)Sphinx)ExtensionMetadata
OptionSpecz^\s*<BLANKLINE>z[ \t]*#\s*doctest:.+$c                .    t        |      t        |       v S )aY  Check `spec` satisfies `version` or not.

    This obeys PEP-440 specifiers:
    https://peps.python.org/pep-0440/#version-specifiers

    Some examples:

        >>> is_allowed_version('<=3.5', '3.3')
        True
        >>> is_allowed_version('<=3.2', '3.3')
        False
        >>> is_allowed_version('>3.2, <4.0', '3.3')
        True
    )r
   r	   )specversions     J/home/agent/.friday_env/lib/python3.12/site-packages/sphinx/ext/doctest.pyis_allowed_versionr   -   s     7|D111    c                  (    e Zd ZdZdZdZdZdZddZy)TestDirectivez*Base class for doctest-related directives.Tr      c                   dj                  | j                        }d }| j                  dk(  rYd|v r|}t        j	                  d|      }t
        j                  |      r(d| j                  vr|s|}t
        j	                  d|      }t        j                  }| j                  dv sd| j                  v rt        j                  }| j                  r:| j                  d   j                  d	      D cg c]  }|j                          }}nd
g} |||| j                  |      }| j                  |       |||d<   | j                  dk(  rd|d<   n)| j                  dk(  rd|d<   n| j                  dk(  rd|d<   i |d<   | j                  dv rd| j                  v r| j                  d   j                  d	d      j                         }|D ]  }|d   |dd  }
}	|	dvrH| j                   j"                  j$                  j'                  t)        d      |z  | j*                         Y|
t,        j.                  vrH| j                   j"                  j$                  j'                  t)        d      |
z  | j*                         t,        j.                  |dd     }|d   dk(  |d   |<    | j                  dk(  rud| j                  v rg	 | j                  d   }dj                  t1        t2        t4        j6                  d d             }t9        ||      st,        j.                  d   }d |d   |<   d"| j                  v r| j                  d"   |d"<   d#| j                  v rd |d$<   |gS d| j                  v rd%|d$<   |gS c c}w # t:        $ rJ | j                   j"                  j$                  j'                  t)        d!      z  | j*                         Y w xY w)&N
doctestz<BLANKLINE> no-trim-doctest-flags>   	testsetuptestcleanuphider   ,default)testnodetypegroupstestpyconlanguagetestcodepython
testoutputnoneoptions>   r&   r5    r#   z+-z"missing '+' or '-' in '%s' option.)linez'%s' is not a valid option.+	pyversion.   SKIPTz$'%s' is not a valid pyversion optionskipiftrim-doctest-flags
trim_flagsF)joincontentnameblankline_resubdoctestopt_researchr7   r   literal_blockcomment	argumentssplitstripset_source_inforeplacestatedocumentreporterwarningr   linenor&   OPTIONFLAGS_BY_NAMEmapstrsysversion_infor   r   )selfcoder0   nodetypexr/   nodeoption_stringsoptionprefixoption_nameflagr   python_versions                 r   runzTestDirective.runJ   s    yy&99	!$#''D1$$T*+4<<?D$((T2&+&9&99944$,,8N}}H>>)-):)@)@)EFAaggiFFF[Fd6JT"DL99	!&DYY*$'DYY,&%DY9911i4<<6O!\\)4<<S#FLLNN( 9&,Qi%JJ''0088?@6I![[ 9  g&A&AAJJ''008889KG![[ 9  226!":>(.q	S(8Y%9  99	!kT\\&A	||K0!$#c33C3CBQ3G*H!I)$?"66v>D,0DOD)
 t||#!\\(3DN4<</!%D v %4!&Dvi GT $ 

##,,44=>EDKK 5 s   .M2 A&M7 7AO
	O
N)returnz
list[Node])	__name__
__module____qualname____doc__has_contentrequired_argumentsoptional_argumentsfinal_argument_whitespacere    r    r   r"   r"   B   s"    4K $Ir    r"   c                  4    e Zd ZU dej                  iZded<   y)TestsetupDirectiver?   ClassVar[OptionSpec]option_specNrg   rh   ri   r   unchanged_requiredrs   __annotations__ro   r    r   rq   rq          *//)K% r    rq   c                  4    e Zd ZU dej                  iZded<   y)TestcleanupDirectiver?   rr   rs   Nrt   ro   r    r   ry   ry      rw   r    ry   c                      e Zd ZU ej                  ej                  ej
                  ej                  ej                  ej                  dZded<   y)DoctestDirectiver+   r(   r7   r;   r?   r@   rr   rs   N	rg   rh   ri   r   rc   	unchangedru   rs   rv   ro   r    r   r{   r{      A    !+''22//(oo)K% r    r{   c                      e Zd ZU ej                  ej                  ej
                  ej
                  ej                  dZded<   y)TestcodeDirective)r+   r(   r;   r?   r@   rr   rs   N)rg   rh   ri   r   rc   ru   rs   rv   ro   r    r   r   r      s8    !+22//(oo)K% r    r   c                      e Zd ZU ej                  ej                  ej
                  ej                  ej                  ej                  dZded<   y)TestoutputDirectiver|   rr   rs   Nr}   ro   r    r   r   r      r   r    r   c                  &    e Zd ZddZdddZddZy)		TestGroupc                <    || _         g | _        g | _        g | _        y N)rD   setuptestscleanup)rZ   rD   s     r   __init__zTestGroup.__init__   s    	%'
CE
')r    c                d   |j                   dk(  r;|r| j                  j                  d|       y | j                  j                  |       y |j                   dk(  r| j                  j                  |       y |j                   dk(  r| j
                  j                  |g       y |j                   dk(  r| j
                  j                  |d f       y |j                   dk(  r@| j
                  r3| j
                  d   }t        |      dk(  r|d   |g| j
                  d<   y y y t        t        d	            )
Nr)   r   r*   r&   r3   r5      zinvalid TestCode type)	typer   insertappendr   r   lenRuntimeErrorr   )rZ   r[   prependlatest_tests       r   add_codezTestGroup.add_code   s    99#

!!!T*

!!$'YY-'LL%YY)#JJtf%YY*$JJtTl+YY,&zz"jjn{#q(&1!nd%;DJJrN ) 
 r"9:;;r    c           	     p    d| j                   d| j                  d| j                  d| j                  d	S )NzTestGroup(name=z, setup=z
, cleanup=z, tests=))rD   r   r   r   rZ   s    r   __repr__zTestGroup.__repr__   s=    dii](4::. A||&htzznA?	
r    N)rD   rW   rf   None)F)r[   TestCoder   boolrf   r   rf   rW   )rg   rh   ri   r   r   r   ro   r    r   r   r      s    *<*
r    r   c                  6    e Zd Z	 d	 	 	 	 	 	 	 	 	 	 	 ddZddZy)r   Nc                R    || _         || _        || _        || _        |xs i | _        y r   r[   r   filenamerT   r7   )rZ   r[   r   r   rT   r7   s         r   r   zTestCode.__init__   s+     		 (/2r    c                    d| j                   d| j                  d| j                  d| j                  d| j                  dS )Nz	TestCode(z, z, filename=z	, lineno=z
, options=r   r   r   s    r   r   zTestCode.__repr__   sI    		}Btyym;t}}>O Pkk_Jt||.>aA	
r    r   )r[   rW   r   rW   r   rW   rT   intr7   zdict[int, bool] | Nonerf   r   r   )rg   rh   ri   r   r   ro   r    r   r   r      sK     +/66 6 	6
 6 (6 
6
r    r   c                  D     e Zd Z	 d	 	 	 	 	 d fdZ	 d	 	 	 	 	 ddZ xZS )SphinxDocTestRunnerc                    t               }t        j                  }|t        _        	 t        |   |      }|t        _         ||j                                |S # |t        _        w xY wr   )r   rX   stdoutsuper	summarizegetvalue)rZ   outverbose	string_io
old_stdoutres	__class__s         r   r   zSphinxDocTestRunner.summarize  sX     J	ZZ

	$'#G,C#CJI !
 $CJs   A A'c                h   | j                   j                  |      }|ru|j                  d      | j                  j                  k(  rM	 | j                  j
                  t        |j                  d               }|j                  j                  d      S | j                  ||      S # t        $ r Y w xY w)NrD   
examplenumT)%_DocTestRunner__LINECACHE_FILENAME_REmatchgroupr0   rD   examplesr   source
splitlines
IndexErrorsave_linecache_getlines)rZ   r   module_globalsmexamples        r   *_DocTestRunner__patched_linecache_getlinesz>SphinxDocTestRunner._DocTestRunner__patched_linecache_getlines  s     66<<XFDIINN27)),,S1F-GH ~~0066++HnEE	  s   1B% %	B10B1r   )r   zCallable[[str], None]r   zbool | Nonerf   ztuple[int, int])r   rW   r   r   rf   r   )rg   rh   ri   r   r   __classcell__)r   s   @r   r   r     sI    AE(3>	 48FF-0F	Fr    r   c                      e Zd ZdZdZ ed      ZddZddZddZ	ddZ
ddd	Zdd
ZddZddZddZedd       ZddZddZ	 	 	 	 	 	 	 	 	 	 	 	 ddZddZy)DocTestBuilderz(Runs test snippets in the documentation.r&   zZTesting of doctests in the sources finished, look at the results in %(outdir)s/output.txt.c                   | j                   j                  | _        | j                  t        _        | j                   j
                  t        j                  dd d| _        d| _	        d| _
        d| _        d| _        d| _        d| _        t        j                   d      }| j"                  j%                  d      }|j'                  dd      | _        dt+        |      z  }| j(                  j-                  d	| d
| d       y )Nr   singlez%Y-%m-%d %H:%M:%Sz
output.txtwzutf-8)encoding=z"Results of doctest builder run on z#
==================================r%   )configdoctest_default_flagsoptcompiler&   doctest_pathrX   pathr   total_failurestotal_triessetup_failuressetup_triescleanup_failurescleanup_triestimestrftimeoutdirjoinpathopenoutfiler   write)rZ   dateoutpathr9   s       r   initzDocTestBuilder.init-  s    ;;44 ,,001	 !}}01++&&|4||C'|:SY0 7115b:	
r    c                R    t        | d      r| j                  j                          y y )Nr   )hasattrr   closer   s    r   __del__zDocTestBuilder.__del__M  s#     4#LL  $r    c               h    t         j                  |d       | j                  j                  |       y )NTnonl)loggerinfor   r   rZ   texts     r   _outzDocTestBuilder._outS  s$    Dt$4 r    c                   | j                   j                  dk  rt        j                  |       nt        j	                  |d       | j
                  j                  |       y )Nr   Tr   )r   	verbosityr   rS   r   r   r   r   s     r   	_warn_outzDocTestBuilder._warn_outW  sB    ;;  1$NN4 KK4K(4 r    Nc                     y)Nr'   ro   )rZ   docnametyps      r   get_target_urizDocTestBuilder.get_target_uri^  s    r    c                .    | j                   j                  S r   )env
found_docsr   s    r   get_outdated_docsz DocTestBuilder.get_outdated_docsa  s    xx"""r    c                8   dd}d}| j                   s| j                  s| j                  r,d| j                  _        | j
                  j                  r| d}dt        |      z  }| j                  d| d| d| j                  dd || j                         d| j                   dd	 || j                          d
| j                  dd	 || j                         d| j                  dd	 || j                         d       | j                  j                          y )Nc                    | dk7  rdS dS )Nr#   sr'   ro   )vs    r   r   z DocTestBuilder.finish.<locals>.sf  s    q&3(b(r    zDoctest summaryr#   z" (exiting after first failed test)r   r%   5z testz failurez
 in tests
z in setup code
z in cleanup code
)r   r   rf   rW   )r   r   r   _app
statuscoder   doctest_fail_fastr   r   r   r   r   )rZ   r   header	underlines       r   finishzDocTestBuilder.finishd  s+   	) #$"5"59N9N#$DII {{,,"8#EF#f+%			 	
 ! E!D,,-. /Q x$"5"5 67 8Q x$"5"5 67 8q !D$9$9":!; <		
 	r    c                    t         j                  t        d             t        |      D ]J  }| j                  j                  |      }| j                  ||      }|r3| j                  j                  sJ y  y )Nzrunning tests...)	r   r   r   sortedr   get_doctreetest_docr   r   )rZ   docnamesr   doctreesuccesss        r   write_documentszDocTestBuilder.write_documents|  s^    D+,-h' 	Ghh**73GmmGW5Gt{{<<	r    c                    	 t        |j                  | j                  j                        }|j	                  d      d   S # t
        $ r( t        | j                  j                  |d            cY S w xY w)z|Try to get the file which actually contains the doctest, not the
        filename of the document it's included in.
        :docstring of r   F)r   r   r   srcdir	partition	ExceptionrW   doc2path)rZ   r^   r   r   s       r   get_filename_for_nodez$DocTestBuilder.get_filename_for_node  sa    	:t{{DHHOO<H%%&67:: 	:txx((%899	:s   =A   .A10A1c                    dt         j                  j                  | j                  xs d      v ry| j                  | j                  dz
  S y)z0Get the real line number or admit we don't know.r	  r'   Nr#   )osr   basenamer   r9   r^   s    r   get_line_numberzDocTestBuilder.get_line_number  sD    
 rww//0ArBB
 99 99q= r    c                   d|vry|d   }i }| j                   j                  r t        | j                   j                  |       t        ||      }| j                   j                  r t        | j                   j                  |       |S )Nr?   F)r   doctest_global_setupexecevaldoctest_global_cleanup)rZ   r^   	conditioncontextshould_skips        r   skippedzDocTestBuilder.skipped  so    4XI&(G{{//T[[55w?y'2K{{11T[[77Ar    c           
     "	   i }g }t        d| j                        | _        t        d| j                        | _        t        d| j                        | _        | j                  j
                  | j                  _        | j                  j
                  | j                  _        | j                  j                  rt        }nt        }|j                  |      D ]  }| j                  |      rd|v r|d   n|j                         }| j                  ||      }| j                  |      }	|s1t        j!                  t#        d      |j%                  dd      ||	       t'        ||j%                  dd      ||	|j%                  d            }
|j%                  d	| j                  j                  g      }d
|v r|j)                  |
       |D ](  }||vrt+        |      ||<   ||   j-                  |
       *   |D ](  }
|j/                         D ]  }|j-                  |
        * | j                  j0                  rKt'        | j                  j0                  ddd      }
|j/                         D ]  }|j-                  |
d        | j                  j2                  rIt'        | j                  j2                  ddd      }
|j/                         D ]  }|j-                  |
        |sy| j                  j4                  }|r$| j7                  d| ddt9        |      z   d       d}|j/                         D ].  }| j;                  |      rd}| j                  j<                  s. n | j                  j?                  | j6                  d      \  }}| xj@                  |z  c_         | xjB                  |z  c_!        | j                  jD                  rT| j                  j?                  | j6                  |      \  }}| xjF                  |z  c_#        | xjH                  |z  c_$        | j                  jD                  rT| j                  j?                  | j6                  |      \  }}| xjJ                  |z  c_%        | xjL                  |z  c_&        |S )NF)r   optionflagsr0   z#no code/output in %s block at %s:%sr.   r&   r7   )r   r   rT   r7   r/   *r)   z<global_setup>r   )r   rT   T)r   r*   z<global_cleanup>z
Document: z
-----------r%   )r   )'r   r   setup_runnertest_runnercleanup_runner_fakeoutr   doctest_test_doctest_blocks_condition_with_doctest_condition_defaultfindallr  astextr  r  r   rS   r   getr   r   r   r   valuesr  r  doctest_show_successesr   r   
test_groupr   r   r   r   triesr   r   r   r   )rZ   r   r  r/   add_to_all_groupsr  r^   r   r   line_numberr[   node_groups	groupnamer   show_successesr  res_fres_ts                     r   r  zDocTestBuilder.test_doc  s   ')/488T.u$((S1%TXXV$($5$5$>$>!'+'8'8'A'A$;;22/I*IOOI. 	1D||D!%+t^T&\F11$@H..t4K<=HH^Y7	 XXni8!"+D ((8dkk.U.U-VWKk!!((.( 1	F*(1)(<F9%y!**4013	1: & 	%D %t$%	% ;;++00)	D   3tT23;;--22+	D   %t$%;;IIWI\#G:L9MRPQ]]_ 	E??5);;00		 ((22499e2Luu$E!!!++55dii5XLE55(%$$..88		> 9 LE5 !!U*!%'r    c                4    t        ||| j                  ||      S r   )r   r   )rZ   r[   rD   r   flagsdont_inherits         r   r   zDocTestBuilder.compile  s     tT499e\BBr    c           	         i 	 	 	 	 	 	 	 	 d fd} | j                   j                  d      syd}j                  D ])  }t        |      dk(  r	 t        j                  |d   j                  i j                  |d   j                  |d   j                        }|j                  sj|j                  D ]A  }|d   j                  j!                         }|j#                  |j                         ||_        C d	 _        n|d   r|d   j                  nd
}|d   r|d   j                  ni }	d|	t&        j(                  <   t        j*                  j-                  |      }
|
r|
j/                  d      }nd }t'        j0                  |d   j                  |||d   j                  |	      }t'        j2                  |gi j                  |d   j                  |d   j                  d       }d _        |_         j6                  j8                  } j6                  j;                  | j<                  d        j6                  j8                  |kD  sd} j>                  j@                  s* n  | jB                  jD                  d      sy|S # t        $ rN t        j                  t        d      |d   j                  |d   j                  |d   j                  f       Y w xY w)Nc                   g }|D ]?  }t        j                  |j                  d|j                        }|j	                  |       A |syt        j
                  |i j                   d| d|d   j                  dd       }	|_        | j                  }d
_
        | j                  |
j                  d	       | j                  |k  S )
Nr'   )rT   Tz (z code)r   r  Fr   clear_globs)r&   Exampler[   rT   r   DocTestrD   r   globsfailuresr   re   r   )runner	testcodeswhatr   r3   r   sim_doctestold_fr   nsrZ   s           r   run_setup_cleanupz4DocTestBuilder.test_group.<locals>.run_setup_cleanup  s     H% )!//(--HOOT() !//::,bf-!%%K !#KOOEDIJJ{EJJ??e++r    r   FTr#   r   z!ignoring invalid doctest code: %r)locationr   r'   msg)exc_msgrT   r7   r  r;  r   )rA  r   rB  zlist[TestCode]rC  r   rf   r   )#r!  r   r   r   parserget_doctestr[   rD   r   rT   r  r   rS   r   r   r7   copyupdater   r&   DONT_ACCEPT_BLANKLINE_EXCEPTION_REr   r   r=  r>  r?  r"  r@  re   r   r   r   r#  r   )rZ   r   rG  r  r[   r0   r   new_optoutputr7   r   rJ  rE  rF  s   ``           @r   r-  zDocTestBuilder.test_group  s   	,	,$2	,:=	,	,2 !!2!2EKKI KK :	D4yA~
!--Qb%**d1g6F6FQD }}#}} .G"1goo224GNN7??3&-GO	.
 %	 *.aab-1!W$q'//"9=556((..v6ggenG"G!//GLL#7>># IJJG$$GNN #	DJ$$--E  4>>u M((50;;00u:	z !!4!4emmYOs ! NN>?Q"&q'"2"2DGNN!C # 
 s   A
JAK('K()rf   r   )r   rW   rf   r   r   )r   rW   r   z
str | Nonerf   rW   )rf   zset[str])r  zSet[str]rf   r   )r^   r   r   rW   rf   rW   )r^   r   rf   z
int | None)r^   r   rf   r   )r   rW   r  r   rf   r   )r[   rW   rD   rW   r   rW   r7  r   r8  r   rf   r   )r   r   rf   r   )rg   rh   ri   rj   rD   r   epilogr   r   r   r   r   r   r   r  r  staticmethodr  r  r  r   r-  ro   r    r   r   r   $  s    2D	,F

@!!!#0:  ZxCC"C*-C69CIMC	C
br    r   c           	        | j                  dt               | j                  dt               | j                  dt               | j                  dt               | j                  dt
               | j                  t               | j                  dddt        t        h      	       | j                  d
ddt        t        t        h      	       | j                  dddt        t        h      	       | j                  dddt        t        h      	       | j                  dddt        t        h      	       | j                  dt        j                  t        j                   z  t        j"                  z  dt        t$        h      	       | j                  dddt        t        h      	       t&        j(                  ddS )Nr)   r*   r&   r3   r5   r,  Tr'   )typesr   ro   r%  r-   r  r  r   r   F)r   parallel_read_safe)add_directiverq   ry   r{   r   r   add_builderr   add_config_value	frozensetr   listtuplerW   r&   DONT_ACCEPT_TRUE_FOR_1ELLIPSISIGNORE_EXCEPTION_DETAILr   sphinx__display_version__)apps    r   r   r   r  s   k#56m%9:i!12j"34l$78OON#149dVCTURy$7OP%y"Ise<L   /Ry#?OP12rC5AQR&&


	

)
)	* 	   ,eRy$?PQ--" r    c                b    t        | t        j                  t        j                  f      xr d| v S )Nr.   )
isinstancer   rI   rJ   r  s    r   r'  r'    s-    4%--u}}=> 	#d"r    c                P    t        |       xs t        | t        j                        S r   )r'  re  r   doctest_blockr  s    r   r&  r&    s    d#Lz$8K8K'LLr    )r   rW   r   rW   rf   r   )rc  r   rf   r   )r^   r   rf   r   )Irj   
__future__r   r&   os.pathr  rerX   r   ior   typingr   docutilsr   docutils.parsers.rstr   packaging.specifiersr   r	   packaging.versionr
   ra  sphinx._cli.util.colourr   sphinx.buildersr   sphinx.localer   sphinx.utilr   sphinx.util.docutilsr   sphinx.util.osutilr   collections.abcr   r   r   r   docutils.nodesr   r   r   sphinx.applicationr   sphinx.util.typingr   r   	getLoggerrg   r   r   	MULTILINErE   rG   r   r"   rq   ry   r{   r   r   DocTestParserrK  r   r   DocTestRunnerr   r   r   r'  r&  ro   r    r   <module>r     sG  
 #   	 
      + ? %  ( #   0 &-$99)@ 
		8	$rzz,bll;

3R\\B2*QO Qh = }  -  
			  
  
F
 
,F'// FFKW K\
<Mr    