+
    =i/+                        R t ^ RIt^ RIt^ RIt^ RIt^ RIt^ RIt^ RIHtH	t	 ^ RI
Ht ^ RIHtHtHtHtHtHtHtHt ^ RIt^ RIHt . R!Ot]! 4       t]! ]! ]R]P:                  P<                  4      4      t]! R	]	R
7      t R R lt!R R lt"R R lt#R R lt$R R lt% ! R R]&4      t'R R lt(R R lt)R R lt*R R lt+ ! R R]4      t,R R  lt-R# )"z=
Decorators to add docstrings to enum members from comments.
N)EnumEnumMeta)dedent)IterableIteratorListOptionalSequenceTupleTypeVarUnion)PythonLexerDocumentedEnumMultipleDocstringsWarningps1EnumType)boundc                F    V ^8  d   QhR\         R\        \        ,          /#    linereturn)strr   r
   )formats   "{/Users/tonyclaw/.openclaw/workspace/scripts/youtube-playlists/venv/lib/python3.14/site-packages/enum_tools/documentation.py__annotate__r   ;   s     & &S &T%[ &    c                >    \        \        P                  V 4      4      # )zo
Returns a list ot tokens generated from the given Python code.

:param line: Line of Python code to tokenise.
)list_lexer
get_tokensr   s   &r   r    r    ;   s     	Vt$%%r   c                Z    V ^8  d   QhR\         P                  R\        \        ,          /# )r   exprr   )astExprr   r   )r   s   "r   r   r   E   s"      sxx HSM r   c                >   V P                   p\        V\        P                  4      '       d.   \        VP                   \        4      '       d   VP                   pM/\        V\        P
                  4      '       d   VP                  pMR# \        P                  ! V4      # )z
Check if the expression is a docstring.

:param expr:

:returns: The cleaned docstring text if it is a docstring, or :py:obj:`None` if it isn't.
N)	value
isinstancer$   Constantr   Strsinspectcleandoc)r#   docstring_nodetexts   &  r   _docstring_from_exprr0   E   sn     **~s||,,N<P<PRU1V1V			$))			$ 
r   c                    V ^8  d   QhR\         R\        \        P                  \        P                  3,          R\
        \         ,          /# r   sourcenoder   r   r   r$   Assign	AnnAssignr   )r   s   "r   r   r   [   s<      
cjj#--'( }r   c                   \        V P                  R4      VP                  ^,
          ,          4      p\        V4       Uu. uF%  q3P                  \
        P                  8X  g   K#  VNK'  	  ppV'       dh   \        P                  ! RV^ ,          P                  4       F;  pVP                  ^4      '       g   K  VP                  ^4      P                  4       u # 	  R# u upi )z
