
    }cX                        d 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mZmZmZ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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- ddl.m/Z/ e
rddl0m1Z1  e'j2        e3          Z4 ej5        dej6                  Z7 ej5        dej6                  Z8de9de9de:fdZ; G d de+          Z< G d de<          Z= G d de<          Z> G d d e<          Z? G d! d"e<          Z@ G d# d$e<          ZA ejB                    ZC G d% d&          ZD G d' d(          ZE G d) d*ejF                  ZG G d+ d,e#          ZHd-d.dee9ef         fd/ZIdS )0zfMimic doctest in Sphinx.

The extension automatically execute code snippets and checks their results.
    N)StringIO)path)
TYPE_CHECKINGAnyCallableDictIterableListSequenceSetTupleType)nodes)ElementNodeTextElement)
directives)InvalidSpecifierSpecifierSet)Version)Builder)__)logging)bold)SphinxDirective)relpath)
OptionSpec)Sphinxz^\s*<BLANKLINE>z#\s*doctest:.+$specversionreturnc                 >    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.3', '<=3.5')
        True
        >>> is_allowed_version('3.3', '<=3.2')
        False
        >>> is_allowed_version('3.3', '>3.2, <4.0')
        True
    )r   r   )r   r    s     2lib/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ee	         fdZ
dS )TestDirectivez4
    Base class for doctest-related directives.
    Tr      r!   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| j        j        dv rd|d<   n;d|d<   n5| j        dk    r| j        j        dv rd|d<   n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" t2          j        d d#         D                       }t7          ||          st.          j        d$         }
d%|d         |
<   nK# t8          $ 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>X   s     FFFAaggiiFFFr%   r   ,default)testnodetypegroupstest)pypythonpyconlanguagepycon3testcoder=   python3
testoutputnoneoptions)r+   rC    r(   z+-z"missing '+' or '-' in '%s' option.)linez'%s' is not a valid option.+	pyversion.c                 ,    g | ]}t          |          S r2   )str)r4   vs     r#   r6   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searchrE   r   literal_blockcomment	argumentssplitset_source_infoconfighighlight_languagereplacestatedocumentreporterwarningr   linenor+   OPTIONFLAGS_BY_NAMEsysversion_infor$   r   )selfcoder;   nodetyper:   nodeoption_stringsoptionprefixoption_nameflagr   python_versions                r#   runzTestDirective.runF   sU    yy&&9	! 	3$ 2#''D11##D)) 3.ET\.Y 3  D$((T22&+&9944 	%$,8N 	%}H> 	!FF):)@)@)E)EFFFFF[Fxd6JJJT""" 	 DL9	! 	&{-1AA ,#*Z  #+Z  Y*$ 	&{-1AA -#+Z  #,Z  Y,& 	&%DY911 	;i4<6O 	;!\)4<<S#FFLLNNN( ; ;&,Qi% J'088?@@6I![ 9 * * * g&AA J'088899KG![ 9 * * * 26!"":>)/c)9Y%%9	! 
	&kT\&A 
	&	&|K0!$*P*P3;KBQB;O*P*P*P!Q!Q)$?? 1"6v>D,0DOD)# & & &
#,44=>>E 5 & & & & && t|# 	4!\(3DN4</ 	'!%D$4 	'!&Dvs   %A+L AMMN)__name__
__module____qualname____doc__has_contentrequired_argumentsoptional_argumentsfinal_argument_whitespacer
   r   rt   r2   r%   r#   r'   r'   <   s]          K $JT$Z J J J J J Jr%   r'   c                   ,    e Zd ZU dej        iZeed<   dS )TestsetupDirectiverP   option_specNru   rv   rw   r   unchanged_requiredr   r   __annotations__r2   r%   r#   r~   r~      6         */K     r%   r~   c                   ,    e Zd ZU dej        iZeed<   dS )TestcleanupDirectiverP   r   Nr   r2   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ee	d<   dS )DoctestDirectiver0   r-   rE   rI   rP   rQ   r   N
ru   rv   rw   r   rr   	unchangedr   r   r   r   r2   r%   r#   r   r      T         !+'2/(o K     r%   r   c                   \    e Zd ZU ej        ej        ej        ej        ej        dZeed<   dS )TestcodeDirective)r0   r-   rI   rP   rQ   r   N)	ru   rv   rw   r   rr   r   r   r   r   r2   r%   r#   r   r      sN         !+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ee	d<   dS )TestoutputDirectiver   r   Nr   r2   r%   r#   r   r      r   r%   r   c                   @    e Zd ZdeddfdZddddeddfd	Zdefd
ZdS )	TestGrouprU   r!   Nc                 >    || _         g | _        g | _        g | _        d S N)rU   setuptestscleanup)rj   rU   s     r#   __init__zTestGroup.__init__   s"    	%'
+-
')r%   Frk   TestCodeprependc                 B   |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 g           d S |j         dk    r;| j        r0t          | j        d                   dk    r|| j        d         d	<   d S d S d S t          t          d
                    )Nr.   r   r/   r+   rA   rC      r(   zinvalid TestCode type)	typer   insertappendr   r   lenRuntimeErrorr   )rj   rk   r   s      r#   add_codezTestGroup.add_code   sP   9# 	< (
