
    }cUG              
       N   U d 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 ddlmZ dd	lmZ dd
lmZ e	rddlmZ dZdZ ed           Z ee!e"f         e#d<   e $                    ej%        ej%        ej&        ej'        ej(        eej)        d            ed           Z*ee"e"f         e#d<   e*$                    ej(        eej)        d            ed ej&        dej'        dej)        di          Z+de!ddfdZ,deej-                 ddfdZ. G d dej-                  Z/ G d  d!e/          Z0 G d" d#e/          Z1 G d$ dej2                  Z3 G d% d&ej4                  Z5 G d' d(ej4                  Z6 G d) d*ej7        j8                  Z9edeej:        ddf         fd+            Z;edee9ddf         fd,            Z<edee9ddf         fd-            Z=edYd/e>ded0         fd1            Z?ed2e!ded0         fd3            Z@ G d4 d5          ZA G d6 d7ejB                  ZCd8e!d9e!d:ee!         de>fd;ZD G d< d=ejB                  ZE G d> d?ejB                  ZF G d@ dAejB                  ZG G dB dCejB                  ZH G dD dEejB                  ZI G dF dGejB                  ZJ G dH dIeJ          ZK G dJ dKeJ          ZLdLedee!         fdMZM G dN dOejN                  ZO G dP dQ          ZP G dR dS          ZQdTdUdVedWeddfdXZRdS )Zz%Logging utility functions for Sphinx.    N)defaultdict)contextmanager)
IOTYPE_CHECKINGAnyDict	GeneratorListOptionalTupleTypeUnion)nodes)Nodeget_source_line)SphinxWarning)colorize)Sphinxsphinx   c                      t           j        S N)loggingWARNING     3lib/python3.11/site-packages/sphinx/util/logging.py<lambda>r      s    '/ r   LEVEL_NAMES)CRITICALSEVEREERRORr   INFOVERBOSEDEBUGc                      dS )Nr   r   r   r   r   r   r   "   s    A r   VERBOSITY_MAP)r         c                      dS )Nbluer   r   r   r   r   r   )   s     r   darkredreddarkgraynamereturnSphinxLoggerAdapterc                 n    t          j        t          dz   | z             }d|_        t	          |i           S )a  Get logger wrapped by :class:`sphinx.util.logging.SphinxLoggerAdapter`.

    Sphinx logger always uses ``sphinx.*`` namespace to be independent from
    settings of root logger.  It ensures logging is consistent even if a
    third-party extension or imported application resets logger settings.

    Example usage::

        >>> from sphinx.util import logging
        >>> logger = logging.getLogger(__name__)
        >>> logger.info('Hello, this is an extension!')
        Hello, this is an extension!
    .F)r   	getLogger	NAMESPACEdisabledr2   )r0   loggers     r   r5   r5   1   s4     y3566FFOvr***r   recordsc                     | D ]a}|                                 |_        d|_        t          |dd          }t	          |t
          j                  rt          |          |_        bdS )zConvert LogRecord serializable.r   locationN)	
getMessagemsgargsgetattr
isinstancer   r   get_node_locationr;   )r9   rr;   s      r   convert_serializablerC   G   sf     5 51j$//h
++ 	5*844AJ5 5r   c                   <     e Zd ZU dZdZdZeed<   def fdZ	 xZ
S )SphinxLogRecordz$Log record class supporting location Nr;   r1   c                     t                                                      }t          | dd           }|r|d| j        |}n| j        |vr
| j        |z   }|S )Nr;   z: )superr<   r?   prefix)selfmessager;   	__class__s      r   r<   zSphinxLogRecord.getMessageX   si    ''$$&&4T22 	,$,HHdkk77CGG[' 	,kG+Gr   )__name__
__module____qualname____doc__rI   r;   r   __annotations__strr<   __classcell__rL   s   @r   rE   rE   S   sa         ..FHcC          r   rE   c                       e Zd ZdZdZdS )SphinxInfoLogRecordz)Info log record class supporting locationrF   N)rM   rN   rO   rP   rI   r   r   r   rV   rV   c   s        33FFFr   rV   c                   .    e Zd ZdZedefd            ZdS )SphinxWarningLogRecordz,Warning log record class supporting locationr1   c                 b    | j         t          j        k    rdS | j         t          j        k    rdS dS )Nz
CRITICAL: zERROR: z	WARNING: )levelnor   r!   r#   rJ   s    r   rI   zSphinxWarningLogRecord.prefixj   s4    <7++ 	<\W]* 	9;r   N)rM   rN   rO   rP   propertyrR   rI   r   r   r   rX   rX   h   s?        66    X  r   rX   c            
            e Zd ZdZg dZdeeef         dedededdf
 fd	Z	dedededdfd