Search for an end-of-line docstring comment (starts with ``# doc:``).

:param source: The source of the Enum class.
:param node: The AST node for the Enum member.

(doc:\s*)([^#]*)(#|$)N)_tokenize_linesplitlinenor   typetokenizeCOMMENTrefinditerstringgrouprstrip)r3   r4   toksxcomment_toksmatchs   &&    r   _docstring_from_eol_commentrJ   [   s     	v||D)$++/:; JEJq&&H4D4D*DJE{{3\!_5K5KLekk!nn;;q>  "" M 	 Fs     C%Cc                    V ^8  d   QhR\         R\        \        P                  \        P                  3,          R\
        \         ,          /# r2   r5   )r   s   "r   r   r   o   s<      
cjj#--'( }r   c                ~   \        VP                  ^,
          ^ R4       F  pV P                  R4      V^,
          ,          pVP                  4       '       g   K:   \	        V4      p\        T4       Uu. uF%  qUP                  \
        P                  8X  g   K#  TNK'  	  ppT'       dj   \        P                  ! RT^ ,          P                  4       F=  pTP                  ^4      '       g   K  TP                  ^4      P                  4       u u # 	   R# 	  R#   \
        P                  \        3 d      R# i ; iu upi )z
Search for a Sphinx-style docstring comment (starts with ``#:``).

:param source: The source of the Enum class.
:param node: The AST node for the Enum member.
r9   Nz(#:\s*)(.*))ranger=   r<   stripr;   r?   
TokenErrorSyntaxErrorr   r>   r@   rA   rB   rC   rD   rE   )r3   r4   offsetr   rF   rG   rH   rI   s   &&      r   _docstring_from_sphinx_commentrS   o   s     T[[1_a,V	d	FQJ	'$	ZZ\\$D
 #4jGjFFh6F6F,F11j<G^\!_-C-CDA[[^""$$ E # -& 	 
,  Hs   D2 D:D:D76D7c                Z    V ^8  d   QhR\         R\        \        P                  ,          /# r   )r   r   r?   	TokenInfo)r   s   "r   r   r      s%     
; 
; 
;h&8&8!9 
;r   c                r   a  R V 3R llp\        \        P                  ! V! 4       P                  4      4      # )z=
Tokenize a single line of Python source code.

:param line:
c                :    V ^8  d   QhR\         \        ,          /# r   r   )r   r   )r   s   "r   r   $_tokenize_line.<locals>.__annotate__   s      (3- r   c               3      <"   S x  R # 5iN r!   s   r   yielder_tokenize_line.<locals>.yielder   s     *s   
)r   r?   generate_tokens__next__)r   r]   s   f r   r;   r;      s-      	X%%gi&8&89::r   c                   X   a  ] tR t^t o RtR	V 3R lR lltV 3R lR ltV 3R ltRtV t	R# )
r   z
Warning emitted when multiple docstrings are found for a single Enum member.

.. versionadded:: 0.8.0

:param member:
:param docstrings: The list of docstrings found for the member.
c                6   < V ^8  d   QhRS[ RS[S[,          /# r   member
docstringsr   r   r   )r   __classdict__s   "r   r   &MultipleDocstringsWarning.__annotate__   s      D hsm r   c                    Wn         W n        R # r[   )rd   re   )selfrd   re   s   &&&r   __init__"MultipleDocstringsWarning.__init__   s    +/r   c                    < V ^8  d   QhRS[ /# rX   )r   )r   rg   s   "r   r   rh      s     K Kc Kr   c                    R P                  V P                  P                  P                  V P                  P                  P                  V P                  P
                  .4      pRV R2# ).z+Found multiple docstrings for enum member <>)joinrd   	__class__
__module____name__name)rj   member_full_names   & r   __str__!MultipleDocstringsWarning.__str__   s\    XXKK$$KK""KK 
 77G6H	JJr   c                B   < V ^8  d   Qh/ S[ ;R&   S[S[,          ;R&   # rc   rf   )r   rg   s   "r   r   rh      s"      
  c] r   )re   rd   N)r\   )
rt   rs   __qualname____firstlineno____doc__rk   rw   __annotate_func____static_attributes____classdictcell__rg   s   @r   r   r      s'      K K)  r   c                0    V ^8  d   QhR\         R\         /# )r   an_enumr   )r   )r   s   "r   r   r      s     e e8 e er   c           
     6   \        V \        4      '       g   \        R\        V 4       R24      h\        '       g   V # \        \        P                  ! V 4      4      p\        P                  ! V4      p\        VP                  4      ^8X  g   Q hVP                  ^ ,          p\        V\        P                  4      '       g   Q hVP                  p\        V4       EF:  w  rV. p\        V\        P                  4      '       dR   VP                   F@  p\        V\        P                   4      '       g   Q hVP#                  VP$                  4       KB  	  Mt\        V\        P&                  4      '       dS   \        VP(                  \        P                   4      '       g   Q hVP#                  VP(                  P$                  4       MK  \        V\        P                  \        P&                  34      '       g   Q hV^,           \        V4      8X  d   Rp	MWE^,           ,          p	. p
\        V	\        P*                  4      '       d   V
P#                  \-        V	4      4       V
P#                  \/        W4      4       V
P#                  \1        W4      4       \3        \5        RV
4      4      p\        V4      ^8  d1   \6        P8                  ! \;        \=        W^ ,          4      V4      4       V'       g   EK  V^ ,          pV F  pV\=        W4      n        K  	  EK=  	  V # )a)  
Document all members of an enum by parsing a docstring from the Python source..

The docstring can be added in several ways:

#. A comment at the end the line, starting with ``doc:``:

   .. code-block:: python

       Running = 1  # doc: The system is running.

#. A comment on the previous line, starting with ``#:``. This is the format used by Sphinx.

   .. code-block:: python

       #: The system is running.
       Running = 1

#. A string on the line *after* the attribute. This can be used for multiline docstrings.

   .. code-block:: python

       Running = 1
       """
       The system is running.

       Hello World
       """

If more than one docstring format is found for an enum member
a :exc:`MultipleDocstringsWarning` is emitted.

:param an_enum: An :class:`~enum.Enum` subclass
:type an_enum: :class:`enum.Enum`

:returns: The same object passed as ``an_enum``. This allows this function to be used as a decorator.
:rtype: :class:`enum.Enum`

.. versionchanged:: 0.8.0  Added support for other docstring formats and multiline docstrings.
!'an_enum' must be an 'Enum', not !N) r(   r   	TypeErrorr>   INTERACTIVEr   r,   	getsourcer$   parselenbodyClassDef	enumerater6   targetsNameappendidr7   targetr%   r0   rJ   rS   r   filterwarningswarnr   getattrr|   )r   func_sourcefunc_source_treemodule_body
class_bodyidxr4   r   t	next_nodedocstring_candidatesdocstring_candidates_nn	docstringr   s   &             r   document_enumr      sO   T 	7H%%5d7m_AFGG	.g''01IIk*!!"a'''$$Q';----J'YS'cjj!!LLqa""""NN144  $&&
T[[#((
+
++
+
>>$++..!	D3::s}}5	6	66	6 	1WJ9'"9	388$$3I>? 9+LM <[OP .B!CD	 !A%==*77AJ+GI`ab&q)9v'0GG$ U (Z 	r   c                (    V ^8  d   QhR\         RR/# )r   enum_memberr   N)r   )r   s   "r   r   r   "  s     3 3 3$ 3r   c                   \        V \        4      '       g   \        R\        V 4       R24      h\        '       g   R# \        \        P                  ! V P                  4      4      pRpRpVP                  R4       EFf  p\        V4      w  rTVP                  R4      '       g	   V'       g   K2  \        V4      p\        W6V4      pV P                  V9  d   K\  V^ ,          ^ ,          \        P                   P"                  P$                  9   d   V^ ,          ^,          R9   d   V'       * pV^ ,          ^ ,          \        P                   P&                  9   d   V'       d   K  V^ ,          ^ ,          \        P                   P&                  9  d   EK  WS8  d   EK  \)        V4      w  rxV F4  p	V	P                  R4      '       d   K  WP                  8X  g   K.  Wn        K6  	  EKi  	  R# )	z
Document a member of an enum by adding a comment to the end of the line that starts with ``doc:``.

:param enum_member: A member of an :class:`~enum.Enum` subclass
r   r   NFr9   class@   """''')r(   r   r   r>   r   r   r,   r   rr   r<   get_dedented_line
startswithr    get_base_indentru   pygmentstokenLiteralStringr   parse_tokensr|   )
r   r   in_docstringbase_indentr   indent
all_tokens	enum_varsdocvars
   &         r   document_memberr   "  su    	;%%5d;6G5HJKK	g''(=(=>?t$T"4(,&	__WT$*@+ T!]1//666mA.(##L]1,,,!}Qx~~222
+.)c
..


	 7 %B 	r   c                v    V ^8  d   QhR\         R,          R\        \        \        \        ,          3,          /# )r   r   zpygments.Tokenr   )r   r
   r   r   r   )r   s   "r   r   r   X  s/      X&67 E$QTBU<V r   c                   . pRpRpV  Ft  pV^ ,          \         P                  P                  9   d   VP                  V^,          4       KC  V^ ,          \         P                  P                  9   g   Kk  V^,          p M	  \
        P                  ! RV4       F=  pVP                  ^4      '       g   K  VP                  ^4      P                  4       p W3# 	  W3# )z
Parse the tokens representing a line of code to identify Enum members and ``doc:`` comments.

:param all_tokens:

:return: A list of the Enum members' names, and the docstring for them.
N r:   )	r   r   r   r   CommentrA   rB   rD   rE   )r   r   r   commentr   rI   s   &     r   r   r   X  s     U
1X$$$E!HQx8>>)))1X7  kk2G<U
[[^^	Q			 3 =
 	r   c          	          V ^8  d   QhR\         \        ,          R\        \        ,          R\        R\         \        ,          /# )r   r   r   r   r   )r   intr	   )r   s   "r   r   r   t  s=      }x   }	r   c                v   V '       g   V^ ,          ^ ,          \         P                  P                  P                  9   d   V^ ,          ^,          R9   d   Tp V # V^ ,          ^ ,          \         P                  P                  9   d   Tp V # V^ ,          ^ ,          \         P                  P
                  9   d   Tp V # )a  
Determine the base level of indentation (i.e. one level of indentation in from the ``c`` of ``class``).

:param base_indent: The current base level of indentation
:param all_tokens:
:param indent: The current level of indentation

:returns: The base level of indentation
r   )r   r   r   r   Keywordr   )r   r   r   s   &&&r   r   r   t  s     	]1//666mA.(K 	 !}Q8>>111; 	 !}Q8>>...;r   c                   *   a  ] tR tRt o RtR tRtV tR# )r   i  z
An enum where docstrings are automatically added to members from comments starting with ``doc:``.

.. note:: This class does not (yet) support the other docstring formats :deco:`~.document_enum` does.
c                    \        V 4       R # r[   )r   )rj   r'   s   &&r   rk   DocumentedEnum.__init__  s
    $r   r\   N)rt   rs   rz   r{   r|   rk   r~   r   r   s   @r   r   r     s      r   c                R    V ^8  d   QhR\         R\        \        \         3,          /# r   )r   r
   r   )r   s   "r   r   r     s"      C E#s(O r   c                t    \        V 4      p\        V 4      \        V4      ,
          pVP                  4       p W 3# )zq
Returns the line without indentation, and the amount of indentation.

:param line: A line of Python source code
)r   r   rO   )r   dedented_liner   s   &  r   r   r     s6     
d)c-(
(r   )r    r   r   r   r   r   r   r   ).r|   r$   r,   rA   sysr?   r   enumr   r   textwrapr   typingr   r   r   r   r	   r
   r   r   pygments.tokenr   pygments.lexers.pythonr   __all__r   boolr   flagsinteractiver   r   r    r0   rJ   rS   r;   UserWarningr   r   r   r   r   r   r   r\   r   r   <module>r      s   .   	 
     V V V  .	 
73syy'<'<=>:X.&,(B
;K K:eP3l86T r   