
    QjfTO                       d Z ddlmZ dZddl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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 ddlmZ ej:                  dk\  rddlZnddlZej:                  dk\  rddl m!Z! nddl"m!Z! er?ddl#m$Z$ ddlm%Z% ddl&m'Z' ddl(m)Z)  G d de%d      Z* G d de%d      Z+ G d de%d      Z, ejZ                  e.      Z/ e0       Z1dZ2dZ3 G d d       Z4 G d! d"      Z5d2d#Z6	 	 	 	 	 	 	 	 d3d$Z7d4d%Z8d5d&Z9d6d'Z:d7d(Z;d8d*Z<d9d+Z=d:d,Z>d;d-Z? G d. d)      Z@d<d/ZAe.d0k(  r eB eAej                  d1d             y)=z"Theming support for HTML builders.    )annotations)ThemeHTMLThemeFactoryN)path)TYPE_CHECKINGAny)ZipFile)package_dir)check_confval_types)
ThemeError)__)logging)	ensuredir)      )r   
   )entry_points)Callable)	TypedDict)Required)Sphinxc                  "    e Zd ZU ded<   ded<   y)
_ThemeTomlzRequired[_ThemeTomlTheme]themedict[str, str]optionsN__name__
__module____qualname____annotations__     .lib/python3.12/site-packages/sphinx/theming.pyr   r   *   s    ((r#   r   F)totalc                  6    e Zd ZU ded<   ded<   ded<   ded<   y)	_ThemeTomlThemezRequired[str]inherit	list[str]stylesheetssidebars_ThemeTomlThemePygmentspygments_styleNr   r"   r#   r$   r'   r'   .   s    //r#   r'   c                  "    e Zd ZU ded<   ded<   y)r,   strdefaultdarkNr   r"   r#   r$   r,   r,   4   s    	r#   r,   z
theme.tomlz
theme.confc                  R    e Zd ZdZ	 	 	 	 	 	 	 	 	 	 ddZd	dZefd
dZdddZddZ	y)r   zA Theme is a set of HTML templates and configurations.

    This class supports both theme directory and theme archive (zipped theme).
    c                  || _         t        |      | _        || _        i }d| _        d| _        d | _        d | _        t        |j                               D ]  }||j                  z  }|j                  |j                  | _        |j
                  |j
                  | _        |j                  |j                  | _        |j                  v|j                  | _         || _        y )Nr"   )nametuple_dirs	_tmp_dirsr*   sidebar_templatespygments_style_defaultpygments_style_darkreversedvaluesr   _options)selfr4   configspathstmp_dirsr   configs          r$   __init__zTheme.__init__F   s     	5\
!"$,.2426#/3 w~~/0 		FFv~~%G!!-#)#5#5 ''3)/)A)A&,,8.4.K.K+))5+1+E+E(		F  r#   c                ,    t        | j                        S )zReturn a list of theme directories, beginning with this theme's,
        then the base theme's, then that one's base theme's, etc.
        )listr6   r>   s    r$   get_theme_dirszTheme.get_theme_dirsd   s     DJJr#   c                   |dk(  ry|dk(  r dj                  | j                        xs |}n|dk(  r dj                  | j                        xs |}nv|dk(  r| j                  xs |}n`|dk(  r| j                  xs |}nJ|}nG|dk(  r| j
                  j                  ||      }n%t        d      }t        j                  ||z         |}|t        u rt        d	      ||fz  }t        |      |S )
zdReturn the value for a theme configuration setting, searching the
        base theme chain.
        r   
stylesheet, r+   r-   pygments_dark_styler   zTheme configuration sections other than [theme] and [options] are not supported, returning the default value instead (tried to get a value from %r)z:setting %s.%s occurs in none of the searched theme configs)joinr*   r8   r9   r:   r=   getr   loggerinfo_NO_DEFAULTr   )r>   sectionr4   r0   valuemsgs         r$   
get_configzTheme.get_configj   s     g|#		$"2"23>w#		$"8"89DW))33>w..00;G	!MM%%dG4E 1C
 KKg&EKQRV C S/!r#   Nc                    |i }| j                   j                         }|j                         D ]0  \  }}||vr"t        j	                  t        d      |z         ,|||<   2 |S )z6Return a dictionary of theme options and their values.z!unsupported theme option %r given)r=   copyitemsrN   warningr   )r>   	overridesr   optionrR   s        r$   get_optionszTheme.get_options   sh    I--$$&&__. 	(MFEW$r"EFOP"'		( r#   c                    | j                   D ]9  }t        j                  t              5  t	        j
                  |       ddd       ; y# 1 sw Y   FxY w)zRemove temporary directories.N)r7   
