o $a$Y@s dZddlZddlZddlZddlZddlmZddlmZddl m Z m Z m Z m Z mZmZmZmZmZmZddlmZddlmZmZmZddlmZdd lmZmZdd lm Z ddl!Z!dd l"m#Z#dd l$m%Z%dd l&m'Z'ddl(m)Z)ddl*m+Z+ddl,m-Z-ddl.m/Z/e rddl0m1Z1e'2e3Z4e5dej6Z7e5dej6Z8de9de9de:fddZ;Gddde+ZGd d!d!e<Z?Gd"d#d#e<Z@Gd$d%d%e<ZAeBZCGd&d'd'ZDGd(d)d)ZEGd*d+d+ejFZGGd,d-d-e#ZHd.d/de e9e ffd0d1ZIdS)2z sphinx.ext.doctest ~~~~~~~~~~~~~~~~~~ Mimic doctest by automatically executing code snippets and checking their results. :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. N)StringIO)path) TYPE_CHECKINGAnyCallableDictIterableListSequenceSetTupleType)nodes)ElementNode TextElement) directives)InvalidSpecifier SpecifierSet)Version)Builder)__)logging)bold)SphinxDirective)relpath) OptionSpec)Sphinxz^\s*z#\s*doctest:.+$specversionreturncCst|t|vS)aaCheck `spec` satisfies `version` or not. This obeys PEP-440 specifiers: https://www.python.org/dev/peps/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 )rr)rrr!4/usr/lib/python3/dist-packages/sphinx/ext/doctest.pyis_allowed_version.sr#c@s2eZdZdZdZdZdZdZdee fddZ dS) TestDirectivez4 Base class for doctest-related directives. Trr c Csd|j}d}|jdkr-d|vr|}td|}t|r-d|jvr-|s'|}td|}tj }|jdvs:d|jvr=tj }|j rNdd |j d  d D}nd g}||||j|d }| ||durg||d<|jdkr||jjdvrwd|d<n#d|d<n|jdkr|jjdvrd|d<nd|d<n |jdkrd|d<i|d<|jdvrd|jvr|jdd d }|D]I}|d |dd}} |dvr|jjjjtd||jdq| tjvr|jjjjtd| |jdqtj|dd} |d d k|d| <q|jdkrLd!|jvrLz'|jd!} d"d#d tjdd$D} t| | s1tjd%} d&|d| <WntyK|jjjjtd'| |jdYnwd(|jvrY|jd(|d(<d)|jvrfd&|d*<|gSd|jvrpd+|d*<|gS),N doctestz no-trim-doctest-flags) testsetup testcleanuphidecSsg|]}|qSr!)strip).0xr!r!r" ^z%TestDirective.run..r,default) testnodetypegroupstest)pypythonpyconlanguagepycon3testcoder8python3 testoutputnoneoptions)r'r> r%z+-z"missing '+' or '-' in '%s' option.)linez'%s' is not a valid option.+ pyversion.cSsg|]}t|qSr!)str)r.vr!r!r"r0r1SKIPTz$'%s' is not a valid pyversion optionskipiftrim-doctest-flags trim_flagsF)joincontentname blankline_resub doctestopt_researchr@r literal_blockcomment argumentssplitset_source_infoconfighighlight_languagereplacestatedocumentreporterwarningrlinenor'OPTIONFLAGS_BY_NAMEsys version_infor#r) selfcoder6nodetyper5nodeoption_stringsoptionprefix option_nameflagrpython_versionr!r!r"runLs                             zTestDirective.runN) __name__ __module__ __qualname____doc__ has_contentrequired_argumentsoptional_argumentsfinal_argument_whitespacer rrnr!r!r!r"r$Bsr$c@ eZdZUdejiZeed<dS)TestsetupDirectiverJ option_specNrorprqrunchanged_requiredryr__annotations__r!r!r!r"rx rxc@rw)TestcleanupDirectiverJryNrzr!r!r!r"r~r}r~c@4eZdZUejejejejejejdZee d<dS)DoctestDirectiver,r)r@rDrJrKryN rorprqrrl unchangedr{ryrr|r!r!r!r"r rc@s0eZdZUejejejejejdZeed<dS)TestcodeDirective)r,r)rDrJrKryN) rorprqrrlr{ryrr|r!r!r!r"rs rc@r)TestoutputDirectiverryNrr!r!r!r"rrrc@sDeZdZdeddfddZdddd eddfd d Zdefd d ZdS) TestGrouprOr NcCs||_g|_g|_g|_dSN)rOsetuptestscleanup)rdrOr!r!r"__init__s zTestGroup.__init__FreTestCodeprependcCs|jdkr|r|jd|dS|j|dS|jdkr%|j|dS|jdkr3|j|gdS|jdkrB|j|dgdS|jdkr`|jr\t|jddkr^||jdd <dSdSdSttd ) Nr*rr+r'r<r>r%zinvalid TestCode type) typerinsertappendrrlen RuntimeErrorr)rdrerr!r!r"add_codes      zTestGroup.add_codecCsd|j|j|j|jfS)Nz2TestGroup(name=%r, setup=%r, cleanup=%r, tests=%r))rOrrrrdr!r!r"__repr__szTestGroup.__repr__)F)rorprqrFrboolrrr!r!r!r"rsrc @s@eZdZ d dedededededdf dd Zdefd d ZdS) rNrerfilenamer`r@r cCs&||_||_||_||_|pi|_dSrrerrr`r@)rdrerrr`r@r!r!r"rs zTestCode.__init__cCsd|j|j|j|j|jfS)Nz4TestCode(%r, %r, filename=%r, lineno=%r, options=%r)rrr!r!r"rszTestCode.__repr__r)rorprqrFintrrrr!r!r!r"rs rc sNeZdZd dededeeefffdd Z d dede de fd d Z Z S) SphinxDocTestRunnerNoutverboser csBt}tj}|t_z t|}W|t_n|t_w|||Sr)rrbstdoutsuper summarizegetvalue)rdrr string_io old_stdoutres __class__r!r"rs zSphinxDocTestRunner.summarizermodule_globalscCsh|j|}|r.|d|jjkr.z |jjt|d}Wn ty'Ynw|j dS| ||S)NrO examplenumT) %_DocTestRunner__LINECACHE_FILENAME_REmatchgroupr6rOexamplesr IndexErrorsource splitlinessave_linecache_getlines)rdrrmexampler!r!r"*_DocTestRunner__patched_linecache_getliness    z>SphinxDocTestRunner._DocTestRunner__patched_linecache_getlinesr) rorprqrrr rrrFrr __classcell__r!r!rr"rs   rc @s,eZdZdZdZedZd/ddZdeddfd d Z deddfd d Z d0d ededefddZ de efddZ d/ddZ d1deedeededdfddZded edefddZededefddZdedefd d!Zd ed"eddfd#d$Zd%ed&ed'ed(ed)edef d*d+Zd,eddfd-d.ZdS)2DocTestBuilderz2 Runs test snippets in the documentation. r'zZTesting of doctests in the sources finished, look at the results in %(outdir)s/output.txt.r NcCs|jj|_|jt_|jjtjdd<d|_d|_ d|_ d|_ d|_ d|_ d|_td}tt|jdddd|_|jd|d t|fdS) Nrsinglez%Y-%m-%d %H:%M:%Sz output.txtwzutf-8)encodingzJResults of doctest builder run on %s ==================================%s =)rYdoctest_default_flagsoptcompiler' doctest_pathrbrrtotal_failures total_triessetup_failures setup_triescleanup_failures cleanup_triestimestrftimeopenrMoutdiroutfilewriter)rddater!r!r"inits   zDocTestBuilder.inittextcCstj|dd|j|dSNT)nonl)loggerinforrrdrr!r!r"_out;szDocTestBuilder._outcCs:|jjs|jjrt|ntj|dd|j|dSr)appquietwarningiserrorrr_rrrrr!r!r" _warn_out?s zDocTestBuilder._warn_outdocnametypcCsdS)Nr(r!)rdrrr!r!r"get_target_uriFszDocTestBuilder.get_target_uricCs|jjSr)env found_docsrr!r!r"get_outdated_docsIsz DocTestBuilder.get_outdated_docsc Csdtdtfdd}|j||j|j||j|j||j|j||jf}|d||j|js8|js8|jr>d|j _ dSdS)NrGr cSs|dkrdSdS)Nr%sr(r!)rGr!r!r"rNsz DocTestBuilder.finish..sz} Doctest summary =============== %5d test%s %5d failure%s in tests %5d failure%s in setup code %5d failure%s in cleanup code r%) rrFrrrrrrcloser statuscode)rdrreplr!r!r"finishLs      zDocTestBuilder.finishupdatebuild_docnamesupdated_docnamesmethodcCsH|dur t|jj}ttd|D]}|j|}|||qdS)Nzrunning tests...)sortedrall_docsrrr get_doctreetest_doc)rdrrrrdoctreer!r!r"ras  zDocTestBuilder.writergcCsJzt|j|jjjdddd}W|Sty$|jj|dd}Y|Sw)zsTry to get the file which actually contains the doctest, not the filename of the document it's included in.:docstring of r%)maxsplitrN)base)rrrsrcdirrsplit Exceptiondoc2path)rdrgrrr!r!r"get_filename_for_nodels z$DocTestBuilder.get_filename_for_nodecCs0dt|jpdvr dS|jdur|jdSdS)z0Get the real line number or admit we don't know.rr(Nr%)rbasenamerrBrgr!r!r"get_line_numbervs   zDocTestBuilder.get_line_numbercCsRd|vrdS|d}i}|jjrt|jj|t||}|jjr't|jj||S)NrJF)rYdoctest_global_setupexecevaldoctest_global_cleanup)rdrg conditioncontext should_skipr!r!r"skippeds zDocTestBuilder.skippedrc Csi}g}td|jd|_td|jd|_td|jd|_|jj|j_|jj|j_|jjr6dtdt fdd}n dtdt fdd}| |D]f}| |rLqDd|vrT|dn| }| ||}||} |ssttd |d d || t||d d || |d d } |ddg} d| vr|| qD| D]} | |vrt| || <|| | qqD|D]} |D]} | | qq|jjrt|jjdddd} |D] } | j| ddq|jjrt|jjdddd} |D]} | | q|sdS|d|dt|f|D]} || q|jj|jdd\}}|j|7_|j|7_|jj rG|jj|jdd\}}|j!|7_!|j"|7_"|jj rg|jj|jdd\}}|j#|7_#|j$|7_$dSdS)NF)r optionflagsrgr cSs&t|tjtjfr d|vpt|tjSNr4) isinstancerrTrU doctest_blockrr!r!r"rs  z*DocTestBuilder.test_doc..conditioncSst|tjtjfo d|vSr)rrrTrUrr!r!r"rsr6z#no code/output in %s block at %s:%sr4r'r@)rrr`r@r5r3*r*r)rr`T)rr+z Document: %s ----------%s -)r)%rr setup_runner test_runnercleanup_runner_fakeoutrYdoctest_test_doctest_blocksrrtraverserastextrrrr_rgetrrrrvaluesrrrr test_grouprrrtriesrrrr)rdrrr5add_to_all_groupsrrgrr line_numberre node_groups groupnamerres_fres_tr!r!r"rs                   zDocTestBuilder.test_docrerOrflags dont_inheritcCst|||j||Sr)rr)rdrerOrrrr!r!r"rszDocTestBuilder.compilerc sidtdttdtdtffdd }|jjdsdSjD]}t|dkr|zt |d j ij |d j |d j }Wnty]tjtd |d j |d j |d j fd Yq"w|jsbq"|jD]}|d j}||j||_qed _nP|dr|dj nd }|dr|djni}d|tj<tj|} | r| d} nd} tj|d j || |d j |d}t|gij |d j |d j d}d_|_jj |j!ddq"|j"j#ddS)Nrunner testcodeswhatr csg}|D]}tj|jd|jd}||q|sdSt|idj|f|djdd}|_|j }d_ |j |j dd|j |krEdSdS) Nr()r`Tz %s (%s code)rrFr clear_globs) r'Examplerer`rDocTestrOrglobsfailuresrrnr)rrrrr<r sim_doctestold_frnsrdr!r"run_setup_cleanups"    z4DocTestBuilder.test_group..run_setup_cleanuprr%rz!ignoring invalid doctest code: %r)locationrr(Tmsg)exc_msgr`r@rFrr)$rr rrrrrrparser get_doctestrerOrr`rrr_rrr@copyrrr'DONT_ACCEPT_BLANKLINE _EXCEPTION_RErrrrr rrnrrr) rdrr&rer6rnew_optoutputr@rr)r!r$r"rsP&         zDocTestBuilder.test_group)r Nr)r)rorprqrrrOrepilogrrFrrrr rrrr rrr staticmethodrrrrrrrrrrr!r!r!r"rs.      "NrrrcCs|dt|dt|dt|dt|dt|t|dgd|dd d|d d d|d d d|d t j t j Bt j Bdt jddS)Nr*r+r'r<r>rFr r3rr(rrT)rparallel_read_safe) add_directiverxr~rrr add_builderradd_config_valuer'DONT_ACCEPT_TRUE_FOR_1ELLIPSISIGNORE_EXCEPTION_DETAILsphinx__display_version__)rr!r!r"r,s       r)Jrrr'rerbriorosrtypingrrrrrr r r r r docutilsrdocutils.nodesrrrdocutils.parsers.rstrpackaging.specifiersrrpackaging.versionrr:sphinx.buildersr sphinx.localer sphinx.utilrsphinx.util.consolersphinx.util.docutilsrsphinx.util.osutilrsphinx.util.typingrsphinx.applicationr getLoggerrorr MULTILINErPrRrFrr#r$rxr~rrr DocTestParserr*rr DocTestRunnerrrrr!r!r!r"sR   0            W