Z
dededeeef         fdZdej        ddfdZ xZS )r2   z9LoggerAdapter allowing ``type`` and ``subtype`` keywords.)typesubtyper;   nonlcoloroncelevelr=   r>   kwargsr1   Nc                     t          |t                    r  t                      j        ||g|R i | d S t          |         } t                      j        ||g|R i | d S r   )r@   intrH   logr    )rJ   rc   r=   r>   rd   rZ   rL   s         r   rg   zSphinxLoggerAdapter.logx   s{    eS!! 	7EGGKs4T444V44444!%(GEGGK6t666v66666r   c                 4     | j         t          |g|R i | d S r   )rg   r%   )rJ   r=   r>   rd   s       r   verbosezSphinxLoggerAdapter.verbose   s,    #/////////r   c                     |                     di           }| j        D ]}||v r|                    |          ||<   ||fS )Nextra)
setdefaultKEYWORDSpop)rJ   r=   rd   rk   keywords        r   processzSphinxLoggerAdapter.process   sU    !!'2..} 	5 	5G&  5!'G!4!4gF{r   recordc                 :    | j                             |           d S r   )r8   handlerJ   rq   s     r   rs   zSphinxLoggerAdapter.handle   s    6"""""r   )rM   rN   rO   rP   rm   r   rf   rR   r   rg   ri   r   r   rp   r   	LogRecordrs   rS   rT   s   @r   r2   r2   t   s       CCGGGH7sCx 7s 73 7# 7RV 7 7 7 7 7 703 0s 0c 0d 0 0 0 03  sDy1A    #W. #4 # # # # # # # #r   c                       e Zd ZdZdS )WarningStreamHandlerzStreamHandler for warnings.N)rM   rN   rO   rP   r   r   r   rw   rw      s        %%Dr   rw   c                   6     e Zd ZdZdej        ddf fdZ xZS )NewLineStreamHandlerzAStreamHandler which switches line terminator by record.nonl flag.rq   r1   Nc                    	 |                                   t          |dd          rd| _        t                                          |           d| _        |                                  d S # d| _        |                                  w xY w)Nr`   FrF   
)acquirer?   
terminatorrH   emitrelease)rJ   rq   rL   s     r   r~   zNewLineStreamHandler.emit   sz    	LLNNNvvu-- %"$GGLL   "DOLLNNNNN #DOLLNNNNs   AA- -B
)rM   rN   rO   rP   r   ru   r~   rS   rT   s   @r   ry   ry      sT        KK	7, 	 	 	 	 	 	 	 	 	 	 	r   ry   c                        e Zd ZU dZeej                 ed<   d fdZdej        de	fdZ
ddZd	ej        ddfd
Zdeej                 fdZ xZS )MemoryHandlerzHandler buffering all logs.bufferr1   Nc                 J    t                                          d           d S )N)rH   __init__)rJ   rL   s    r   r   zMemoryHandler.__init__   s!    r   rq   c                     dS )NFr   rt   s     r   shouldFlushzMemoryHandler.shouldFlush   s    ur   c                     d S r   r   r[   s    r   flushzMemoryHandler.flush   s	     	r   r8   c                     |                                   	 | j        D ]}|                    |           g | _        |                                  d S # |                                  w xY wr   )r|   r   rs   r   )rJ   r8   rq   s      r   flushTozMemoryHandler.flushTo   sd    	+ & &f%%%%DKLLNNNNNDLLNNNNs   &A A(c                 $    | j         g c}| _         |S r   )r   )rJ   r   s     r   clearzMemoryHandler.clear   s    "k2r   r1   N)rM   rN   rO   rP   r
   r   ru   rQ   r   boolr   r   Loggerr   r   rS   rT   s   @r   r   r      s         %%"####     '"3        
gn     tG-.        r   r   c               #     K   t          j        t                    } t                      }|                    t           j                   	 g }| j        dd         D ]A}t          |t                    r*| 	                    |           |
                    |           B|                     |           |V  | 	                    |           |D ]}|                     |           |                    |            dS # | 	                    |           |D ]}|                     |           |                    |            w xY w)zgContext manager to postpone logging warnings temporarily.

    Similar to :func:`pending_logging`.
    N)r   r5   r6   r   setLevelr   handlersr@   rw   removeHandlerappend
addHandlerr   r8   
memhandlerr   handlers       r   pending_warningsr      s`      y))FJ(((#qqq) 	) 	)G'#788 )$$W---(((*%%%Z((( 	' 	'Gg&&&&6""""" 	Z((( 	' 	'Gg&&&&6""""s   
A,C< <AEc               #     K   t          j        t                    } t                      }	 g }| j        dd         D ],}|                     |           |                    |           -|                     |           |V  |                     |           |D ]}|                     |           dS # |                     |           |D ]}|                     |           w xY w)zContext manager to suppress logging all logs temporarily.

    For example::

        >>> with suppress_logging():
        >>>     logger.warning('Warning message!')  # suppressed
        >>>     some_long_process()
        >>>
    N)r   r5   r6   r   r   r   r   r   r   s       r   suppress_loggingr      s      y))FJ'qqq) 	% 	%G  )))OOG$$$$*%%%Z((( 	' 	'Gg&&&&	' 	' 	Z((( 	' 	'Gg&&&&	's   AB3 31C$c               #      K   t          j        t                    } 	 t                      5 }|V  ddd           n# 1 swxY w Y   |                    |            dS # |                    |            w xY w)a$  Context manager to postpone logging all logs temporarily.

    For example::

        >>> with pending_logging():
        >>>     logger.warning('Warning message!')  # not flushed yet
        >>>     some_long_process()
        >>>
        Warning message!  # the warning is flushed here
    N)r   r5   r6   r   r   )r8   r   s     r   pending_loggingr      s       y))F# 	:	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	6"""""
6""""s+   A <A A  A A A A5TskipNNNc              #   F  K   t          j        t                    }| du rdV  dS 	 t                      }|j        D ]}|j                            d|           dV  |j        D ]}|                    |           dS # |j        D ]}|                    |           w xY w)z9Context manager to skip WarningIsErrorFilter temporarily.FNr   )r   r5   r6   DisableWarningIsErrorFilterr   filtersinsertremoveFilter)r   r8   disablerr   s       r   skip_warningiserrorr     s       y))Fu} /		/244H!? 4 4 &&q(3333EEE!? / /$$X..../ /6? / /$$X..../s   7A? ?!B rI   c              #     K   t          j        t                    }d}|j        D ]}t	          |t
                    r|} ndV  dS d}|j        D ]}t	          |t                    r|} n|r(	 |j        }| |_        dV  ||_        dS # ||_        w xY wt          |           }	 |	                    |           dV  |
                    |           dS # |
                    |           w xY w)zContext manager to prepend prefix to all warning log records temporarily.

    For example::

        >>> with prefixed_warnings("prefix:"):
        >>>     logger.warning('Warning message!')  # => prefix: Warning message!

    .. versionadded:: 2.0
    N)r   r5   r6   r   r@   rw   r   MessagePrefixFilterrI   	addFilterr   )rI   r8   warning_handlerr   prefix_filter_filterpreviouss          r   prefixed_warningsr   !  sH      y))FO?  g344 	%OE	
 	M"*  g233 	#ME	  8	,$+H#)M EEE#+M   8M ++++ ,F33	8%%m444EEE((77777O((7777s   /B
 
	B&C C-c                   >    e Zd ZddZeded         fd            ZdS )LogCollectorr1   Nc                     g | _         d S r   )logsr[   s    r   r   zLogCollector.__init__P  s    -/			r   r   c              #      K   t                      5 }d V  |                                | _        d d d            d S # 1 swxY w Y   d S r   )r   r   r   )rJ   r   s     r   collectzLogCollector.collectS  s       	+*EEE"((**DI	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+s   <A A r   )rM   rN   rO   r   r   r	   r   r   r   r   r   r   O  sU        0 0 0 0 +#34 + + + ^+ + +r   r   c                   ,    e Zd ZdZdej        defdZdS )
InfoFilterz"Filter error and warning messages.rq   r1   c                 4    |j         t          j        k     rdS dS )NTF)rZ   r   r   rt   s     r   filterzInfoFilter.filter^  s    >GO+ 	45r   NrM   rN   rO   rP   r   ru   r   r   r   r   r   r   r   [  s?        ,,W. 4      r   r   r^   r_   suppress_warningsc                 |    | dS |D ]4}d|v r|                     dd          \  }}n|d}}|| k    r
|d|dfv r dS 5dS )z/Check whether the warning is suppressed or not.NFr4   r)   *T)split)r^   r_   r   warning_typetarget	subtargets         r   is_suppressed_warningr   e  s~     u *  , 	3 , 2 23 : :FII ,dIFT> 	iD'3+?? 	445r   c                   >     e Zd ZdZd	 fdZdej        defdZ xZ	S )
WarningSuppressorz#Filter logs by `suppress_warnings`.appr   r1   Nc                 V    || _         t                                                       d S r   r   rH   r   rJ   r   rL   s     r   r   zWarningSuppressor.__init__{  &    r   rq   c                     t          |dd           }t          |dd           }	 | j        j        j        }n# t          $ r g }Y nw xY wt          |||          rdS | j        xj        dz  c_        dS )Nr^   r_   Fr)   T)r?   r   configr   AttributeErrorr   
_warncount)rJ   rq   r^   r_   r   s        r   r   zWarningSuppressor.filter  s    vvt,,&)T22	# $ A 	# 	# 	# "	# !w0ABB 	5H1$4s   6 AAr   r   r1   N
rM   rN   rO   rP   r   r   ru   r   r   rS   rT   s   @r   r   r   x  sh        --     W. 4        r   r   c                   >     e Zd ZdZd	 fdZdej        defdZ xZ	S )
WarningIsErrorFilterz#Raise exception if warning emitted.r   r   r1   Nc                 V    || _         t                                                       d S r   r   r   s     r   r   zWarningIsErrorFilter.__init__  r   r   rq   c                 Z   t          |dd          rdS | j        j        rt          |dd          }	 |j        |j        z  }n# t
          t          f$ r
 |j        }Y nw xY w|r#t          |dz   t          |          z             }nt          |          }|j	        ||j	        d         |dS )Nskip_warningsiserrorFTr;   rF   :r)   )
r?   r   warningiserrorr=   r>   	TypeError
ValueErrorr   rR   exc_info)rJ   rq   r;   rK   excs        r   r   zWarningIsErrorFilter.filter  s    61599 	4X$ 	vz266H% *v{2z* % % % *%  -#HsNS\\$ABB#G,, vq11	4s   A AAr   r   rT   s   @r   r   r     sh        --     W. 4        r   r   c                   ,    e Zd ZdZdej        defdZdS )r   z6Disable WarningIsErrorFilter if this filter installed.rq   r1   c                     d|_         dS )NT)r   rt   s     r   r   z"DisableWarningIsErrorFilter.filter  s    &*#tr   Nr   r   r   r   r   r     s?        @@W. 4      r   r   c                   F     e Zd ZdZdeddf fdZdej        defdZ	 xZ
S )r   z"Prepend prefix to all log records.rI   r1   Nc                 V    || _         t                                                       d S r   )rI   rH   r   )rJ   rI   rL   s     r   r   zMessagePrefixFilter.__init__  s&    r   rq   c                 B    | j         r| j         dz   |j        z   |_        dS )N T)rI   r=   rt   s     r   r   zMessagePrefixFilter.filter  s&    ; 	8s*VZ7FJtr   rM   rN   rO   rP   rR   r   r   ru   r   r   rS   rT   s   @r   r   r     sv        ,,s t      W. 4        r   r   c                   H     e Zd ZdZd	deddf fdZdej        defdZ	 xZ
S )

OnceFilterzShow the message only once.rF   r0   r1   Nc                 X    t                                          |           i | _        d S r   )rH   r   messages)rJ   r0   rL   s     r   r   zOnceFilter.__init__  s&    )+r   rq   c                     t          |dd          }|sdS | j                            |j        g           }|j        |v rdS |                    |j                   dS )Nrb   rF   TF)r?   r   rl   r=   r>   r   )rJ   rq   rb   paramss       r   r   zOnceFilter.filter  sf    vvr** 	4]--fj"==F{f$ uMM&+&&&4r   )rF   r   rT   s   @r   r   r     s{        %%, ,S ,$ , , , , , ,
W. 
4 
 
 
 
 
 
 
 
r   r   c                   V     e Zd ZU dZeej                 ed<   d
 fdZde	de
fd	Z xZS )SphinxLogRecordTranslatorzConverts a log record to one Sphinx expects

    * Make a instance of SphinxLogRecord
    * docname to path if location given
    LogRecordClassr   r   r1   Nc                 V    || _         t                                                       d S r   r   r   s     r   r   z"SphinxLogRecordTranslator.__init__  r   r   rq   c                     t          |t          j                  r| j        |_        t          |dd           }t          |t                    re|\  }}|r,|r*| j        j        	                    |          d||_
        n|r(d| j        j        	                    |          z  |_
        ndd |_
        n\t          |t          j                  rt          |          |_
        n-|r+d|vr'd| j        j        	                    |          z  |_
        dS )Nr;   r   z%sT)r@   r   ru   r   rL   r?   tupler   envdoc2pathr;   r   r   rA   )rJ   rq   r;   docnamelinenos        r   r   z SphinxLogRecordTranslator.filter  s   fg/00 	3#2F6:t44h&& 	E&OGV '6 '-1X\-B-B7-K-K-K-KVV"T '"&)>)>w)G)G"G"&%*-- 	E/99FOO 	E#X- 	E"TX\%:%:8%D%DDFOtr   r   )rM   rN   rO   rP   r   r   ru   rQ   r   rX   r   r   rS   rT   s   @r   r   r     s          
 *++++     3         r   r   c                       e Zd ZdZeZdS )InfoLogRecordTranslatorz/LogRecordTranslator for INFO level log records.N)rM   rN   rO   rP   rV   r   r   r   r   r   r     s        99(NNNr   r   c                       e Zd ZdZeZdS )WarningLogRecordTranslatorz2LogRecordTranslator for WARNING level log records.N)rM   rN   rO   rP   rX   r   r   r   r   r   r     s        <<+NNNr   r   nodec                 \    t          |           \  }}|r	|r|d|S |rd|z  S |rd|z  S d S )Nr   z%s:z<unknown>:%sr   )r   sourcelines      r   rA   rA     s]    $T**NVT $  &&$$''	 v~	 $$tr   c                   2     e Zd Zdej        def fdZ xZS )ColorizeFormatterrq   r1   c                     t                                          |          }t          |dd           }|t                              |j                  }|rt          ||          S |S )Nra   )rH   formatr?   	COLOR_MAPgetrZ   r   )rJ   rq   rK   ra   rL   s       r   r   zColorizeFormatter.format  sa    ''..((.. 	2MM&.11E 	E7+++Nr   )rM   rN   rO   r   ru   rR   r   rS   rT   s   @r   r   r     sN        	W. 	3 	 	 	 	 	 	 	 	 	 	r   r   c                   :    e Zd ZdZdeddfdZdeddfdZd	dZdS )
SafeEncodingWriterz7Stream writer which ignores UnicodeEncodeError silentlystreamr1   Nc                 D    || _         t          |dd          pd| _        d S )Nencodingascii)r  r?   r  )rJ   r  s     r   r   zSafeEncodingWriter.__init__  s%    
G<<Gr   datac                     	 | j                             |           d S # t          $ rO | j                             |                    | j        d                              | j                             Y d S w xY w)Nreplace)r  writeUnicodeEncodeErrorencoder  decoderJ   r  s     r   r	  zSafeEncodingWriter.write"  s    	[Kd#####! 	[ 	[ 	[ Kdkk$-CCJJ4=YYZZZZZZ	[s    AA76A7c                 f    t          | j        d          r| j                                         d S d S )Nr   )hasattrr  r   r[   s    r   r   zSafeEncodingWriter.flush*  s:    4;(( 	 K	  	 r   r   )	rM   rN   rO   rP   r   r   rR   r	  r   r   r   r   r  r    s~        AAHr Hd H H H H[# [$ [ [ [ [           r   r  c                   6    e Zd ZdZdddeddfdZdeddfd	ZdS )
LastMessagesWriterzBStream writer storing last 10 messages in memory to save trackbackr   r   r  r1   Nc                     || _         d S r   )r   )rJ   r   r  s      r   r   zLastMessagesWriter.__init__1  s    r   r  c                 D    | j         j                            |           d S r   )r   
messagelogr   r  s     r   r	  zLastMessagesWriter.write4  s!    ""4(((((r   )rM   rN   rO   rP   r   r   rR   r	  r   r   r   r  r  /  se        LLH b T    )# )$ ) ) ) ) ) )r   r  r   r   statuswarningc                 r   t          j        t                    }|                    t           j                   d|_        |j        dd         D ]}|                    |           t          t          |                    }|
                    t                                 |
                    t          |                      |                    t          | j                            |                    t!                                 t#          t          |                    }|
                    t%          |                      |
                    t'          |                      |
                    t)          |                      |
                    t+                                 |                    t           j                   |                    t!                                 t          j        t1          | |                    }|
                    t                                 |                    t          | j                            |                    t!                                 |                    |           |                    |           |                    |           dS )zSetup root logger for SphinxFN)r   r5   r6   r   r&   	propagater   r   ry   r  r   r   r   r(   	verbositysetFormatterr   rw   r   r   r   r   r   StreamHandlerr  r   )r   r  r  r8   r   info_handlerr   messagelog_handlers           r   setupr  8  sE   y))F
OOGM"""F ?111% & &W%%%%'(:6(B(BCCL:<<(((2377888-6777/11222*+=g+F+FGGO/445558==>>>2377888jll+++W_---  !2!4!4555 ./A#v/N/NOO  ...cm <===##$5$7$7888
l###
o&&&
()))))r   )T)SrP   r   logging.handlerscollectionsr   
contextlibr   typingr   r   r   r   r	   r
   r   r   r   r   docutilsr   docutils.nodesr   docutils.utilsr   sphinx.errorsr   sphinx.util.consoler   sphinx.applicationr   r6   r%   r    rR   rf   rQ   updater!   r#   r   r$   r&   r(   r   r5   ru   rC   rE   rV   rX   LoggerAdapterr2   r  rw   ry   r   BufferingHandlerr   Handlerr   r   r   r   r   r   r   Filterr   r   r   r   r   r   r   r   r   r   rA   	Formatterr   r  r  r  r   r   r   <module>r/     sS   + + +      # # # # # # % % % % % % ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^             * * * * * * ' ' ' ' ' ' ( ( ( ( ( ( *)))))) 	
)k*A*ABBT#s(^ B B B    ]L]     !,II 6 6tCH~ 6 6 6   |}     K#M9#OU#M: 	+C +1 + + + +,	5$w'8"9 	5d 	5 	5 	5 	5    g'        /   
	 	 	 	 	_ 	 	 	# # # # #'/ # # #4	 	 	 	 	70 	 	 	
    70       G$5   < #)GOT4$?@ # # # #6 ')M4$=> ' ' ' '8 #=$#<= # # # #& / /d /i8H.I / / / /& *8c *8i0@&A *8 *8 *8 *8Z	+ 	+ 	+ 	+ 	+ 	+ 	+ 	+        c d3i TX    &       0    7>   <    '.   
 
 
 
 
'. 
 
 
       (       D) ) ) ) )7 ) ) )
, , , , ,!: , , ,
	D 	Xc] 	 	 	 	
 
 
 
 
) 
 
 
               &) ) ) ) ) ) ) )*x * *b *T * * * * * *r   