contextlibsuppress	Exceptionshutilrmtree)r>   tmp_dirs     r$   _cleanupzTheme._cleanup   sI    ~~ 	'G$$Y/ 'g&' '	'' 's   A

A	)
r4   r/   r?   zdict[str, _ConfigFile]r@   r)   rA   r)   returnNone)rd   r)   )rQ   r/   r4   r/   r0   r   rd   r   N)rY   zdict[str, Any] | Nonerd   zdict[str, Any]rd   re   )
r   r   r    __doc__rC   rG   rP   rT   r[   rc   r"   r#   r$   r   r   @   sX    
   (	 
     
 <  BM #J'r#   r   c                  J    e Zd ZdZd	dZd
dZddZd
dZedd       Z	ddZ
y)r   z A factory class for HTML Themes.c                   || _         |j                  j                  | _        i | _        | j                          t        |j                  dd       r%| j                  |j                  j                         | j                          y )Nhtml_theme_path)_appregistryhtml_themes_themes_entry_point_themes_load_builtin_themesgetattrrB   _load_additional_themesrk   _load_entry_point_themes)r>   apps     r$   rC   zHTMLThemeFactory.__init__   sc    	||//BD !!#3::0$7(()C)CD%%'r#   c                    | j                  t        j                  t        d            }|j	                         D ]  \  }}|| j
                  |<    y)zLoad built-in themes.themesN)_find_themesr   rL   r
   rW   ro   )r>   rw   r4   r   s       r$   rq   z%HTMLThemeFactory._load_builtin_themes   sD    ""499[(#CD!<<> 	'KD%!&DLL	'r#   c                    |D ]w  }t        j                  t        j                  | j                  j                  |            }| j                  |      }|j                         D ]  \  }}|| j                  |<    y y)z7Load additional themes placed at specified directories.N)r   abspathrL   rl   confdirrx   rW   ro   )r>   theme_paths
theme_pathabs_theme_pathrw   r4   r   s          r$   rs   z(HTMLThemeFactory._load_additional_themes   sk    % 	+J!\\$))DII4E4Ez*RSN&&~6F%||~ +e%*T"+	+r#   c                    t        d      D ]T  }|j                  | j                  v r| j                  |j                  f	 	 	 	 	 dd}|| j
                  |j                  <   V y)zTry to load a theme with the specified name.

        This uses the ``sphinx.html_themes`` entry point from package metadata.
        zsphinx.html_themes)groupc                R    | j                  |       t        | | j                         y rf   )setup_extension_config_post_initrB   )ru   theme_modules     r$   _load_theme_closurezFHTMLThemeFactory._load_entry_point_themes.<locals>._load_theme_closure   s     
 ##L1!#szz2r#   N)ru   r   r   r/   rd   re   )r   r4   ro   rl   modulerp   )r>   entry_pointr   s      r$   rt   z)HTMLThemeFactory._load_entry_point_themes   s|    
 (.BC 	MK4<</ #ii$/$6$633 "3 	3 :MD$$[%5%56	Mr#   c                4   i }t        j                  |       s|S t        j                  |       D ]  }t        j                  | |      }t        j
                  |      rU|j                         j                  d      r6t        |      r|dd }|||<   ct        j                  t        d      |       t        j                  |t              }t        j                  |t              }t        j
                  |      st        j
                  |      s|||<    |S )z'Search themes from specified directory.z.zipNzAfile %r on theme path is not a valid zipfile or contains no theme)r   isdiroslistdirrL   isfilelowerendswith_is_archived_themerN   rX   r   _THEME_TOML_THEME_CONF)r}   rw   entrypathnamer4   	toml_path	conf_paths          r$   rx   zHTMLThemeFactory._find_themes   s     "$zz*%MZZ
