-PhCdZddlZddlZddlZddlZddlZddlmZddlm Z ddl m Z ddl Z ddlmZddlmZdd lmZdd lmZmZd Zd ZGd dejZdZddZddZdZedzZ ddZ dZ!dZ"dS)z^Backreferences Generator. Parses example file code in order to keep track of used functions. N) defaultdict)escape)Path)ExtensionError) DummyClass)_find_image_ext)_W_KW _replace_md5zT .. raw:: html
.. thumbnail-parent-div-open z; .. thumbnail-parent-div-close .. raw:: html
cDeZdZdZd fd Zd dZdZdZdZd Z xZ S) NameFinderzwFinds the longest form of variable names and their imports in code. Only retains names from imported modules. Ncti|_|pi|_t |_dSN)super__init__imported_namesglobal_variablessetaccessed_names)selfr __class__s ]/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/sphinx_gallery/backreferences.pyrzNameFinder.__init__0s@   0 6B!eecZ|jD]"}|jp|j}||jz|j|<#dS)z0For 'import' add node names to `imported_names`.N)namesasnamenamer)rnodeprefixalias local_names r visit_ImportzNameFinder.visit_Import6sFZ B BE3J.4uz.AD  + + B BrcB|||jdzdS)zIFor 'from import' add node names to `imported_names`, incl module prefix..N)r#modulerrs rvisit_ImportFromzNameFinder.visit_ImportFrom<s% $ c 122222rcD|j|jdS)z Add node id to `accessed_names`.N)raddidr's r visit_NamezNameFinder.visit_Name@s! (((((rcg}t|tjr;||j|j}t|tj;t|tjrV||j|j d t|dS| |dS)z > > > > JJt     rc t}|jD]}|d}tt |D]}d|d|dz}|t |d}||jvr|j|}dg} }|r|dddD]x} |} t| j| d} t| tr | }d| g} }nA t|| }n#t$rYn"wxYwtj |r | }d| g} }ny~tj|} | s|rl| r|n|jg}d}|t |krJ||jD]$}||vr|t ur||%|dz }|t |kJn|jg}|D]}tj|}||jd}|j}tt |ddD]@}d|d||gz| z}||||| dfAtt |D]p}d|d|dz}|t |d}||jvr.|j||z}dx} }||||| dfq|S)aMap names used in code, using AST nodes, to their fully qualified names. Returns ------- options : List[Tuple[str]] List of tuples, each tuple containing the following information about an `accessed_name`: accessed name : str, fully qualified name : str if it is a class attribute (i.e., property or method) : bool if it is a class : bool if it is an explicit backreference : bool (always false here) r%NrFTr)listrsplitrangelenr5rgetattrrr.property Exceptioninspectismethodisclass __bases__objectr1 getmodule__name__ __qualname__r)roptionsrlocal_name_split split_levelr" remainderobj class_attrmethodlevellast_objpropis_classclassesoffsetbaseccr& class_namedepth full_names r get_mappingzNameFinder.get_mappingSs&&'D SD SD#zz# $S)9%:%:;;7 "7 "  XX&67Hq7H&IJJ  Z!2!23 !666/ ;C).J &%.qrr]%8%8%=%=&&E'*H#*8+=ud#K#KD)$99&&.59E7F % &&-c5&9&9#,&&& %&&/44&&.59E7F %&"&s33H 2: 2*2#E33 "F!"$s7||33(/(A99#'w#6#64v;M;M$+NN4$8$8$8"aKF %s7||33$'=/% " "!(!22!6!6!-%+_%:%:3%?%?F)+J*/s6{{Ar)B)B"",/HH$*6E6Nj\$AF$J-"-" !(%)9j(E$R!"!"!"!" %S)9%:%:;; S S  XX&67Hq7H&IJJ  Z!2!23 !444 $ 3J ?) KI,11HzNND)Z5#QRRR  Ss7D D D rr) rI __module__rJ__doc__rr#r(r,r9r] __classcell__)rs@rr r *s $$$$$$ BBBB 333)))   UUUUUUUrr cRd|vr|d\}}nd} ttj||}|t||n#tt f$rYdSwxYw|d}|}t t|dz ddD]}d|d|} |ttj||usJE#ttt f$r$d|d|dz}YnwxYw|S)z&Get the shortest possible module name.r%Nrrr;) r=r@sysmodulesAttributeErrorKeyErrorr>r?r5AssertionError) module_nameobj_namer2real_objparts short_nameis r_get_short_module_namernsW h!,,$$ 3;{3X>>   Hd # # # H %tt   c " "EJ 3u::>1b ) )  XXeBQBi((  ws{:'>IIIIIII9    % 1q5 "233J EE   s#2AA)(A)$C))7D$#D$rcRd}tjd|d|rdnd}d|d|dS) z/Make regex to find reference to python objects.zfunc|meth|attr|obj|classz (?:py:)?()z|[^:]?rz(?::(?:z):z()(?!``)`~?[^!]*?`]+)>?(?!``)`)re fullmatch) default_rolerolesdef_role_regexs r_make_ref_regexrvsY 'EL!5U!5!5!5|DDL"  35 3 3N 3 3 3rc|dkr3dd|D}tj|}t|}|||t |}dd|D}|dtj ||Dt}|D]\} } } } } | |vrt || <| dd| z}t|dkr d |d f}nAt|d kr*| sJ|d d|ddf}n| rJ|\}}t||}t|||p|| | }|| ||S) aBuild a codeobj summary by identifying and resolving used names. Parameters ---------- script_blocks : list (label, content, line_number) List where each element is a tuple with the label ('text' or 'code'), the corresponding content string of block and the leading line number. ref_regex : str Regex to find references to python objects. example_globals: Optional[Dict[str, Any]] Global variables for examples. Default=None node : ast.Module or str The parsed node. Default="". Returns ------- example_code_obj : Dict[str, Any] Dict with information about all code object references found in an example. Dict contains the following keys: - example_code_obj['name'] : function or class name (str) - example_code_obj['module'] : module name (str) - example_code_obj['module_short'] : shortened module name (str) - example_code_obj['is_class'] : whether object is class (bool) - example_code_obj['is_explicit'] : whether object is an explicit backreference (referred to by sphinx markup) (bool) r c3:K|]}|jdk |jVdS)codeNtypecontent.0blocks r z!identify_names..s1WW%*PVBVBVemBVBVBVBVWWrNc3:K|]}|jdk |jVdS)textNr{r~s rrz!identify_names..s0VVuvAUAUU]AUAUAUAUVVrc3$K|] }||dddfV dS)FTN)rxs rrz!identify_names..s-QQ!Qud+QQQQQQrr%rbuiltinsr)rr& module_shortrU is_explicit)r5r/parser r7r<r]extendrqfindalldictrsplitr?rnr1) script_blocks ref_regexrrcfinderrrexample_code_objrr\ class_likerUrsplitsr& attributercobjs ridentify_namesrs: rzz IIWWWWW W Wy|| ( ) )F  T ##%% & &E 99VV VVV V VD LLQQRZ 45P5PQQQQQQvv?D,,:iX{ ' ' '%)VV T "!!#q:~66 v;;!   &),FF [[A     Qi&*!5!56FF! ! ! !" .fi@@ %/#     %%d++++ rz .. raw:: html
.. only:: html .. image:: /{thumbnail} :alt: :ref:`sphx_glr_{ref_name}` .. raw:: html
{title}
z3 .. only:: not html * :ref:`sphx_glr_{ref_name}` FTc t|}ttj|ddd|jd\}}|r1tj|std|tj||}tj||} | tj d}tj| | tj d} |rtnt} | t|||| S) aGenerate reST to place a thumbnail in a gallery. Parameters ---------- target_dir : str Absolute path to output directory, where thumbnails are saved. src_dir : str Absolute path to build source directory. fname : str Filename of example file. intro : str Introductory docstring of example, to show in tooltip title: str Title of example. is_backref : bool Whether the thumbnail is for a html backreference/recommendation file. If not a bullet list of the example is added for non-html documentation builds. check : bool Whether to check if the thumbnail image file exists. Returns ------- thumbnail : str reST for a thumbnail. imagesthumb sphx_glr_z _thumb.pngz7Could not find internal Sphinx-Gallery thumbnail file: /_)intro thumbnailtitleref_name)rr ospathr5stemisfilerrelpathreplacesepBACKREF_THUMBNAIL_TEMPLATETHUMBNAIL_TEMPLATEformatr) target_dirsrc_dirfnamerr is_backrefcheckrrfull_dirrtemplates r_thumbnail_divrBs(8 KKE  Z74V 4V4V4VWWHE1  RW^^E**  Nu N N    GOOE7 + +Ewz733H MM"&# & &Ew||He,,44RVSAAH-7O))=OH ??UmmuEH   rc |ddStt}|D]E} tj|d|d| d} | |v} | rdnd} t | | fit 5} | sxd| d}| d |zd z| d t|zd z| d | t| t||d|||d | | ||  |||||fdddn #1swxYwYGt|S)aWrite and return backreferences for one example. Backreferences '.examples' file written includes reST of the list of examples as thumbnails. Parameters ---------- backrefs : set[str] Back references to write. seen_backrefs: set Back references already encountered when parsing this example. gallery_conf : Dict[str, Any] Gallery configurations. src_dir : str Stuff. target_dir : str Absolute path to directory where examples are saved. fname : str Filename of current example python file. intro : str Introductory docstring of example. title: str Title of example. Returns ------- backrefs_example : dict[str, tuple] Dictionary where value is the backreference object and value is a tuple containing: example filename, full path to example source directory, full path to example target directory, intro, title. backreferences_dirNr .examples.newawzExamples using ``z``z rx^z .. start-sphx-glr-thumbnails T)r)rr<rrr5openr writer?THUMBNAIL_PARENT_DIVrr*r1r)backrefs seen_backrefs gallery_confrrrrrbackrefs_examplebackref include_pathseenmodeex_fileheadings r_write_backreferencesrusD()1"4((YYw||  # - . % % %  -'#ss , . . . . Y' 4:g999 fw.5666 cCLL047888 DEEE 2333 MM +#       g & & & W % , ,eWj%QV-W X X X- Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y.  ! !!s1CEE "E c&tjjd}|ddS|D]}tj|d|d|d}tj|rWt|dfit5}| tdddn #1swxYwYt|d|d d }t||}|d ||d dS) z(Replace backref files only if necessary.zsphinx-galleryrNrrrt)r log_levelbackreference_missingz$Could not find backreferences file: zTThe backreferences are likely to be erroneous due to file system case insensitivity.)sphinxutillogging getLoggerrrr5rrr rTHUMBNAIL_PARENT_DIV_CLOSEr r@)rrloggerrrrrRfuncs r_finalize_backreferencesrsz [ * *+; < >$   dC))5)) :W 8999 : : : : : : : : : : : : : : : C ( ( ( ( ( -.EFE65))D D>>> ? ? ? D9    !sB<<C C r^)Nr)FT)#r`r/rCrrqrc collectionsrhtmlrpathlibr sphinx.utilr sphinx.errorsr_dummyrscrapersr utilsr r rr NodeVisitorr rnrvrrrrrrrrrrs   ######((((((%%%%%%&&&&&&&&~~~~~~~~BD     EEEEP(GK0000fE"E"E"Pr