
    7 fZ                       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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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*m+Z+ ddl,m-Z- ddl.m/Z/  ej0        e1          Z2 ej3        dej4                  Z5 ej3        dej4                  Z6d5dZ7 G d de"          Z8 G d d e8          Z9 G d! d"e8          Z: G d# d$e8          Z; G d% d&e8          Z< G d' d(e8          Z= ej>                    Z? G d) d*          Z@ G d+ d,          ZA G d- d.ejB                  ZC G d/ d0e          ZDd6d4ZEdS )7zfMimic doctest in Sphinx.

The extension automatically execute code snippets and checks their results.
    )annotationsN)StringIO)path)TYPE_CHECKINGAnyCallable)nodes)
directives)InvalidSpecifierSpecifierSet)Version)Builder)__)logging)bold)SphinxDirective)relpath)IterableSequence)ElementNodeTextElement)Sphinx)
OptionSpecz^\s*<BLANKLINE>z#\s*doctest:.+$specstrversionreturnboolc                >    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   )r   r   s     H/var/www/equiseq/venv/lib/python3.11/site-packages/sphinx/ext/doctest.pyis_allowed_versionr"   ,   s     7|D1111    c                  *    e Zd ZdZdZdZdZdZd	dZdS )
TestDirectivez4
    Base class for doctest-related directives.
    Tr      r   
list[Node]c                   d                     | j                  }d }| j        dk    rcd|v r|}t                              d|          }t
                              |          r(d| j        vr|s|}t
                              d|          }t          j	        }| j        dv s	d| j        v rt          j
        }| j        r+d | j        d	                             d
          D             }ndg} |||| 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                             d