+ 	-EyyU3H{{8$)?)?)G%h/ ":D#+F4LNN;  !IIh<	 IIh<	;;y)T[[-C$,F5M%	-( r#   c                    || j                   v r| j                   |   } |        || j                  vrt        t        d      |z        t	        || j                  | j                         \  }}}t        ||||      S )zCreate an instance of theme.z-no theme named %r found (missing theme.toml?))r?   r@   rA   )rp   ro   r   r   _load_theme_with_ancestorsr   )r>   r4   entry_point_loaderrw   
theme_dirsrA   s         r$   createzHTMLThemeFactory.create   s    4+++!%!9!9$!? t||#R OPSWWXX'ALL$$(
$
H
 T6hOOr#   N)ru   r   rd   re   rg   )r|   r/   rd   re   )r}   r/   rd   r   )r4   r/   rd   r   )r   r   r    rh   rC   rq   rs   rt   staticmethodrx   r   r"   r#   r$   r   r      s4    *('+M&  8Pr#   r   c                   	 t        |       5 }t        |j                               }t        |v xs t        |v cddd       S # 1 sw Y   yxY w# t
        $ r Y yw xY w)zBCheck whether the specified file is an archived theme file or not.NF)r	   	frozensetnamelistr   r   r_   )filenamefr   s      r$   r   r      s_    X 	F! .H(*EkX.E	F 	F 	F  s-   A +A	A AA A 	AAc          	        i }g }g }t        d      D ]  }t        | ||          \  }}}	}
|j                  |       |	|j                  |	       |
|| <   |dk(  r n||v rt        d      | z  }t	        |      ||v r||vr||   } |        ||vr4t        d      | |dj                  t        |            fz  }t	        |      |}  t        d      | z  }t	        |      |||fS )Nr   nonez%The %r theme has circular inheritancezQThe %r theme inherits from %r, which is not a loaded theme. Loaded themes are: %srJ   z#The %r theme has too many ancestors)range_load_themeappendr   r   rL   sorted)r4   r|   entry_point_themesrw   r   rA   _r(   	theme_dirrb   rB   rS   r   s                r$   r   r   	  s*    &(FJH 2Y .9$D@Q.R+GV)$OOG$tff<=DCS/!((WK-G!3G!< +%( w		&*= >?@C S/!+. 67$>o:x''r#   c               &   t        j                  |      rd }|}n7t        j                  d      }t        j                  ||       }t        ||       t        j                  t        j                  |t              x}      r#t        |      }t        ||       }t        |      }nit        j                  t        j                  |t              x}      r#t        |      }	t        |	|       }t        |	      }nt        t!        d      |z        ||||fS )Nsxtz'no theme configuration file found in %r)r   r   tempfilemkdtemprL   _extract_zipr   r   _load_theme_toml_validate_theme_toml_convert_theme_tomlr   _load_theme_conf_validate_theme_conf_convert_theme_confr   r   )
r4   r}   rb   r   r   
_cfg_tabler(   rB   r   _cfg_parsers
             r$   r   r   1  s    zz*	 ""5)IIgt,	Z+{{		)[ AA9B%i0
&z48$Z0	$))I{"CCY	D&y1&{D9$[1EFRSSIw..r#   c                  t        |       t        |       5 }|j                         D ]  }|j                  d      rt	        j
                  ||      }t        t	        j                  |             t        t	        j
                  |      d      5 }|j                  |j                  |             ddd        	 ddd       y# 1 sw Y   xY w# 1 sw Y   yxY w)z%Extract zip file to target directory./wbN)
r   r	   r   r   r   rL   dirnameopenwriteread)r   
target_dirarchiver4   r   fps         r$   r   r   J  s    j		 -g$$& 	-D}}S!IIj$/Edll5)*dii&- -d+,- -	-- -- -- -s$   A9C!C1
CC
CCc                   t        | d      5 }|j                         }d d d        t        j                        }dD ci c]  }||v s|||    c}S # 1 sw Y   7xY wc c}w )Nutf-8encoding)r   r   )r   r   tomllibloads)config_file_pathr   config_textcss        r$   r   r   X  s`    		1 Qffhk"A1<Q!VAqtG<<  =s   A 	A!
A!Ac                V   d| vrt        d      |z  }t        |      | d   }t        |t              st        d      |z  }t        |      |j	                  dd      }|st        d      |z  }t        |      d| v r,t        | d   t              st        d      |z  }t        |      |S )	Nr   'theme %r doesn't have the "theme" tablez+The %r theme "[theme]" table is not a tabler(    4The %r theme must define the "theme.inherit" settingr   z-The %r theme "[options]" table is not a table)r   r   
isinstancedictrM   )cfgr4   rS   r   r(   s        r$   r   r   _  s    c;<tCoLEeT">?$Foii	2&GGH4OoC#i.$/DELCS/!Nr#   _ConfigFilec          
     f   | d   }d|v rt        |d         }nd }d|v rt        |d         }nd }|j                  di       }t        |t              rd| d}t	        d      |z  }t        |      |j                  d      }|j                  d	      }t        ||||| j                  d
