ó
öÀ„\c           @@  s  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 m Z d d l m Z d d	 l m Z m Z m Z m Z m Z d d l 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# m$ Z$ d d l% m& Z& d d l' m( Z( m) Z) e* r·d d l+ m, Z, m- Z- m. Z. m/ Z/ m0 Z0 m1 Z1 m2 Z2 m3 Z3 m4 Z4 m5 Z5 d d l6 m7 Z7 n  e  j8 e9 ƒ Z: e j; d e j< ƒ Z= e j; d e j< ƒ Z> e rd „  Z? n	 d „  Z? d „  Z@ d e$ f d „  ƒ  YZA d eA f d „  ƒ  YZB d eA f d „  ƒ  YZC d eA f d „  ƒ  YZD d  eA f d! „  ƒ  YZE d" eA f d# „  ƒ  YZF e jG ƒ  ZH d$ eI f d% „  ƒ  YZJ d& eI f d' „  ƒ  YZK d( e jL f d) „  ƒ  YZM d* e f d+ „  ƒ  YZN d, „  ZO d S(-   sý   
    sphinx.ext.doctest
    ~~~~~~~~~~~~~~~~~~

    Mimic doctest by automatically executing code snippets and checking
    their results.

    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
i    (   t   absolute_importN(   t   path(   t   nodes(   t
   directives(   t   SpecifierSett   InvalidSpecifier(   t   Version(   t
   itervaluest   StringIOt   binary_typet	   text_typet   PY2(   t   Builder(   t   __(   t   force_decodet   logging(   t   bold(   t   SphinxDirective(   t   set_source_info(   t   fs_encodingt   relpath(
   t   Anyt   Callablet   Dictt   IOt   Iterablet   Listt   Optionalt   Sequencet   Sett   Tuple(   t   Sphinxs   ^\s*<BLANKLINE>s   #\s*doctest:.+$c         C@  sM   t  |  t ƒ rI |  j | ƒ }  |  j t j ƒ rI |  t t j ƒ }  qI n  |  S(   N(   t
   isinstanceR
   t   encodet
   startswitht   codecst   BOM_UTF8t   len(   t   textt   encoding(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   doctest_encode/   s
    c         C@  s   |  S(   N(    (   R&   R'   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR(   7   s    c         C@  s   t  | ƒ t |  ƒ k S(   sa  Check `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
    (   R   R   (   t   spect   version(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   is_allowed_version<   s    t   TestDirectivec           B@  s/   e  Z d  Z e Z d Z d Z e Z d „  Z RS(   s4   
    Base class for doctest-related directives.
    i    i   c         C@  sš  d j  |  j ƒ } d  } |  j d k r„ d | k rN | } t j d | ƒ } n  t j | ƒ r„ | sl | } n  t j d | ƒ } q„ n  t j	 } |  j d" k s« d |  j
 k r· t j } n  |  j rò g  |  j d j d	 ƒ D] } | j ƒ  ^ q× } n	 d
 g } | | | d |  j d | ƒ} t |  | ƒ | d  k	 r?| | d <n  |  j d k r[d | d <n8 |  j d k rwd | d <n |  j d k r“d | d <n  i  | d <|  j d# k r¥d |  j
 k r¥|  j
 d j d	 d ƒ j ƒ  } xÈ | D]½ } | d | d }	 }
 |	 d k r7|  j j j j t d ƒ | d |  j ƒqán  |
 t j k ru|  j j j j t d ƒ |
 d |  j ƒqán  t j | d } | d d k | d | <qáWn  |  j d k rpd |  j
 k rpym |  j
 d } d j  g  t j d  D] } t | ƒ ^ qçƒ } t | | ƒ s/t j d } t | d | <n  Wqpt k
 rl|  j j j j t d  ƒ | d |  j ƒqpXn  d! |  j
 k r“|  j
 d! | d! <n  | g S($   Ns   
t   doctests   <BLANKLINE>t    t	   testsetupt   testcleanupt   hidei    t   ,t   defaultt   testnodetypet   groupst   testt   pycont   languaget   testcodet   pythont
   testoutputt   nonet   optionst    i   s   +-s"   missing '+' or '-' in '%s' option.t   lines   '%s' is not a valid option.t   +t	   pyversiont   .i   t   SKIPs$   '%s' is not a valid pyversion optiont   skipif(   R/   R0   (   R-   R;   (   t   joint   contentt   Nonet   namet   blankline_ret   subt   doctestopt_ret   searchR   t   literal_blockR=   t   commentt	   argumentst   splitt   stripR   t   replacet   statet   documentt   reportert   warningR   t   linenoR-   t   OPTIONFLAGS_BY_NAMEt   syst   version_infot   strR+   t   TrueR   (   t   selft   codeR6   t   nodetypet   xR5   t   nodet   option_stringst   optiont   prefixt   option_namet   flagR)   t   vt   python_version(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   run[   sr    			2	


/(	   t   __name__t
   __module__t   __doc__R\   t   has_contentt   required_argumentst   optional_argumentst   final_argument_whitespaceRi   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR,   Q   s   t   TestsetupDirectivec           B@  s   e  Z i e j d  6Z RS(   RD   (   Rj   Rk   R   t   unchanged_requiredt   option_spec(    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRq   Ÿ   s   t   TestcleanupDirectivec           B@  s   e  Z i e j d  6Z RS(   RD   (   Rj   Rk   R   Rr   Rs   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRt   £   s   t   DoctestDirectivec           B@  s6   e  Z i e j d  6e j d 6e j d 6e j d 6Z RS(   R1   R=   RA   RD   (   Rj   Rk   R   Rf   t	   unchangedRr   Rs   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRu   §   s
   


t   TestcodeDirectivec           B@  s,   e  Z i e j d  6e j d 6e j d 6Z RS(   R1   RA   RD   (   Rj   Rk   R   Rf   Rr   Rs   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRw   °   s   

t   TestoutputDirectivec           B@  s6   e  Z i e j d  6e j d 6e j d 6e j d 6Z RS(   R1   R=   RA   RD   (   Rj   Rk   R   Rf   Rv   Rr   Rs   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRx   ¸   s
   


t	   TestGroupc           B@  s&   e  Z d  „  Z e d „ Z d „  Z RS(   c         C@  s(   | |  _  g  |  _ g  |  _ g  |  _ d  S(   N(   RH   t   setupt   testst   cleanup(   R]   RH   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   __init__Ç   s    			c         C@  s  | j  d k r> | r+ |  j j d | ƒ q|  j j | ƒ nÉ | j  d k r` |  j j | ƒ n§ | j  d k r… |  j j | g ƒ n‚ | j  d k r­ |  j j | d  g ƒ nZ | j  d k rõ |  j rt |  j d ƒ d k r| |  j d d	 <qn t t	 d
 ƒ ƒ ‚ d  S(   NR/   i    R0   R-   R9   R;   iÿÿÿÿi   i   s   invalid TestCode type(
   t   typeRz   t   insertt   appendR|   R{   RG   R%   t   RuntimeErrorR   (   R]   R^   t   prepend(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   add_codeÎ   s    "c         C@  s    d |  j  |  j |  j |  j f S(   Ns2   TestGroup(name=%r, setup=%r, cleanup=%r, tests=%r)(   RH   Rz   R|   R{   (   R]   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   __repr__á   s    (   Rj   Rk   R}   t   FalseRƒ   R„   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRy   Æ   s   	t   TestCodec           B@  s   e  Z d d  „ Z d „  Z RS(   c         C@  s7   | |  _  | |  _ | |  _ | |  _ | p- i  |  _ d  S(   N(   R^   R~   t   filenameRW   R=   (   R]   R^   R~   R‡   RW   R=   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR}   è   s
    				c         C@  s&   d |  j  |  j |  j |  j |  j f S(   Ns4   TestCode(%r, %r, filename=%r, lineno=%r, options=%r)(   R^   R~   R‡   RW   R=   (   R]   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR„   ð   s    N(   Rj   Rk   RG   R}   R„   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR†   ç   s   t   SphinxDocTestRunnerc           B@  s    e  Z d d  „ Z d d „ Z RS(   c         C@  sU   t  ƒ  } t j } | t _ z t j j |  | ƒ } Wd  | t _ X| | j ƒ  ƒ | S(   N(   R   RY   t   stdoutR-   t   DocTestRunnert	   summarizet   getvalue(   R]   t   outt   verboset	   string_iot
   old_stdoutt   res(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR‹   ÷   s    			
c         C@  s   |  j  j | ƒ } | r} | j d ƒ |  j j k r} y# |  j j t | j d ƒ ƒ } Wn t k
 ri q} X| j j	 t
 ƒ Sn  |  j | | ƒ S(   NRH   t
   examplenum(   t%   _DocTestRunner__LINECACHE_FILENAME_REt   matcht   groupR6   RH   t   examplest   intt
   IndexErrort   sourcet
   splitlinesR\   t   save_linecache_getlines(   R]   R‡   t   module_globalst   mt   example(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt*   _DocTestRunner__patched_linecache_getlines  s    !#N(   Rj   Rk   RG   R‹   RŸ   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRˆ   ö   s   t   DocTestBuilderc           B@  s¡   e  Z d  Z d Z e d ƒ Z d „  Z d „  Z d „  Z d d „ Z
 d „  Z d „  Z d	 d
 „ Z d „  Z e d „  ƒ Z d „  Z d „  Z d „  Z d „  Z RS(   s2   
    Runs test snippets in the documentation.
    R-   sZ   Testing of doctests in the sources finished, look at the results in %(outdir)s/output.txt.c         C@  sÚ   |  j  j |  _ |  j t _ |  j  j t j d d +d |  _ d |  _	 d |  _
 d |  _ d |  _ d |  _ d |  _ t j d ƒ } d  |  _ t j t j |  j d ƒ d d d ƒ|  _ |  j j d | d	 t | ƒ f ƒ d  S(
   Ni    t   singles   %Y-%m-%d %H:%M:%Ss
   output.txtt   wR'   s   utf-8sJ   Results of doctest builder run on %s
==================================%s
t   =(   t   configt   doctest_default_flagst   optt   compileR-   t   doctest_pathRY   R   R~   t   total_failurest   total_triest   setup_failurest   setup_triest   cleanup_failurest   cleanup_triest   timet   strftimeRG   t   outfileR#   t   openRE   t   outdirt   writeR%   (   R]   t   date(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   init  s     								c         C@  s'   t  j | d t ƒ|  j j | ƒ d  S(   Nt   nonl(   t   loggert   infoR\   R±   R´   (   R]   R&   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   _out?  s    c         C@  sp   |  j  j s |  j  j r( t j | ƒ n t j | d t ƒt | t ƒ r\ t	 | d  ƒ } n  |  j j | ƒ d  S(   NR·   (   t   appt   quiett   warningiserrorR¸   RV   R¹   R\   R    R	   R   RG   R±   R´   (   R]   R&   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt	   _warn_outD  s    c         C@  s   d S(   NR.   (    (   R]   t   docnamet   typ(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   get_target_uriN  s    c         C@  s
   |  j  j S(   N(   t   envt
   found_docs(   R]   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   get_outdated_docsR  s    c      	   C@  s£   d „  } |  j  | |  j  ƒ |  j | |  j ƒ |  j | |  j ƒ |  j | |  j ƒ f } |  j d | ƒ |  j j ƒ  |  j s |  j s |  j rŸ d |  j _ n  d  S(   Nc         S@  s   |  d k r d p d S(   Ni   t   sR.   (    (   Rg   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRÅ   Y  s    s}   
Doctest summary
===============
%5d test%s
%5d failure%s in tests
%5d failure%s in setup code
%5d failure%s in cleanup code
i   (	   Rª   R©   R«   R­   Rº   R±   t   closeR»   t
   statuscode(   R]   RÅ   t   repl(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   finishV  s    	t   updatec         C@  sk   | d  k r! t |  j j ƒ } n  t j t d ƒ ƒ x0 | D]( } |  j j | ƒ } |  j | | ƒ q; Wd  S(   Ns   running tests...(	   RG   t   sortedRÂ   t   all_docsR¸   R¹   R   t   get_doctreet   test_doc(   R]   t   build_docnamest   updated_docnamest   methodR¿   t   doctree(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR´   m  s    c         C@  sr   y/ t  | j |  j j ƒ j d d d ƒd } Wn) t k
 rZ |  j j | d d ƒ} n Xt rn | j	 t
 ƒ S| S(   ss   Try to get the file which actually contains the doctest, not the
        filename of the document it's included in.s   :docstring of t   maxspliti   i    t   baseN(   R   R™   RÂ   t   srcdirt   rsplitt	   Exceptiont   doc2pathRG   R   R!   R   (   R]   Ra   R¿   R‡   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   get_filename_for_nodex  s    c         C@  s@   d t  j |  j p d ƒ k r" d S|  j d k	 r< |  j d Sd S(   s0   Get the real line number or admit we don't know.s   :docstring of R.   i   N(   R   t   basenameR™   RG   R?   (   Ra   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   get_line_number…  s
    c         B@  sq   d | k r e  S| d } i  } |  j j r= |  j j | Un  e | | ƒ } |  j j ri |  j j | Un  | Sd  S(   NRD   (   R…   R¤   t   doctest_global_setupt   evalt   doctest_global_cleanup(   R]   Ra   t	   conditiont   contextt   should_skip(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   skipped–  s    
c         C@  s  i  } g  } t  d t d |  j ƒ |  _ t  d t d |  j ƒ |  _ t  d t d |  j ƒ |  _ |  j j |  j _ |  j j |  j _ |  j j r™ d „  } n	 d „  } xN| j	 | ƒ D]=} |  j
 | ƒ rÍ q² n  d | k rã | d n	 | j ƒ  } |  j | | ƒ } |  j | ƒ }	 | sAt j t d ƒ | j d d ƒ | |	 ƒ n  t | d	 | j d d ƒ d
 | d |	 d | j d ƒ ƒ}
 | j d d g ƒ } d | k r®| j |
 ƒ q² n  x> | D]6 } | | k rÚt | ƒ | | <n  | | j |
 ƒ qµWq² Wx2 | D]* }
 x! t | ƒ D] } | j |
 ƒ qWqúW|  j j r‚t |  j j d d
 d  d d ƒ}
 x* t | ƒ D] } | j |
 d t ƒqbWn  |  j j rÖt |  j j d d
 d  d d ƒ}
 x$ t | ƒ D] } | j |
 ƒ q¼Wn  | sàd  S|  j d | d t | ƒ f ƒ x! t | ƒ D] } |  j | ƒ qW|  j j |  j d t ƒ\ } } |  j | 7_ |  j  | 7_  |  j j! r²|  j j |  j d t ƒ\ } } |  j" | 7_" |  j# | 7_# n  |  j j! r |  j j |  j d t ƒ\ } } |  j$ | 7_$ |  j% | 7_% n  d  S(   NRŽ   t   optionflagsc         S@  s7   t  |  t j t j f ƒ r' d |  k p6 t  |  t j ƒ S(   NR4   (   R    R   RM   RN   t   doctest_block(   Ra   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRß   ³  s    c         S@  s%   t  |  t j t j f ƒ o$ d |  k S(   NR4   (   R    R   RM   RN   (   Ra   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRß   ¹  s    R6   s#   no code/output in %s block at %s:%sR4   R-   R~   R‡   RW   R=   R5   R3   t   *R/   i    R‚   R0   s   
Document: %s
----------%s
t   -(&   Rˆ   R…   R¦   t   setup_runnert   test_runnert   cleanup_runnert   _fakeoutR¤   t   doctest_test_doctest_blockst   traverseRâ   t   astextRÙ   RÛ   R¸   RV   R   t   getR†   R€   Ry   Rƒ   R   RÜ   RG   R\   RÞ   Rº   R%   t
   test_groupR‹   R«   R¬   t   triesR©   Rª   R­   R®   (   R]   R¿   RÒ   R5   t   add_to_all_groupsRß   Ra   R™   R‡   t   line_numberR^   t   node_groupst	   groupnameR•   t   res_ft   res_t(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRÎ   ¤  s‚    	"	!!c         C@  s   t  | | |  j | | ƒ S(   N(   R§   R~   (   R]   R^   RH   R~   t   flagst   dont_inherit(    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR§   õ  s    c      
   @  s‡  i  ‰ ‡  ‡ ‡ f d †  } | ˆ j  ˆ  j d ƒ s7 d  Sx3ˆ  j D](} t | ƒ d k rKyI t j t | d j ˆ j j	 j
 ƒ i  ˆ  j | d j | d j ƒ } WnK t k
 rï t j t d ƒ | d j d | d j | d j f ƒqA n X| j sÿ qA n  x= | j D]2 } | d j j ƒ  } | j | j ƒ | | _ q	Wd ˆ _ nö | d rb| d j ped } | d r| d j p‚i  } t | t j <t j j | ƒ }	 |	 r¼|	 j d	 ƒ }
 n d  }
 t j t | d j ˆ j j	 j
 ƒ | d
 |
 d | d j d | ƒ} t j | g i  ˆ  j | d j | d j d  ƒ } d ˆ _ ˆ | _  ˆ j! j" | d ˆ j# d t$ ƒqA W| ˆ j% ˆ  j& d ƒ d  S(   Nc         @  sØ   g  } xE | D]= } | j  t j t | j ˆ j j j ƒ d d | j ƒƒ q W| sX t	 St j
 | i  d ˆ  j | f | d j d d  ƒ } ˆ | _ |  j } d ˆ _ |  j | d ˆ j d t ƒ|  j | k rÔ t St	 S(   NR.   RW   s   %s (%s code)i    t   execR   t   clear_globs(   R€   R-   t   ExampleR(   R^   RÂ   R¤   t   source_encodingRW   R\   t   DocTestRH   R‡   RG   t   globst   failuresR~   Ri   R¾   R…   (   t   runnert	   testcodest   whatR–   R9   t   sim_doctestt   old_f(   R•   t   nsR]   (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   run_setup_cleanupý  s"    			Rz   i   i    s!   ignoring invalid doctest code: %rt   locationR¡   R.   t   msgt   exc_msgRW   R=   Rù   R   Rú   R|   ('   Rç   Rz   R{   R%   t   parsert   get_doctestR(   R^   RÂ   R¤   Rü   RH   R‡   RW   R×   R¸   RV   R   R–   R=   t   copyRÊ   R~   R\   R-   t   DONT_ACCEPT_BLANKLINEt   _EXCEPTION_RER”   R•   RG   Rû   Rý   Rþ   Rè   Ri   R¾   R…   Ré   R|   (   R]   R•   R  R^   R6   Rž   t   new_optt   outputR=   R   R	  (    (   R•   R  R]   s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRï   ù  sN    $	"			#N(   Rj   Rk   Rl   RH   R   t   epilogR¶   Rº   R¾   RG   RÁ   RÄ   RÉ   R´   RÙ   t   staticmethodRÛ   Râ   RÎ   R§   Rï   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyR      s    	 		
					Q	c         C@  sâ   |  j  d t ƒ |  j  d t ƒ |  j  d t ƒ |  j  d t ƒ |  j  d t ƒ |  j t ƒ |  j d g  t	 ƒ |  j d d t	 ƒ |  j d	 d
 t	 ƒ |  j d d
 t	 ƒ |  j d t
 j t
 j Bt
 j Bt	 ƒ i t j d 6t d 6S(   NR/   R0   R-   R9   R;   R¨   Rë   R3   RÜ   R.   RÞ   R¥   R*   t   parallel_read_safe(   t   add_directiveRq   Rt   Ru   Rw   Rx   t   add_builderR    t   add_config_valueR…   R-   t   DONT_ACCEPT_TRUE_FOR_1t   ELLIPSISt   IGNORE_EXCEPTION_DETAILt   sphinxt   __display_version__R\   (   R»   (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyRz   H  s    (P   Rl   t
   __future__R    R#   R-   t   reRY   R¯   t   osR   t   docutilsR   t   docutils.parsers.rstR   t   packaging.specifiersR   R   t   packaging.versionR   t   sixR   R   R	   R
   R   R  t   sphinx.buildersR   t   sphinx.localeR   t   sphinx.utilR   R   t   sphinx.util.consoleR   t   sphinx.util.docutilsR   t   sphinx.util.nodesR   t   sphinx.util.osutilR   R   R…   t   typingR   R   R   R   R   R   R   R   R   R   t   sphinx.applicationR   t	   getLoggerRj   R¸   R§   t	   MULTILINERI   RK   R(   R+   R,   Rq   Rt   Ru   Rw   Rx   t   DocTestParserR
  t   objectRy   R†   RŠ   Rˆ   R    Rz   (    (    (    s1   lib/python2.7/site-packages/sphinx/ext/doctest.pyt   <module>   sV   (F		N		!!ÿ 2