!!!T*****
!!$'''''Y-' 
	<L%%%%%Y)# 	<Jtf%%%%%Y*$ 	<JtTl+++++Y,& 	<z )c$*R.11Q6 )$(
2q!!!) ) ) ) r"9::;;;r%   c           	      H    d| j         d| j        d| j        d| j        d	S )NzTestGroup(name=z, setup=z
, cleanup=z, tests=))rU   r   r   r   rj   s    r#   __repr__zTestGroup.__repr__   s/     IIItzzz4<<<= 	=r%   )F)ru   rv   rw   rL   r   boolr   r   r2   r%   r#   r   r      s        *S *T * * * *< <Z <$ <4 < < < <$=# = = = = = =r%   r   c                   >    e Zd Z	 d
dedededededdfdZdefd	ZdS )r   Nrk   r   filenamerf   rE   r!   c                 P    || _         || _        || _        || _        |pi | _        d S r   rk   r   r   rf   rE   )rj   rk   r   r   rf   rE   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__   s9     IIItyyy$---dlllL 	Lr%   r   )ru   rv   rw   rL   intr   r   r   r2   r%   r#   r   r      s        .2% %S % %s %%'+%7;% % % %L# L L L L L Lr%   r   c            	       V     e Zd Zd	dededeeef         f fdZ	 d	dede	de	fdZ
 xZS )
SphinxDocTestRunnerNoutverboser!   c                    t                      }t          j        }|t          _        	 t                                          |          }|t          _        n# |t          _        w xY w ||                                           |S r   )r   rh   stdoutsuper	summarizegetvalue)rj   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   module_globalsc                 f   | j                             |          }|r|                    d          | j        j        k    r]	 | j        j        t          |                    d                             }|j                            d          S # t          $ r Y nw xY w| 
                    ||          S )NrU   
examplenumT)%_DocTestRunner__LINECACHE_FILENAME_REmatchgroupr;   rU   examplesr   source
splitlines
IndexErrorsave_linecache_getlines)rj   r   r   mexamples        r#   *_DocTestRunner__patched_linecache_getlinesz>SphinxDocTestRunner._DocTestRunner__patched_linecache_getlines   s     6<<XFF 		7DIN2 		77),S1F1F-G-GH ~00666     ++HnEEEs   2B 
BBr   )ru   rv   rw   r   r   r   r   r   rL   r   r   __classcell__)r   s   @r#   r   r      s        
 
X 
 
S#X
 
 
 
 
 
 JNF F3 FCFFRUF F F F F F F Fr%   r   c                   F   e Zd ZdZdZ ed          Zd"dZdeddfdZ	deddfd	Z
d#d
ededefdZdee         fdZd"dZ	 d$dee         dee         deddfdZded
edefdZededefd            ZdedefdZd
ededdfdZdedededededefdZd eddf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!   Nc           	         | j         j        | _        | j        t          _        | j         j        t          j        dd<   d| _        d| _	        d| _
        d| _        d| _        d| _        d| _        t          j        d          }t#          t          j        | 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*   )r_   doctest_default_flagsoptcompiler+   doctest_pathrh   r   r   total_failurestotal_triessetup_failuressetup_triescleanup_failurescleanup_triestimestrftimeopenrS   outdiroutfilewriter   )rj   dates     r#   initzDocTestBuilder.init  s    ;4 ,01	 !}011DIdk<@@#PWXXX DD#D		///3 	4 	4 	4 	4 	4r%   textc                 r    t                               |d           | j                            |           d S NT)nonl)loggerinfor   r   rj   r   s     r#   _outzDocTestBuilder._out5  s4    Dt$$$4     r%   c                     | j         j        s| j         j        rt                              |           nt                              |d           | j                            |           d S r   )appquietwarningiserrorr   re   r   r   r   r   s     r#   	_warn_outzDocTestBuilder._warn_out9  sa    8> 	)TX4 	)NN4    KK4K(((4     r%   docnametypc                     dS )Nr,   r2   )rj   r   r   s      r#   get_target_urizDocTestBuilder.get_target_uri@  s    rr%   c                     | j         j        S r   )env
found_docsr   s    r#   get_outdated_docsz DocTestBuilder.get_outdated_docsC  s    x""r%   c           
      ~   dt           dt          f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 )NrM   r!   c                     | dk    rdndS )Nr(   sr,   r2   )rM   s    r#   r   z DocTestBuilder.finish.<locals>.sH  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(   )r   rL   r   r   r   r   r   r   closer   
statuscode)rj   r   repls      r#   finishzDocTestBuilder.finishF  s    	) 	) 	) 	) 	) 	) !!D$4"5"5#QQt':%;%;#QQt':%;%;%qq)>'?'?A 			   	 	 	 	 	$$"5 	$9N 	$"#DH	$ 	$r%   updatebuild_docnamesupdated_docnamesmethodc                     |t          | j        j                  }t                              t          d                     |D ]2}| j                            |          }|                     ||           3d S )Nzrunning tests...)sortedr   all_docsr   r   r   get_doctreetest_doc)rj   r   r  r  r   doctrees         r#   r   zDocTestBuilder.write[  s|     	7#DH$566ND+,,---% 	, 	,Gh**733GMM'7++++	, 	,r%   rm   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   N)base)r   r   r   srcdirrsplit	Exceptiondoc2path)rj   rm   r   r   s       r#   get_filename_for_nodez$DocTestBuilder.get_filename_for_nodef  su    	=t{DHO<<(155a9HH 	= 	= 	=x((t(<<HHH	=s   := &A&%A&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   rG   rm   s    r#   get_line_numberzDocTestBuilder.get_line_numberp  sD    
 t}T[->B??? 	
 49 	!9q= tr%   c                     d|vrdS |d         }i }| j         j        rt          | j         j        |           t          ||          }| j         j        rt          | j         j        |           |S )NrP   F)r_   doctest_global_setupexecevaldoctest_global_cleanup)rj   rm   	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           
      d   i }g }t          d| j                  | _        t          d| j                  | _        t          d| j                  | _        | j        j        | j        _        | j        j        | j        _        | j        j        rdt          dt          fd}ndt          dt          f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 |                     d|ddt7          |          z  d           |                                D ]}|                     |           | j                            | j        d          \  }}| xj        |z  c_        | xj        |z  c_        | j        j         rD| j                            | j        d          \  }}| xj!        |z  c_!        | xj"        |z  c_"        | j        j         rF| j                            | j        d          \  }}| xj#        |z  c_#        | xj$        |z  c_$        d S d S )NF)r   optionflagsrm   r!   c                     t          | t          j        t          j        f          rd| v pt          | t          j                  S Nr9   )
isinstancer   rZ   r[   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   rZ   r[   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:%sr9   r+   rE   )r   r   rf   rE   r:   r8   *r.   r   )r   rf   T)r   r/   z
Document: z
-----------r*   )r   )%r   r   setup_runnertest_runnercleanup_runner_fakeoutr_   doctest_test_doctest_blocksr   r   findallr  astextr  r  r   re   r   getr   r   r   r   valuesr  r  r   r   
test_groupr   r   r   triesr   r   r   r   )rj   r   r  r:   add_to_all_groupsr  rm   r   r   line_numberrk   node_groups	groupnamer   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^FT&\\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<'$qB B BD 3 3tT2222;- 	%DK>)DD D DD % %t$$$$ 	F			77C#g,,...0 	1 	1 	1]]__ 	# 	#EOOE""""(2249e2LLuu$E!! 	&+55di5NNLE55(%$ 	(.88AE 9 G GLE5!!U*!!%'		( 	(r%   rk   rU   r   flagsdont_inheritc                 2    t          ||| j        ||          S r   )r   r   )rj   rk   rU   r   r9  r:  s         r#   r   zDocTestBuilder.compile  s    tT49e\BBBr%   r   c           	          i dt           dt          t                   dt           dt          f 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runner	testcodeswhatr!   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,   )rf   Tz (z code)r   r  Fr   clear_globs)r+   Examplerk   rf   r   DocTestrU   r   globsfailuresr   rt   r   )r=  r>  r?  r   rA   r   sim_doctestold_fr   nsrj   s           r#   run_setup_cleanupz4DocTestBuilder.test_group.<locals>.run_setup_cleanup  s    H% ) )!/(-HOTTT(((( t!/(B<AJJJ*M*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_msgrf   rE   r  FrA  r   )$r   r
   r   r   r(  r   r   r   parserget_doctestrk   rU   r   rf   r  r   re   r   r   rE   copyr   r   r+   DONT_ACCEPT_BLANKLINE_EXCEPTION_REr   r   rC  rD  rE  r)  rt   r   r*  r   )rj   r   rJ  rk   r;   r   new_optoutputrE   r   rM  rI  s   ``         @r#   r1  zDocTestBuilder.test_group  s   	c 	d8n 	C 	TX 	 	 	 	 	 	 	 	( ! !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B11AD
D)r!   Nr   )r   )ru   rv   rw   rx   rU   r   epilogr   rL   r   r   r   r   r   r   r	   r   r   r   r  staticmethodr   r  r   r   r  r  r   r   r   r1  r2   r%   r#   r   r     s^         DR 4 5 5F4 4 4 4:! ! ! ! ! !!c !d ! ! ! ! c  s    #3s8 # # # #$ $ $ $, %	, 	,HSM 	,Xc] 	,	,)-	, 	, 	, 	,$       d s    \G     L( L(d L(t L( L( L( L(\CC Cs C# Cc CQU CZ] C C C CEI	 EId EI EI EI EI EI EIr%   r   r   r   c                    |                      dt                     |                      dt                     |                      dt                     |                      dt                     |                      dt
                     |                     t                     |                     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+   rA   rC   r   Fr,  r8   r  r,   r  r   T)r    parallel_read_safe)add_directiver~   r   r   r   r   add_builderr   add_config_valuer+   DONT_ACCEPT_TRUE_FOR_1ELLIPSISIGNORE_EXCEPTION_DETAILsphinx__display_version__)r   s    r#   r   r   &  s1   k#5666m%9:::i!1222j"3444l$7888OON###U3336	5III/U;;;12u===&)99G<[[   1NNNr%   )Jrx   r+   rerh   r   ior   osr   typingr   r   r   r   r	   r
   r   r   r   r   docutilsr   docutils.nodesr   r   r   docutils.parsers.rstr   packaging.specifiersr   r   packaging.versionr   r_  sphinx.buildersr   sphinx.localer   sphinx.utilr   sphinx.util.consoler   sphinx.util.docutilsr   sphinx.util.osutilr   sphinx.util.typingr   sphinx.applicationr   	getLoggerru   r   r   	MULTILINErV   rX   rL   r   r$   r'   r~   r   r   r   r   DocTestParserrN  r   r   DocTestRunnerr   r   r   r2   r%   r#   <module>rv     se   
  				 



                                           5 5 5 5 5 5 5 5 5 5 + + + + + + ? ? ? ? ? ? ? ? % % % % % %  # # # # # #             $ $ $ $ $ $ 0 0 0 0 0 0 & & & & & & ) ) ) ) ) ) *)))))) 
	8	$	$rz,bl;;
-r|<<2S 23 24 2 2 2 2(T T T T TO T T Tn           =       }              -    
		 	 
= = = = = = = =<L L L L L L L LF F F F F'/ F F F@SI SI SI SI SIW SI SI SIlOx ODcN O O O O O Or%   