i             S )Nr   r*   r+   r-   zpygments_style = { default = "z" }z>The "theme.pygments_style" setting must be a table. Hint: "%s"r0   r1   r   r*   r8   r9   r:   r   )r5   rM   r   r/   r   r   r   )	r   r   r*   r8   pygments_tablehintrS   r9   r:   s	            r$   r   r   r  s    LE.3E-4H.IU49%
:K4L YY/4N.#&00@EQRUYYo)7););I)F&4&8&8&@+5/	2& r#   c               T    t        j                         }|j                  | d       |S )Nr   r   )configparserRawConfigParserr   )r   r   s     r$   r   r     s&    $$&AFFgF.Hr#   c                    | j                  d      st        t        d      |z        | j                  ddd       x}r|S t        d      |z  }t        |      )Nr   r   r(   fallbackr   )has_sectionr   r   rM   )r   r4   r(   rS   s       r$   r   r     s]    ??7#FG$NOO'''9t'<<w<
C
Dt
KC
S/r#   c                  | j                  ddd      x}r3t        t        t        j                  |j                  d                  }nd }| j                  ddd      x}r3t        t        t        j                  |j                  d                  }nd }| j                  ddd       }| j                  ddd       }| j                  d	      rt        | j                  d	            ni }t        |||||
      S )Nr   rI   r   r   ,r+   r-   rK   r   r   )