d                                          }|D ]}|d	         |dd          }	}|dvr<| j        j        j                            t'          d          |z  | j                   T|	t*          j        vr<| j        j        j                            t'          d          |	z  | j                   t*          j        |dd                   }
|d	         dk    |d         |
<   | j        dk    rd| j        v r	 | j        d         }d                     d t.          j        d d          D                       }t3          ||          st*          j        d!         }
d"|d         |
<   nK# t4          $ r> | j        j        j                            t'          d#          |z  | j                   Y nw xY wd$| j        v r| j        d$         |d$<   d%| j        v rd"|d&<   nd| j        v rd'|d&<   |gS )(N
doctestz<BLANKLINE> no-trim-doctest-flags)	testsetuptestcleanuphidec                6    g | ]}|                                 S  )strip).0xs     r!   
<listcomp>z%TestDirective.run.<locals>.<listcomp>\   s     FFFAaggiiFFFr#   r   ,default)testnodetypegroupstestpyconlanguagetestcodepython
testoutputnoneoptions)r*   r?    r&   z+-z"missing '+' or '-' in '%s' option.)linez'%s' is not a valid option.+	pyversion.c                ,    g | ]}t          |          S r1   )r   )r3   vs     r!   r5   z%TestDirective.run.<locals>.<listcomp>   s    *P*P*Pa3q66*P*P*Pr#      SKIPTz$'%s' is not a valid pyversion optionskipiftrim-doctest-flags
trim_flagsF)joincontentnameblankline_resubdoctestopt_researchrA   r	   literal_blockcomment	argumentssplitset_source_inforeplacestatedocumentreporterwarningr   linenor*   OPTIONFLAGS_BY_NAMEsysversion_infor"   r   )selfcoder:   nodetyper9   nodeoption_stringsoptionprefixoption_nameflagr   python_versions                r!   runzTestDirective.runJ   s    yy&&9	!!$$#''D11##D)) 3.ET\.Y.Y  D$((T22&+&99444$,8N8N}H> 	!FF):)@)@)E)EFFFFF[Fxd6JJJT"""DL9	!!&DY*$$'DY,&&%DY9111i4<6O6O!\)4<<S#FFLLNNN( ; ;&,Qi%%J'088?@@6I![ 9 * * * g&AAAJ'088899KG![ 9 * * * 26!"":>)/c)9Y%%9	!!kT\&A&A	&|K0!$*P*P3;KBQB;O*P*P*P!Q!Q)$?? 1"6v>D,0DOD)# & & &
#,44=>>E 5 & & & & && t|##!\(3DN4<//!%D$44!&Dvs   =A+K) )AL10L1N)r   r'   )	__name__
__module____qualname____doc__has_contentrequired_argumentsoptional_argumentsfinal_argument_whitespacerm   r1   r#   r!   r%   r%   @   sQ          K $D D D D D Dr#   r%   c                  ,    e Zd ZU dej        iZded<   dS )TestsetupDirectiverK   r   option_specNrn   ro   rp   r
   unchanged_requiredrx   __annotations__r1   r#   r!   rw   rw      9         */K      r#   rw   c                  ,    e Zd ZU dej        iZded<   dS )TestcleanupDirectiverK   r   rx   Nry   r1   r#   r!   r~   r~      r|   r#   r~   c                  h    e Zd ZU ej        ej        ej        ej        ej        ej        dZded<   dS )DoctestDirectiver/   r,   rA   rE   rK   rL   r   rx   N	rn   ro   rp   r
   rk   	unchangedrz   rx   r{   r1   r#   r!   r   r      W         !+'2/(o K      r#   r   c                  \    e Zd ZU ej        ej        ej        ej        ej        dZded<   dS )TestcodeDirective)r/   r,   rE   rK   rL   r   rx   N)rn   ro   rp   r
   rk   rz   rx   r{   r1   r#   r!   r   r      sQ         !+2/(o K      r#   r   c                  h    e Zd ZU ej        ej        ej        ej        ej        ej        dZded<   dS )TestoutputDirectiver   r   rx   Nr   r1   r#   r!   r   r      r   r#   r   c                  (    e Zd ZddZdddZddZdS )	TestGrouprP   r   r   Nonec                >    || _         g | _        g | _        g | _        d S N)rP   setuptestscleanup)rc   rP   s     r!   __init__zTestGroup.__init__   s"    	%'
CE
')r#   Frd   TestCodeprependr   c                J   |j         dk    r;|r| j                            d|           d S | j                            |           d S |j         dk    r| j                            |           d S |j         dk    r| j                            |g           d S |j         dk    r| j                            |d f           d S |j         dk    r?| j        r4| j        d         }t          |          dk    r|d         |g| j        d<   d S d S d S t          t          d	                    )
Nr-   r   r.   r*   r=   r?      zinvalid TestCode type)	typer   insertappendr   r   lenRuntimeErrorr   )rc   rd   r   latest_tests       r!   add_codezTestGroup.add_code   sH   9## (
!!!T*****
!!$'''''Y-''L%%%%%Y)##Jtf%%%%%Y*$$JtTl+++++Y,&&z <"jn{##q((&1!nd%;DJrNNN< <(( r"9::;;;r#   c           	     H    d| j         d| j        d| j        d| j        d	S )NzTestGroup(name=z, setup=z
, cleanup=z, tests=))rP   r   r   r   rc   s    r!   __repr__zTestGroup.__repr__   sV    C$) C Ctz C C<C C37:C C C 	Dr#   N)rP   r   r   r   )F)rd   r   r   r   r   r   r   r   )rn   ro   rp   r   r   r   r1   r#   r!   r   r      s[        * * * *< < < < <*D D D D D Dr#   r   c                  "    e Zd Z	 dddZddZdS )r   Nrd   r   r   filenamer_   intrA   dict | Noner   r   c                P    || _         || _        || _        || _        |pi | _        d S r   rd   r   r   r_   rA   )rc   rd   r   r   r_   rA   s         r!   r   zTestCode.__init__   s-    		 }"r#   c                X    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__   sf    EDI E E49 E E4= E E+E E37<E E E 	Fr#   r   )rd   r   r   r   r   r   r_   r   rA   r   r   r   r   )rn   ro   rp   r   r   r1   r#   r!   r   r      sJ        59% % % % %F F F F F Fr#   r   c                  .     e Zd Zdd fdZ	 dddZ xZS )SphinxDocTestRunnerNoutr   verbosebool | Noner   tuple[int, int]c                   t                      }t          j        }|t          _        	 t                                          |          }|t          _        n# |t          _        w xY w ||                                           |S r   )r   ra   stdoutsuper	summarizegetvalue)rc   r   r   	string_io
old_stdoutres	__class__s         r!   r   zSphinxDocTestRunner.summarize   ss    JJ	Z

	$''##G,,C#CJJCJ####I  !!!
s   !A A%r   r   module_globalsr   c                f   | j                             |          }|r|                    d          | j        j        k    r]	 | j        j        t          |                    d                             }|j                            d          S # t          $ r Y nw xY w| 
                    ||          S )NrP   
examplenumT)%_DocTestRunner__LINECACHE_FILENAME_REmatchgroupr:   rP   examplesr   source
splitlines
IndexErrorsave_linecache_getlines)rc   r   r   mexamples        r!   *_DocTestRunner__patched_linecache_getlinesz>SphinxDocTestRunner._DocTestRunner__patched_linecache_getlines   s     6<<  		7DIN227),S1F1F-G-GH ~00666     ++n& & 	&s   2B 
BBr   )r   r   r   r   r   r   )r   r   r   r   r   r   )rn   ro   rp   r   r   __classcell__)r   s   @r!   r   r      sb        
 
 
 
 
 
 
 JN& & & & & & & & &r#   r   c                      e Zd ZdZdZ ed          Zd.dZd/d	Zd/d
Z	d0d1dZ
d2dZd.dZ	 d3d4dZd5dZed6d            Zd7d!Zd8d#Zd9d*Zd:d-ZdS );DocTestBuilderz2
    Runs test snippets in the documentation.
    r*   zZTesting of doctests in the sources finished, look at the results in %(outdir)s/output.txt.r   r   c           	        | j         j        | _        | j        t          _        | j         j        t          j        dd<   d| _        d| _	        d| _
        d| _        d| _        d| _        d| _        t          j        d          }| j                            d          }|                    dd          | _        | j                            d|d	d
t-          |          z  d           d S )Nr   singlez%Y-%m-%d %H:%M:%Sz
output.txtwzutf-8)encodingz"Results of doctest builder run on z#
===================================r)   )configdoctest_default_flagsoptcompiler*   doctest_pathra   r   r   total_failurestotal_triessetup_failuressetup_triescleanup_failurescleanup_triestimestrftimeoutdirjoinpathopenoutfilewriter   )rc   dateoutpaths      r!   initzDocTestBuilder.init  s    ;4 ,01	 !}011+&&|44||C'|:: DD#D		///3 	4 	4 	4 	4 	4r#   textr   c                r    t                               |d           | j                            |           d S NT)nonl)loggerinfor   r   rc   r   s     r!   _outzDocTestBuilder._out9  s4    Dt$$$4     r#   c                    | j         j        s| j         j        rt                              |           nt                              |d           | j                            |           d S r   )appquietwarningiserrorr   r^   r   r   r   r   s     r!   	_warn_outzDocTestBuilder._warn_out=  sa    8> 	)TX4 	)NN4    KK4K(((4     r#   Ndocnametyp
str | Nonec                    dS )Nr+   r1   )rc   r   r   s      r!   get_target_urizDocTestBuilder.get_target_uriD  s    rr#   set[str]c                    | j         j        S r   )env
found_docsr   s    r!   get_outdated_docsz DocTestBuilder.get_outdated_docsG  s    x""r#   c           
     b   dd}| j          || j                   | j         || j                  | j         || j                  | j         || j                  f}|                     d|z             | j                                         | j        s| j        s| j        rd| j        _        d S d S )	NrH   r   r   r   c                    | dk    rdndS )Nr&   sr+   r1   )rH   s    r!   r   z DocTestBuilder.finish.<locals>.sL  s    q&&33b(r#   z}
Doctest summary
===============
%5d test%s
%5d failure%s in tests
%5d failure%s in setup code
%5d failure%s in cleanup code
r&   )rH   r   r   r   )	r   r   r   r   r   r   closer   
statuscode)rc   r   repls      r!   finishzDocTestBuilder.finishJ  s    	) 	) 	) 	) !!D$4"5"5#QQt':%;%;#QQt':%;%;%qq)>'?'?A 			   	 	 	 	 	$$"5 	$9N 	$"#DH	$ 	$r#   updatebuild_docnamesIterable[str] | Noneupdated_docnamesSequence[str]methodc                    |t          | j        j                  }t                              t          d                     |D ]2}| j                            |          }|                     ||           3d S )Nzrunning tests...)sortedr   all_docsr   r   r   get_doctreetest_doc)rc   r  r  r  r   doctrees         r!   r   zDocTestBuilder.write_  sz    !#DH$566ND+,,---% 	, 	,Gh**733GMM'7++++	, 	,r#   rf   r   c                    	 t          |j        | j        j                                      dd          d         }n+# t
          $ r | j                            |d          }Y nw xY w|S )zsTry to get the file which actually contains the doctest, not the
        filename of the document it's included in.:docstring of r&   )maxsplitr   F)r   r   r   srcdirrsplit	Exceptiondoc2path)rc   rf   r   r   s       r!   get_filename_for_nodez$DocTestBuilder.get_filename_for_nodej  sr    	9t{DHO<<(155a9HH 	9 	9 	9x((%88HHH	9s   := %A%$A%r   c                f    dt          j        | j        pd          v rdS | j        
| j        dz
  S dS )z0Get the real line number or admit we don't know.r  r+   Nr&   )r   basenamer   rC   rf   s    r!   get_line_numberzDocTestBuilder.get_line_numbert  s@    
 t}T[->B????
 49 9q= tr#   r   r   c                    d|vrdS |d         }i }| j         j        rt          | j         j        |           t          ||          }| j         j        rt          | j         j        |           |S )NrK   F)r   doctest_global_setupexecevaldoctest_global_cleanup)rc   rf   	conditioncontextshould_skips        r!   skippedzDocTestBuilder.skipped  s{    45XI&(G{/ @T[5w???y'22K{1 BT[7AAAr#   r  c           
     H   i }g }t          d| j                  | _        t          d| j                  | _        t          d| j                  | _        | j        j        | j        _        | j        j        | j        _        | j        j        rdd}ndd}|                    |          D ]G}| 	                    |          rd	|v r|d	         n|
                                }|                     ||          }|                     |          }	|s>t                              t          d
          |                    dd          ||	           t#          ||                    dd          ||	|                    d                    }
|                    ddg          }d|v r|                    |
           |D ]3}||vrt'          |          ||<   ||                             |
           4I|D ].}
|                                D ]}|                    |
           /| j        j        rKt#          | j        j        ddd          }
|                                D ]}|                    |
d           | j        j        rIt#          | j        j        ddd          }
|                                D ]}|                    |
           |sd S | j        j        }|r,|                     d| ddt5          |          z   d           |                                D ]}|                     |           | j                            | j        d          \  }}| xj        |z  c_        | xj        |z  c_        | j        j        rD| j                            | j        |          \  }}| xj         |z  c_         | xj!        |z  c_!        | j        j        rF| j                            | j        |          \  }}| xj"        |z  c_"        | xj#        |z  c_#        d S d S ) NF)r   optionflagsrf   r   r   r   c                    t          | t          j        t          j        f          rd| v pt          | t          j                  S Nr8   )
isinstancer	   rU   rV   doctest_blockr  s    r!   r  z*DocTestBuilder.test_doc.<locals>.condition  s@    "4%*=u})MNN /&$.:tU%899:r#   c                V    t          | t          j        t          j        f          od| v S r&  )r'  r	   rU   rV   r  s    r!   r  z*DocTestBuilder.test_doc.<locals>.condition  s+    !$)<em(LMM /&$./r#   r:   z#no code/output in %s block at %s:%sr8   r*   rA   )r   r   r_   rA   r9   r7   *r-   z<global_setup>r   )r   r_   T)r   r.   z<global_cleanup>z
Document: z
-----------r)   )r   )rf   r   r   r   )$r   r   setup_runnertest_runnercleanup_runner_fakeoutr   doctest_test_doctest_blocksfindallr"  astextr  r  r   r^   r   getr   r   r   r   valuesr  r  doctest_show_successesr   r   
test_groupr   r   r   triesr   r   r   r   )rc   r   r  r9   add_to_all_groupsr  rf   r   r   line_numberrd   node_groups	groupnamer   show_successesres_fres_ts                    r!   r  zDocTestBuilder.test_doc  s   ')/<@HF F F.u;?8E E E1%>BhH H H %)$5$>!'+'8'A$;2 	/: : : : :
/ / / / OOI.. 	1 	1D||D!! %+t^^T&\\F11$@@H..t44K 6r"GHH#xx	BB'6 6 6 F.))L)L%-k$(HHY$7$79 9 9D ((8i[99Kk!!!((...( 1 1	F**(1)(<(<F9%y!**400001 & 	% 	%D % %t$$$$%;+ 	3DK<'2B1N N ND 3 3tT2222;- 	%DK>)4FqR R RD % %t$$$$ 	F; 	;II :#*: :#&W#5: : : ; ; ; ]]__ 	# 	#EOOE""""(2249e2LLuu$E!! 	&+55	> 6 3 3LE55(%$ 	(.88	> 9 3 3LE5!!U*!!%'		( 	(r#   rd   rP   r   flagsr   dont_inheritc                2    t          ||| j        ||          S r   )r   r   )rc   rd   rP   r   r?  r@  s         r!   r   zDocTestBuilder.compile  s    tT49e\BBBr#   r   r   c           	         i d fd} | j         j        d	          sd S j        D ]}t          |          d
k    r	 t                              |d         j        i j        |d         j        |d         j	                  }n]# t          $ rP t                              t          d          |d         j        |d         j        |d         j	        f           Y w xY w|j        s|j        D ]B}|d         j                                        }|                    |j                   ||_        Cd _        n|d
         r|d
         j        nd}|d
         r|d
         j        ni }d|t&          j        <   t          j                            |          }	|	r|	                    d          }
nd }
t'          j        |d         j        ||
|d         j	        |          }t'          j        |gi j        |d         j        |d         j	        d           }d _        |_         j                            | j        d            | j        j        d           d S )Nrunnerr   	testcodeslist[TestCode]whatr   r   c                f   g }|D ]8}t          j        |j        d|j                  }|                    |           9|sdS t          j        |i j         d| d|d         j        dd           }	|_        | j	        }d
_
        |                     |
j        d	           | j	        |k    rdS dS )
Nr+   )r_   Tz (z code)r   r  Fr   clear_globs)r*   Examplerd   r_   r   DocTestrP   r   globsfailuresr   rm   r   )rC  rD  rF  r   r=   r   sim_doctestold_fr   nsrc   s           r!   run_setup_cleanupz4DocTestBuilder.test_group.<locals>.run_setup_cleanup  s    H% ) )!/(-HOTTT(((( t!/(B-2Z*G*G4*G*G*G*3A,*?DJ JK !#KOEDIJJ{EJJJJ&&u4r#   r   r&   r   z!ignoring invalid doctest code: %r)locationr   r+   Tmsg)exc_msgr_   rA   r  FrH  r   )rC  r   rD  rE  rF  r   r   r   ) r,  r   r   r   parserget_doctestrd   rP   r   r_   r  r   r^   r   r   rA   copyr  r   r*   DONT_ACCEPT_BLANKLINE_EXCEPTION_REr   r   rJ  rK  rL  r-  rm   r   r.  r   )rc   r   rQ  rd   r:   r   new_optoutputrA   r   rT  rP  s   ``         @r!   r6  zDocTestBuilder.test_group  s   	 	 	 	 	 	 	 	( ! !2EKII 	F K &	N &	ND4yyA~~!--d1glB
.21g.>QP PDD    NN2&I#J#JDQRGL-1!W-=tAw~,N # P P PH } #} . .G"1go2244GNN7?333&-GOO$		 *.a8ab-1!W<$q'//"9=56(..v66 #ggennGG"G!/$q',15aR R Ry"ej'+Aw'7aO O"	DJ  4>u MMMM 	$-u}iHHHHHs   AB

AC$#C$)r   r   )r   r   r   r   r   )r   r   r   r   r   r   )r   r   )r  )r  r  r  r  r  r   r   r   )rf   r   r   r   r   r   )rf   r   r   r   )rf   r   r   r   )r   r   r  r   r   r   )rd   r   rP   r   r   r   r?  r   r@  r   r   r   )r   r   r   r   )rn   ro   rp   rq   rP   r   epilogr   r   r   r   r   r  r   r  staticmethodr  r"  r  r   r6  r1   r#   r!   r   r     so         DR 4 5 5F4 4 4 4<! ! ! !! ! ! !    # # # #$ $ $ $, %	, 	, 	, 	, 	,       \   P( P( P( P(dC C C CEI EI EI EI EI EIr#   r   r   r   dict[str, Any]c                   |                      dt                     |                      dt                     |                      dt                     |                      dt                     |                      dt
                     |                     t                     |                     dddt          f           |                     d	g d           |                     d
dd           |                     ddd           |                     ddd           |                     dt          j        t          j        z  t          j        z  d           t          j        ddS )Nr-   r.   r*   r=   r?   r5  TFr   r0  r7   r  r+   r  r   )r   parallel_read_safe)add_directiverw   r~   r   r   r   add_builderr   add_config_valuer   r*   DONT_ACCEPT_TRUE_FOR_1ELLIPSISIGNORE_EXCEPTION_DETAILsphinx__display_version__)r   s    r!   r   r   .  sN   k#5666m%9:::i!1222j"3444l$7888OON###14HHHU3336	5III/U;;;12u===&)99G<[[   1NNNr#   )r   r   r   r   r   r   )r   r   r   r^  )Frq   
__future__r   r*   rera   r   ior   osr   typingr   r   r   docutilsr	   docutils.parsers.rstr
   packaging.specifiersr   r   packaging.versionr   rg  sphinx.buildersr   sphinx.localer   sphinx.utilr   sphinx.util.consoler   sphinx.util.docutilsr   sphinx.util.osutilr   collections.abcr   r   docutils.nodesr   r   r   sphinx.applicationr   sphinx.util.typingr   	getLoggerrn   r   r   	MULTILINErQ   rS   r"   r%   rw   r~   r   r   r   DocTestParserrU  r   r   DocTestRunnerr   r   r   r1   r#   r!   <module>r     s   
 # " " " " "  				 



              / / / / / / / / / /       + + + + + + ? ? ? ? ? ? ? ? % % % % % %  # # # # # #             $ $ $ $ $ $ 0 0 0 0 0 0 & & & & & & .222222229999999999))))))------ 
	8	$	$rz,bl;;
-r|<<2 2 2 2(N N N N NO N N Nb           =       }              -    
		 	 
D D D D D D D DBF F F F F F F F& & & & &'/ & & &DXI XI XI XI XIW XI XI XIvO O O O O Or#   