rM   r5   mapr/   stripsplitr   r   rW   r   )r   rI   r*   sidebarr8   r9   r:   r   s           r$   r   r     s    WWWlRW@@z@.3C		:CSCSTWCX4Y.Z''':';;w;49#ciiWZI[:\4] ),:JUY)Z&)ggg7LW[g&\,/OOI,Fd399Y'(BG+5/ r#   c                  H    e Zd ZdZ	 	 	 	 	 	 	 	 	 	 	 	 ddZddZd	dZd
dZy)r   r   c                f    || _         || _        || _        || _        |j	                         | _        y rf   )r*   r8   r9   r:   rV   r   )r>   r*   r8   r9   r:   r   s         r$   rC   z_ConfigFile.__init__  s1     4?9J2H#/B '.||~r#   c                    | j                   j                   d| j                  d| j                  d| j                  d| j
                  d| j                  dS )Nz(stylesheets=z, sidebar_templates=z, pygments_style_default=z, pygments_style_dark=z
, options=))	__class__r    r*   r8   r9   r:   r   rF   s    r$   __repr__z_ConfigFile.__repr__  sr    ~~**+ ,++. /!!%!7!7 : ;&&*&A&A%D E##'#;#;"> ?||&a)	
r#   c                8   t        |t              r| j                  |j                  k(  xrj | j                  |j                  k(  xrO | j                  |j                  k(  xr4 | j
                  |j
                  k(  xr | j                  |j                  k(  S t        S rf   )r   r   r*   r8   r9   r:   r   NotImplemented)r>   others     r$   __eq__z_ConfigFile.__eq__  s    e[)  E$5$55 2**e.E.EE2//53O3OO2 ,,0I0II2 LLEMM1 r#   c                    t        | j                  j                  | j                  | j                  | j
                  | j                  | j                  f      S rf   )hashr   r    r*   r8   r9   r:   r   rF   s    r$   __hash__z_ConfigFile.__hash__  sL    NN''""''$$LL
  	r#   N)r*   tuple[str, ...] | Noner8   r   r9   
str | Noner:   r   r   r   rd   re   )rd   r/   )r   objectrd   bool)rd   int)r   r   r    	__slots__rC   r   r   r   r"   r#   r$   r   r     sW    I6+6 26 !+	6
 (6  6 
6
	r#   c           	        | d d dgk7  rt        d      | dd  } t        |       dk7  rt        d       t        d      t        j                  | d         }t        j
                  |t              }t        j                  |      rt        j                  |      st        |d       yt        |      }|j                  d      st        d       y|j                  ddd 	      }|st        d
       ydd| dg}|j                  ddd	      }|dk(  r|j                  d       ne|dura|j                  d       |j                  d t        t        j                   |j#                  d            D               |j                  d       |j                  ddd	      }|dk(  r|j                  d       nd|dur`|j                  d       |t        t        j                   |j#                  d            D cg c]  }d| d
 c}z  }|j                  d       g }	|j                  ddd	      }
|
dur|	j                  d|
 d       |j                  ddd	      }|dur|	j                  d| d       |	r&|j                  dd j                  |	      z   d!z          |j                  d"      rd|j                  d       |j                  d#       ||j%                  d"      D 
cg c]"  \  }}
|
j'                  dd$      x}s	 | d%| d$ c}
}z  }t        j
                  |t(              }t+        |d&d'(      5 }|j-                  d)j                  |      d)z          d d d        t        d*|       yc c}w c c}
}w # 1 sw Y   #xY w)+N   conf_to_tomlr   z9Usage: python -m sphinx.theming conf_to_toml <theme path>zC must be a path to a theme directory containing a "theme.conf" filer   zThe "theme" table is missing.r(   r   z'The "theme.inherit" setting is missing.z[theme]zinherit = ""rI   .r   zstylesheets = []zstylesheets = [c              3  (   K   | ]
  }d | d  yw)    "",Nr"   ).0r   s     r$   	<genexpr>z(_migrate_conf_to_toml.<locals>.<genexpr>  s     WAE!B-Ws   r   ]r+   zsidebars = []zsidebars = [r   r   r-   zdefault = "rK   zdark = "zpygments_style = { rJ   z }r   z	[options]z\"z = "wr   r   
zWritten converted settings to )
SystemExitlenprintr   realpathrL   r   r   r   r   r   rM   r   extendr   r/   r   r   rW   replacer   r   r   )argvr   r   r   r(   
toml_linesrI   r   r   stylesr0   r1   keydr   r   s                   r$   _migrate_conf_to_tomlr    si   BQxN##m8D
4yA~IJmd1g&I		)[1I::i I(>m^_	
 "9-K""7+-.oogy4o@G78 	
gYa J
 ,EJR,-	3	+,WSYY
@P@PQT@U1VWW#oogzCo@G"}/*		.)c#))W]]3=O.PQqc}QQ
#Foog'7#oFGcG9A./??7$9C?HD3a()/$))F2CCdJKy)"+& + 1 1) <
W__S%000T e4s!
 	

 		)[1I	iw	/ .1			*%,-.	*9-
895 R 
. .s   7M6&'M;;$NN
__main__r   )r   r/   rd   r   )r4   r/   r|   r   r   zdict[str, Callable[[], None]]rd   z3tuple[dict[str, _ConfigFile], list[str], list[str]])r4   r/   r}   r/   rd   z(tuple[str, str, str | None, _ConfigFile])r   r/   r   r/   rd   re   )r   r/   rd   r   )r   r   r4   r/   rd   r/   )r   r   rd   r   )r   r/   rd   configparser.RawConfigParser)r   r  r4   r/   rd   r/   )r   r  rd   r   )r
  r)   rd   r   )Drh   
__future__r   __all__r   r]   r   r`   sysr   r   typingr   r   zipfiler	   sphinxr
   sphinx.configr   r   sphinx.errorsr   sphinx.localer   sphinx.utilr   sphinx.util.osutilr   version_infor   tomliimportlib.metadatar   importlib_metadatacollections.abcr   r   typing_extensionsr   sphinx.applicationr   r   r'   r,   	getLoggerr   rN   r   rP   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r  r  r
  r"   r#   r$   <module>r%     sr   ( "
'   	  
   %   B $   (ww//( *) Ye  0)5 0)5 
 
		8	$ha' a'HXP XPv%(
%(%( 6%(
 9%(P/2-=&4*4 4nCL z
*388AB<8
99 r#   