
    lKj                        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mZmZ ddl	m
Z
 ddlmZmZ ddlmZmZmZmZ ddlmZmZ ddlmZmZmZ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%m&Z&m'Z'm(Z(m)Z)m*Z* dd
l+m,Z,m-Z-m.Z.m/Z/m0Z0m1Z1 ddl2m3Z3m4Z4m5Z5m6Z6m7Z7m8Z8m9Z9 ddl:m;Z;m<Z< ddl=m>Z> ddl?m@Z@mAZAmBZBmCZC ddlDmEZEmFZFmGZGmHZH erddlImJZJ  ed       G d d             ZKy)z)Argument class and related functionality.    N)CallableSequence)suppress)partialreduce)TYPE_CHECKINGAnyget_args
get_origin)definefield)_validate_json_extra_keysconvertinstantiate_from_dicttoken_count)ITERABLE_TYPEScontains_hintget_annotated_discriminatorget_hint_nameis_attrsis_dataclassis_enum_flagis_namedtupleis_nonetypeis_pydanticis_typeddictis_unionresolveresolve_annotatedresolve_optional)CoercionErrorCycloptsErrorMissingArgumentErrorMixedArgumentErrorRepeatArgumentErrorValidationError)	FieldInfo_attrs_field_infos_generic_class_field_infos_pydantic_field_infos_typed_dict_field_infosget_field_infossignature_parameters)ITERATIVE_BOOL_IMPLICIT_VALUE	Parameter)Token)UNSETgrouper
is_builtinparse_version   )enum_flag_from_dictget_choices_from_hintmissing_keys_factory
startswithArgumentCollectionT)kw_onlyc                   ^   e Zd ZU dZ ee      Zee   ed<   	  ee	      Z
e	ed<   	  ee      Zeed<   	  eee      Zeed<   	  ed	      Zedz  ed
<   	  ed	      Zeedf   ed<   	  ede      Zeed<   	  eddd      Zeed<    eddd      Zeed<    eedd      Zeee	f   ed<    edd      Zded<   	  eddd      Zeed<    eddd      Zeed<    eddd      Ze dz  ed<    eddd      Z!e dz  ed<    eddd      Z"edz  ed<    eedd      Z#ded <   	 d! Z$d"eee	f   fd#Z%e&d$        Z'e'jP                  d%        Z'e&d&        Z)e)jP                  defd'       Z)e&d(efd)       Z*e&d(eez  e egef   z  fd*       Z+e&d(efd+       Z,d,efd-Z-dZde.eez     dz  d(efd.Z/	 d[de.eez     ez  ez  dz  deedf   d(efd/Z0dd0d1d2eez  d3e egef   dz  d4ed(eeedf   ef   fd5Z1d6eedf   d(eedf   fd7Z2dd0d1d2ed3e egef   dz  d4ed(eeedf   ef   fd8Z3d
ed(eeedf   ef   fd9Z4d:efd;Z5e&d(efd<       Z6e&d\d=       Z7d> Z8dZd?e dz  fd@Z9dZd?e dz  fdAZ:dB Z;dZd?e dz  fdCZ<d]deedf   fdDZ=e&dE        Z>e&dF        Z?e&d(efdG       Z@e&d(eedf   fdH       ZAdZded4edz  d(ee   fdIZBe&d(efdJ       ZCe&d(efdK       ZDe&d(efdL       ZEd(efdMZFd(efdNZGd(efdOZHd^dPed(eedf   dz  fdQZId(efdRZJd_dSZKd`dTZLdadUZMdbdVZNdcdWZOdX ZPdY ZQy)dArgumentzEncapsulates functionality and additional contextual information for parsing a parameter.

    An argument is defined as anything that would have its own entry in the help page.
    )factorytokens
field_info	parameter)default	converterhintN)rC   index .keysvalue)aliasrC   _valueF)rC   initrepr_accepts_keywords_default)r?   rL   rM   _lookup)rL   rM   r;   children_marked_converted_mark_converted_override_missing_keys_checker_internal_converter_enum_flag_typez&list[tuple[Any, dict[str, FieldInfo]]]_union_branchesc                 	   ddl m}  |       | _        t        | j                        }t        |      rt        |      n|f}| j                  j                  rTt        |      }|t        u s(|t        u s9t        |t              rt        |t              st        d| j                   d      | j                  j                   r!| j                  j"                  rt        d      | j$                  s| j&                  j(                  | j&                  j*                  u }| j&                  j,                  | j&                  j.                  u}|s%|s#t        d| j&                  j0                   d      y | j                  j2                  du ry |D ]  }t5        |      }||h}t7        |      }	t8        |v r\d	| _        t<        t<        }}
t        |      }t?        t@              5  |d   }
|d
   }d d d        |
t<        urtC        d      || _"        ntG        |      r.tI        tJ              | _&        d	| _        | jO                  |	       nutQ        |      r.tI        tR              | _&        d	| _        | jO                  |	       n<tU        |      rDtI        tR              | _&        d	| _        tW        |d      st        d      | jO                  |	       ntY        |      r-tI        tZ              | _&        d	| _        | jO                  |	       nt]        |      r-tI        t^              | _&        d	| _        | jO                  |	       n}ta        |      r || _1        d	| _        | jO                  |	       nRte        |      s/|	r-tI        tR              | _&        d	| _        | jO                  |	       n| j                  j2                  0| j                  j2                  Hd	| _        tI        tR              | _&        tg        ti        |jj                        jm                               D ]a  \  }}|dk(  r|j0                  dk(  r|j(                  |jn                  u r|jp                  | _"        E| jO                  |j0                  |i       c  | j:                  rLts        |      d
kD  r=|D cg c]  }t7        |      x}s||f }}ts        |      d
kD  r|| _:        d | _&        y y y y # 1 sw Y   xY wc c}w )Nr   r:   z5Parameter(count=True) requires an int type hint, got zA. Use 'Annotated[int, Parameter(count=True)]' for counting flags.zParameter(requires_equals=True) and Parameter(consume_multiple=...) cannot be used together. requires_equals enforces '--option=value' syntax, which is incompatible with consume_multiple's space-separated value consumption.zNon-parsed parameter 'zD' must be a KEYWORD_ONLY function parameter or have a default value.FTr5   z1Dictionary type annotations must have "str" keys.__annotations__zGCyclopts cannot handle collections.namedtuple without type annotations.self);cyclopts.argument._collectionr;   rQ   r   rE   r   r
   rB   countr    boolint
isinstancetype
issubclass
ValueErrorrequires_equalsconsume_multipleparserA   kindKEYWORD_ONLYrC   emptynameaccepts_keysr   r,   dictrN   strr   
IndexError	TypeErrorrO   r   r8   r+   rT   _update_lookupr   r)   r   hasattrr   r(   r   r*   r   rV   r3   	enumerater-   __init__valuesVAR_KEYWORD
annotationlenrW   )rZ   r;   rE   hintsresolved_hintis_keyword_onlyhas_defaultoriginhint_originfield_infoskey_typeval_typeargsirA   memberfisbranchess                     l/Users/ahmed/devFolder/Ultron/claude-voice/.venv/lib/python3.12/site-packages/cyclopts/argument/_argument.py__attrs_post_init__zArgument.__attrs_post_init__   sA   D*,tyy!"*4.tg>>,T2M$$M4)HZXegjMk KDII; WV W 
 >>))dnn.M.MH  zz"oo22doo6R6RRO//119N9NNK#{ ,T__-A-A,B C/ /  >>&&%/D%F.K)$/K{")-&%(#(~j)#AwH#AwH * 3&#$WXX (d#-ABY-Z*)-&##K0d#-AB\-]*)-&##K0t$-AB\-]*)-&t%67$%noo##K0$-ABT-U*)-&##K0T"-ABW-X*)-&##K0d#'+$)-&##K0%+-AB\-]*)-&##K0,,4~~**2%)D")=>X)YD&!*+?+N+U+U+W!X:6joo7??j&<&<<$.$9$9DM''*(EF "Yk z !!c%j1n 5:^E&_U[E\>\c>\EH^8}q '/$ .2* ! '5!i *)p _s   SS%0S%S"	r}   c                    ddl m} t        | j                  j                        }|j                         D ]  \  }}| j                  j                  |      x}r`||k(  r)|rR||j                  v rD||j                  v r6||j                  |j                  f   |_        t        j                  |_        }t        || j                  |<    y )Nr   )Literal)typingr   r   rA   ru   itemsrP   getnamesr'   rh   rC   NotImplementedError)rZ   r}   r   discriminatorkeyrA   existing_field_infos          r   ro   zArgument._update_lookup%  s    "3DOO4N4NO*002OC&*ll&6&6s&;;";&*4"}
8H8H'H]^q^w^wMw5<=P=[=[]g]r]r=r5s'22;//'/--$.S!  3    c                     | j                   S )zConverted value from last :meth:`convert` call.

        This value may be stale if fields have changed since last :meth:`convert` call.
        :class:`.UNSET` if :meth:`convert` has not yet been called with tokens.
        )rK   rZ   s    r   rI   zArgument.value6  s     {{r   c                 F    | j                   rd| _        d| _         || _        y )NT)_markedrS   rK   )rZ   vals     r   rI   zArgument.value?  s    <<,0D)r   c                 4    | j                   | j                  z  S )zdIf ``True``, then this node in the tree has already been converted and ``value`` has been populated.)rR   rS   r   s    r   r   zArgument._markedF  s     %%(E(EEEr   c                     || _         y N)rR   )rZ   rI   s     r   r   zArgument._markedK  s
    !&r   returnc                     t        | j                        rt        | j                        n| j                  f}t        d |D              S )Nc              3   B   K   | ]  }t         |t        |      fv   y wr   )rk   r   ).0args     r   	<genexpr>z7Argument._accepts_arbitrary_keywords.<locals>.<genexpr>R  s     BTc4CC11Ts   )r   rE   r
   any)rZ   r   s     r   _accepts_arbitrary_keywordsz$Argument._accepts_arbitrary_keywordsO  s4    &.tyy&9x		"		|BTBBBr   c                    | j                   ry| j                  j                  .| j                  j                  d| j                  j
                  fvS t        | j                  j                  t              r| j                  j                  S | j                  j                  | j                  j
                  u s| j                  j                  sy| j                  j                  S )z(Show the default value on the help page.FN)requiredrB   show_defaultrA   rC   rh   r_   rl   r   s    r   r   zArgument.show_defaultT  s     ==^^((0??**49N9N2OOO33S9>>...oo%%)>)>>t~~GbGb>>...r   c                     t        t        | j                        xs] t        | j                        xrF t	        d t        | j                        D              xs t        | j                  j                              S )Nc              3   2   K   | ]  }t        |        y wr   )r   r   xs     r   r   z6Argument._use_pydantic_type_adapter.<locals>.<genexpr>i  s     D0C1A0Cs   )	r]   r   rE   r   r   r
   r   rA   ru   r   s    r   _use_pydantic_type_adapterz#Argument._use_pydantic_type_adapterb  s`    		" # D0CDD O24??3M3MN	
 		
r   r   c                     	 | j                   |   j                  S # t        $ r | j                   | j                  cY S w xY wr   )rP   ru   KeyErrorrO   )rZ   r   s     r   _type_hint_for_keyzArgument._type_hint_for_keyo  sB    	!<<$/// 	!}}$== 	!s    "A A c                    || j                   }|syt        |d   t              r|d   j                  n|d   }|j	                         j                  d      sy| j                  rR| j                  j                  | j                  j                  S t        | j                  j                  t              ryyt        | j                        }t        |      }|t         v rt#        |      }|r|d   t        uryy)zEWhen parsing, should attempt to parse the token(s) as json dict data.Fr   {T)r@   r_   r0   rI   stripr9   rN   rB   	json_dictr   rA   ru   rl   r   rE   r   r   r
   )rZ   r@   rI   rE   r{   r   s         r   _should_attempt_json_dictz"Argument._should_attempt_json_dictw  s    >[[F#-fQi#?q	VAY{{}'',!!~~''3~~///T__77=tyy!D!^#D>DQs*r   c                    || j                   }|sy| j                  |      \  }}|syt        |t              r|j                  }n:t        |t
              r|}n't        |d   t              r|d   j                  n|d   }|j                         j                  d      sy| j                  j                  | j                  j                  S t        | j                        xs t
        fD ]  }t        |t
              s y y)zEWhen parsing, should attempt to parse the token(s) as json list data.Fr   [T)r@   r   r_   r0   rI   rl   r   r9   rB   	json_listr
   rE   r   )rZ   r@   rH   _consume_allrI   r   s          r   _should_attempt_json_listz"Argument._should_attempt_json_list  s     >[[F))$/;fe$LLE$E'1&)U'CF1IOOPQE{{}'',>>##/>>+++DII&03&0CS#& 1 r   .	transform	delimitertermr   r   c                    | j                   st        t        |t              r| j	                  |      S | j                  |||      S )a  Match a name search-term, or a positional integer index.

        Raises
        ------
        ValueError
            If no match is found.

        Returns
        -------
        tuple[str, ...]
            Leftover keys after matching to this argument.
            Used if this argument accepts_arbitrary_keywords.
        Any
            Implicit value.
            :obj:`~.UNSET` if no implicit value is applicable.
        r   )re   rb   r_   r^   _match_index_match_name)rZ   r   r   r   s       r   matchzArgument.match  sN    . zz $$ d#	
 !!$)y!Q	
r   trailingc                 F   | j                   j                  }||s|S t        | j                        }g }d}|t	        |      k  rD||   }t        |      }t        |      t        u r;|j                  |       t        |      }t	        |      dkD  r|d   nt        }|dz  }ki }	 t        |      }|s |j                  ||d        	 t'        |      S i }	|j                         D ]:  \  }
}|j                  D ]&  }|	j!                   ||      |
|j"                  f       ( < |	j%                  |      }| |j                  ||d        	 t'        |      S |\  }
}|j                  |
       t        |      }|dz  }|t	        |      k  rDt'        |      S # t        $ r Y w xY w)u  Map kebab-case segments back to their canonical Python field names.

        Walks the type hint segment-by-segment:

        * Dynamic ``dict`` keys pass through unchanged (advance to the value type).
        * Segments addressing a structured type (pydantic / dataclass / attrs /
          TypedDict / NamedTuple) are looked up in a ``{name_transform(name): name}``
          map built from the type's field_infos; on hit, the segment is replaced
          with the canonical name and the walk advances to that field's annotation.
        * On miss or when the hint is unwalkable (plain scalar, unresolved forward
          ref, etc.) remaining segments pass through unchanged — this preserves the
          existing raw-snake_case behavior as a backward-compat fallback.
        Nr   r5   )rB   name_transformr   rE   rv   r    r   rk   appendr
   rl   r,   	Exceptionextendr   r   
setdefaultru   r   tuple)rZ   r   r   rE   outr   segmentr   r}   name_mapcanonical_namefirJ   r   	next_hints                  r   _normalize_trailing_keysz!Argument._normalize_trailing_keys  s    66!O tyy!#h-qkG#D)D$4'

7#~"%d)a-tAwSQK-d3 

8AB<(( Sz 46H&1&7&7&9"XXE''u(=PRP]P]?^_ & ': LL)E}

8AB<( Sz ).%NIJJ~&9%DFAI #h-L Sz1  s   $F 	F F c                   | j                   j                  | j                   j                  u rJ| j                  r>| j	                  t        |j                  d      j                  |                  t        fS |}t        }| j                  j                  st        d|      | j                  j                  D ]j  }|r ||      }t        ||      s|t        |      d }| j                  t        u s| j                  t         v rdnt        }|r|d   |k(  s_|dd } nd|fc S  | j"                  }t%        |      rt'        |      }n|f}|D ]  }t)        |      }d}	| j                  j+                  |      D ]|  }|r ||      }t        ||      s|t        |      d }|t         v rd}n/t-        |      s|d}nt/        |      } t1        |      xs |       }|r|d   |k(  sm|dd }d}	 n	d|fc c S  |	s n t        | j                  st        | j	                  t        |j                  |                  |fS )	as  Check how well this argument matches a token keyword identifier.

        Parameters
        ----------
        term: str
            Something like "--foo"
        transform: Callable
            Function that converts the cyclopts Parameter name(s) into
            something that should be compared against ``term``.

        Raises
        ------
        ValueError
            If no match found.

        Returns
        -------
        tuple[str, ...]
            Leftover keys after matching to this argument.
            Used if this argument accepts_arbitrary_keywords.
        Any
            Implicit value.
        -zNo name to match NTr   r5   rG   F)rA   rf   rt   r   r   r   lstripsplitr1   rB   ri   rb   r9   rv   rE   r]   r.   _negatives_hintr   r
   r   get_negativesr   r    r   )
rZ   r   r   r   r   implicit_valueri   rE   rw   double_breaks
             r   r   zArgument._match_name  s-   < ??4??#>#>>4CcCc00t{{37G7M7Mi7X1YZ\aaa~~""09::NN''D $%D	,)-d):diiKh>hns{i/#+AB<~-- ( ''D~ (.$ NN88>D (!$-#'D	#4#@@-2N(.$,-1N#3D#9D.Fj.>.F$-IN#'{i7+3AB</3 %#%~#55% ?&  / 2 ! //,,U8>>)3L-MNP^^^r   c                     | j                   t        | j                  j                  | j                  j                  u r|| j                   k  rt        dt
        fS || j                   k7  rt        dt
        fS NrG   )rF   rb   rA   rf   VAR_POSITIONALr1   )rZ   rF   s     r   r   zArgument._match_indexc  sj    ::__!!T__%C%CCtzz!   5y djj 5yr   tokenc                    | j                   st        t        fd| j                  D              r| j                  j
                  du rt              | j                  j                        \  }}| j                  j
                  du r<|s^| j                  D cg c]  }|j                  j                  k7  s|  c}| _        n$|s"| j                  j                  st              | j                  r>t        j                        t        d | j                  D              z  rt        |       | j                  j                         yc c}w )zSafely add a :class:`Token`.c              3   P   K   | ]  }|j                   j                   k(    y wr   )address)r   r   r   s     r   r   z"Argument.append.<locals>.<genexpr>r  s     ?;aqyyEMM);s   #&F)r   Tc              3   4   K   | ]  }|j                     y wr   )rH   r   s     r   r   z"Argument.append.<locals>.<genexpr>~  s     %Bkaffk   argumentN)re   rb   r   r@   rB   allow_repeatingr%   r   rH   r   r\   r]   r$   r   )rZ   r   r   r   r   s    `   r   r   zArgument.appendm  s    zz?4;;??~~--6)66!--ejj9NA{~~--5".2kk"XkQYY%--=W1k"XDK )=)=)66;;EJJ#%Bdkk%B"BB($775! #Ys   E;Ec                 h    t        | j                        xs t        d | j                  D              S )z@This argument, or a child argument, has at least 1 parsed token.c              3   4   K   | ]  }|j                     y wr   )
has_tokensr   s     r   r   z&Argument.has_tokens.<locals>.<genexpr>  s     'Lmmr   )r]   r@   r   rQ   r   s    r   r   zArgument.has_tokens  s'     DKK LC'Ldmm'L$LLr   c                     ddl m}  |       }| j                  D ].  }|j                  |       |j	                  |j
                         0 |S )Nr   r:   )r[   r;   rQ   r   r   children_recursive)rZ   r;   r   childs       r   r   zArgument.children_recursive  s@    D "]]EJJuJJu//0 # 
r   c                    | j                   rIdd l}| j                         }	 |j                  | j                  j
                        j                  |      S t        S # |j                  $ r}| j                  |       Y d }~y d }~ww xY w)Nr   )
r   pydantic_jsonTypeAdapterrA   ru   validate_pythonr&   !_handle_pydantic_validation_errorr1   )rZ   r   unstructured_dataes       r   _convert_pydanticzArgument._convert_pydantic  st    ?? $

:++DOO,F,FGWWXijj L ++ :66q99:s   3A B+BBrD   c           
      6    ddl m}  j                  j                  rft	         j                  j                  t
              r+t         j                   j                  j                        n> j                  j                  n'%t        t         j                  j                        J  fd j                  st        }|S  j                  j                  rt        d  j                  D              }|S  j                   swg }i } fd}t#         | j                              }|D ]  }t%         j                        }	|j&                  t        urAt	        |j&                  t)        |	      xs |	      rt+        |      dk(  sJ |j&                  c S |j,                  rW|}
|j,                  d d D ]  }|
j/                  |i       }
 |
j/                  |j,                  d   g       j1                  |       n|j1                  |       |s|st3         	       |r j4                  rx j4                  j6                   j4                  j8                  u rLt;         j                        d    j=                         \  }}t?        fd
tA        ||      D              }|S   j                  t?        |            }|S |r j4                  rz j4                  j6                   j4                  jB                  u rN j,                  sB|jE                         D ci c]%  \  }}| t;         j                        d   |      ' }}}|S   j                  |      }|S  jF                  rtI         	      t        S i }t        } jJ                  r jK                  d      } jJ                  rX j                  rL  jJ                   j                        }|t	        |t"              rtM        tN        jP                  |      n|z  } jS                         r j                  r j                  jU                  d      }	 tW        jX                  |jZ                        }ta        | j                  |        | jb                  je                  d      |i|jf                   jh                  dd        j                  r jj                  r jm                         S  j                  rP jJ                  sD j                  D cg c]  }|j,                  r| }}|r  j                  t?        |            S  j                   D ch c]  }|jn                  s|j,                  d     }} jq                  |      } j                   D ]  }t+        |j,                        t+         j,                        dz   k(  sJ ||j,                  d   |v n|jF                  }|jn                  r#|js                        ||j,                  d   <   |r!|}|j,                  D ]  }	 ||   }
 d|_;        |d|_;        |jh                  D ]	  }d|_;           jy                  |        jJ                  r8|t{         jJ                  | j                  j                        z  }|st        }|S |rs j                  } j|                  rM j                  t        |            }|/t_        dt         j                         d  j                        |}t        ||      }|S  jF                  rtI         	      t        }|S c c}}w # tV        j\                  $ r}t_        | j                        |d }~ww xY wc c}w c c}w # tt        $ r tI        |	      d w xY w)Nr   )update_argument_collection)r   c                    t        |t              r
	  | |      S 	 t        j                        r |      S  | |      S # t        t        t        f$ r/}t        |j                  r|j                  d   nd |       |d }~ww xY w# t        t        t        f$ rE}t        |      dk(  r|d   nd }t        |j                  r|j                  d   nd | |      |d }~ww xY w)Nr   msgr   target_typer5   )r   r   r   r   )
r_   rk   AssertionErrorrb   rn   r!   r   inspectismethodrv   )rE   r@   r   r   rD   rZ   s       r   safe_converterz)Argument._convert.<locals>.safe_converter  s    &$'s$T622''	2(00  )v66 '
I> s'AFF1ITTXfjkqrrs '
I> ),V)9F1ItE')*AFF1ITDVZbgs4   A B	 B	 B*BB	C"A CC"c              3   Z   K   | ]#  }|j                   t        us|j                    % y wr   )r   r1   )r   r   s     r   r   z$Argument._convert.<locals>.<genexpr>  s%     iuuG[G[chGhe**s   ++c              3   T  K   | D ]  }j                  |      r	 t        j                  |j                        }t        |t              st        |j                        |s|j                  dg        s|D ]o  }||j                  d|       t        |t              r(|j                  t        j                  |             S|j                  t        |             q |  y # t        j                  $ r}t        |j                        |d }~ww xY ww)Nr   r    )rI   r   )rI   )r   jsonloadsrI   JSONDecodeErrorr!   rE   r_   listevolverk   dumpsrl   )r@   r   parsed_jsonr   elementrZ   s        r   expand_tokensz(Argument._convert.<locals>.expand_tokens  s     #E55e<[*.**U[[*AK  *+t<"/e"SS*"',,R,"KK+6#*?*/,,RPW,*X$X%/%>*/,,TZZ=P,*Q$Q*/,,S\,*J$J ,7 $+ $  $33 ["/e"SYZZ[s(   D(C5B;D(5D%D  D%%D(r5   r   c              3   0   K   | ]  } |        y wr   rG   )r   rs   rE   r   s     r   r   z$Argument._convert.<locals>.<genexpr>  s     sKrtV <Krs   r   r   rG   F)	root_keysallow_unknownrD   TzCannot determine which z' variant the supplied fields belong to.r   )Cr[   r   rB   rD   r_   rl   getattrrE   r   r   r   re   r1   r\   sumr@   rQ   r  r    r   r   rv   rH   r   r   r$   rA   rf   r   r
   r   r   r2   rt   r   r   r#   rV   r   operatoror_r   popr  r  rI   r  r!   r   ri   r   sourcer   r   r   r   _active_branch_required_keysconvert_and_validater   r   _run_missing_keys_checkerr6   rW   _resolve_union_membersetr   r   )rZ   rD   r   r   
positionalkeywordr	  expanded_tokensr   rx   lookupr   tokens_per_elementr   rI   dataconverted_flagsr  r   positional_tokensr   supplied_keysactive_requiredchild_requiredobjk
descendanttarget_hintr   rE   r   s   ``                           @@r   _convertzArgument._convert  s   L>>##$..22C8#DIIt~~/G/GH	 NN44	8U8UVI$$$	* zzCr 
q ^^!!iiiCn 
m &(JG$0 #=#=>O( 0 ;''u4((*]*C*T}: /1444 ///::$F$zz#2!'!2!23!;  /%%ejjnb9@@G%%e,',d;;# )& ??t';';t?]?]']#DII.q1D,0,<,<,>)&s7S]_qKrssCD 
A )E*4EFC@ 
 ??t';';t?Z?Z'Zcgclcl`g`m`m`op`oR\RUW\3x		/B1/Eu MM`oCpz 
w )G<Cv 
u *D99DC##**1-##"01E1Et{{"S
?\`@avhllO<gvv--/kk KKOOA.EW&*jj&= .k499eL.))#.<//"$&+ kk ..--//{{4#7#78<$Vu5::U!$V$)$))U;L5MNN9=[%JZJZUZZ^M["??NO5::3tyy>A+=>>> GVFaB?!Bglgugu##+0+E+EPY+E+ZDB(#C"ZZQ"%a&C (
 %)EM$0 %)EM&+&>&>
-1
* '?) '. **40##*4+?+?t~~GdGdeeC* 
) "ii'' "77D	BF~+"9-		:R9SSz {%)(,		 
 #)K+K> 
 *D99
{ q.  // W+%TYYOUVVW %W \  ) Q"6"FDPQsB   "*\>] ]7]7
]<]<!^]4]//]4^c                 >   | j                   s$	 | j                  |      | _        | j                  S | j                  S # t        $ r6}|j                  | |_        |j
                  | j                  |_         d}~wt        $ r}|j                  | |_         d}~ww xY w)a0  Converts :attr:`tokens` into :attr:`value`.

        Parameters
        ----------
        converter: Callable | None
            Converter function to use. Overrides ``self.parameter.converter``

        Returns
        -------
        Any
            The converted data. Same as :attr:`value`.
        r  N)r   r)  rI   r!   r   r   rE   r"   )rZ   rD   r   s      r   r   zArgument.convert\  s     ||!]]Y]?
 zztzz ! ::%!%AJ==($(IIAM  ::%!%AJs!   = 	B1A77BBBc                    
 t         j                  j                  t              sJ dt        j
                  v r!ddl
t        
j                        }|dk  rd
nd

 fd}d }	  j                  s j                  r݉ j                  j                   j                  j                  u r j                  rt         j                        d   } j                  j                  D ]I  } |||      }t!        j"                  |      }|j%                         D ]  }|r	 ||        |||        K  |t&        t(         j                  j*                  f   |       y j                  r j                  j                   j                  j,                  u rt         j                        d   } j                  j                  D ];  } |||      }t!        j"                  |      }|D ]  }|r	 ||        |||        =  |t         j                  j*                  df   |       y j                  j                  D ]F  } || j                        }t!        j"                  |      r	 ||       4 | j                  |       H  | j                  j*                  |       y# t.        t0        t2        f$ r.}	t5        |	j6                  r|	j6                  d   nd	 
      |	d}	~	ww xY w)zValidates provided value.

        Parameters
        ----------
        value:
            Value to validate.

        Returns
        -------
        Any
            The converted data. Same as :attr:`value`.
        r   r   N)   c                     sy j                   ry 	 j                  |       j                  |       y # j                  $ r}j	                  |       Y d }~y d }~wj
                  $ r Y y w xY wr   )r   r   r   r&   r   PydanticUserError)rE   r   r   r   rZ   s      r   validate_pydanticz,Argument.validate.<locals>.validate_pydantic  sk    ..$$T*::3?++ :66q99-- s    4 A.AA.-A.c                 >    t        | t              rt        ||       } | S r   )r_   rl   r  )	validatorrE   s     r   _resolvez#Argument.validate.<locals>._resolve  s    )S)#D)4	r   r5   .r   exception_messager   )r_   rB   r1  r   sysmodulesr   r4   __version__rH   rA   rf   rt   r   r
   rE   r   r   rs   rk   rl   ru   r   r   rb   rn   r&   r   )rZ   rI   pydantic_versionr/  r2  rE   r1  	is_methodr   r   r   s   `         @r   validatezArgument.validatey  sX    $..22E::: $,X-A-AB$&H		
%	gIIOOOO((DOO,G,GG44		*1-!%!9!9I (D 9I ' 0 0 ;I$||~$%cN%dC0	  . ": "$sDOO,F,F'F"GOT__%9%9T__=[=[%[		*1-!%!9!9I (D 9I ' 0 0 ;I$$%cN%dC0	  % ": "%(B(BC(G"H%P!%!9!9I (DII >I''	2!%(!$))U3 ": "$//"<"<eD
I6 	g!AFF1IRZ^_eff	gs'   (C4J% C
J% (A<J% %K'9)K""K'c                     | j                  |      }|t        ur| j                  |       |S | j                  j                  t
        j                  ur%| j                  | j                  j                         |S )a>  Converts and validates :attr:`tokens` into :attr:`value`.

        Parameters
        ----------
        converter: Callable | None
            Converter function to use. Overrides ``self.parameter.converter``

        Returns
        -------
        Any
            The converted data. Same as :attr:`value`.
        r  )r   r1   r:  rA   rC   r'   rh   )rZ   rD   r   s      r   r  zArgument.convert_and_validate  sb     llYl/eMM# 
 __$$IOO;MM$//112
r   c                 F   | j                   j                  ry| j                   j                  | j                   j                  dk(  ryt        |      dkD  r| j                  }n/t        |      dk(  r| j                  |d         }n| j                  }t        |      \  }}| j                   j                  |fS t        |      dkD  r| j                  }n>t        |      dk(  r| j                  |d         }n| j                  }| j                  r|syt        |      \  }}||fS )a  The number of string tokens this argument consumes.

        Parameters
        ----------
        keys: tuple[str, ...]
            The **python** keys into this argument.
            If provided, returns the number of string tokens that specific
            data type within the argument consumes.

        Returns
        -------
        int
            Number of string tokens to create 1 element.
        consume_all: bool
            :obj:`True` if this data type is iterable.
        r   Fr
  )r5   Tr5   r   )	rB   r\   n_tokensrv   rO   r   rE   r   rV   )rZ   rH   rE   r   consume_all_from_typer  r   s          r   r   zArgument.token_count  s   " >>
 >>"".~~&&", t9q===DY!^2247;D99D ,7t+<((~~..0EEEt9q===DY!^**473D99D##D*5d*;'K!;..r   c                    | j                   j                  }|t        j                  j                  u st        |      t        u r?| j                   j                  }|t        j                  j                  ur|t        |      }t        |      S r   )
rA   ru   r   r/   rh   r   r	   rC   r`   r   )rZ   rE   rC   s      r   r   zArgument._negatives_hint  sn     ))7$$***gdms.Boo--Gg//555':MG} &&r   c                 L    | j                   j                  | j                        S )z5Negative flags from :meth:`.Parameter.get_negatives`.)rB   r   r   r   s    r   	negativeszArgument.negatives!  s     ~~++D,@,@AAr   c                      | j                   d   S )z2The **first** provided name this argument goes by.r   )r   r   s    r   ri   zArgument.name&  s     zz!}r   c                     ddl }t        | j                  j                  t              sJ t	        |j                  | j                  j                  | j                              S )z8Names the argument goes by (both positive and negative).r   N)	itertoolsr_   rB   ri   r   chainrB  )rZ   rE  s     r   r   zArgument.names+  sE     	$..--u555Y__T^^%8%8$..IJJr   c                 R    | j                   j                  | j                  ||      S )z:Split a given value with :meth:`.Parameter.env_var_split`.)r   )rB   env_var_splitrE   )rZ   rI   r   s      r   rH  zArgument.env_var_split3  s"    ~~++DIIu	+RRr   c                     | j                   ry| j                  j                  | j                  j                  S | j                  j                  s| j                  j
                  sy| j                  S )zShow this argument on the help page.

        If an argument has child arguments, don't show it on the help-page.
        Returns False for arguments that won't be parsed (including underscore-prefixed params).
        F)rQ   rB   showri   rA   is_positional_onlyre   r   s    r   rJ  zArgument.show7  sT     ==>>*>>&&&~~""4??+M+Mzzr   c                 N   | j                   j                  yt        | j                   j                  t        j                        rBt        | j                   j                  j                  | j                  j                              S t        | j                   j                        S )zWhether this argument should be parsed from CLI tokens.

        If ``Parameter.parse`` is a regex pattern, parse if the pattern matches
        the field name; otherwise don't parse.
        T)	rB   re   r_   rePatternr]   searchrA   ri   r   s    r   re   zArgument.parseI  sn     >>'dnn**BJJ7,,33DOO4H4HIJJDNN(())r   c                     | j                   j                  | j                  j                  S | j                   j                  S )z<Whether or not this argument requires a user-provided value.)rB   r   rA   r   s    r   r   zArgument.requiredV  s4     >>""*??+++>>***r   c                 .    | j                   j                  S r   )rA   rK  r   s    r   rK  zArgument.is_positional_only^  s    111r   c                 \    | j                   j                  | j                   j                  k(  S r   )rA   rf   r   r   s    r   is_var_positionalzArgument.is_var_positionala  s!    ##t'E'EEEr   c                 (    | j                         dk(  S )a  Check if this argument is a flag (consumes no CLI tokens).

        Flags are arguments that don't consume command-line tokens after the option name.
        They typically have implicit values (e.g., `--verbose` for bool, `--no-items` for list).

        Returns
        -------
        bool
            True if the argument consumes zero tokens from the command line.

        Examples
        --------
        >>> from cyclopts import Parameter
        >>> bool_arg = Argument(hint=bool, parameter=Parameter(name="--verbose"))
        >>> bool_arg.is_flag()
        True
        >>> str_arg = Argument(hint=str, parameter=Parameter(name="--name"))
        >>> str_arg.is_flag()
        False
        r=  )r   r   s    r   is_flagzArgument.is_flagd  s    * !Z//r   forcec                     |s| j                   j                  syt        | j                  | j                   j                        }|rt        |      S dS )a*  Extract completion choices from type hint.

        Extracts choices from Literal types, Enum types, and Union types containing them.
        Respects the Parameter.show_choices setting unless force=True.

        Parameters
        ----------
        force : bool
            If True, return choices even when show_choices=False.
            Used by shell completion to always provide choices.

        Returns
        -------
        tuple[str, ...] | None
            Tuple of choice strings if choices exist and should be shown, None otherwise.

        Examples
        --------
        >>> argument = Argument(hint=Literal["dev", "staging", "prod"], parameter=Parameter(show_choices=True))
        >>> argument.get_choices()
        ('dev', 'staging', 'prod')
        >>> argument = Argument(hint=Literal["dev", "staging", "prod"], parameter=Parameter(show_choices=False))
        >>> argument.get_choices()  # Returns None for help text
        >>> argument.get_choices(force=True)  # Returns choices for completion
        ('dev', 'staging', 'prod')
        N)rB   show_choicesr7   rE   r   r   )rZ   rV  choicess      r   get_choiceszArgument.get_choices{  sA    6 T^^88'		4>>3P3PQ!(uW~2d2r   c                    i }| j                   rs| j                  D ]d  }|}|j                  dd D ]  }|j                  |i       } |j                  t
        u r|j                  n|j                  ||j                  d   <   f | j                  D ]  }d|_        |j                  s|j                  t        | j                        d }|j                   r|j                         }|sY|||d   <   bt        |j                        xs |j                  t        v r|j                  D ]  }|j                  t
        ur/|j                  |d   g       j                  |j                         D|j                  }t!        |t"              r;|j%                         r+|j%                         d   dv r	 t'        j(                  |      }|j                  |d   g       j-                  |        Z|j                  d   }|j                  t
        u r|j                  n|j                  ||d   <    |S # t&        j*                  $ r Y w xY w)a  Convert argument to be json-like for pydantic.

        All values will be str/list/dict. JSON-serialized strings (from sources
        like config files or environment variables) are deserialized back to their
        original dict/list structure.
        Nr
  Tr   )r   r   )rN   r@   rH   r   r   r1   rI   rQ   r   r   rv   r   r   rE   r   r   r_   rl   r   r  r  r  r   )	rZ   r   r   noder   r   rH   resultrI   s	            r   r   zArgument._json  s    !! ::cr?C??33D +6;6J6Je6Su{{Y^YmYmUZZ^$	 %
 ]]E EM##::c$))n./D&&#)CQLUZZ(6EJJ>I"\\E++58tBx4;;E<P<PQ %%eS1ekkmVWHX\fHf%(,

5(9 tBx4;;EB * Q.3.B.Be.Ku{{QVQeQeDG1 #2 
 $(#7#7 % $%s   +H,,IIc                     | j                   sg S g }| j                  | |      D ]H  }| j                  |fz   }| j                  j                  |      }|j	                  ||r|d   ndf       J |S )u  Map each required-but-absent key reported by the checker to its child ``Argument``.

        Non-raising core shared by :meth:`_run_missing_keys_checker` (the conversion-time
        error path) and :meth:`_missing_children` (the read-only query path). The checker
        only inspects ``set(data)`` — the keys — so the values in ``data`` are irrelevant.

        Returns a list of ``(full_keys, argument)`` pairs in checker order; ``argument`` is
        ``None`` for a required key that maps to no Cyclopts-accessible child.
        keys_prefixr   N)rT   rH   rQ   	filter_byr   )rZ   r  r   r   rH   matcheds         r   _resolve_missing_keyszArgument._resolve_missing_keys  su     ))I--dD9C99v%Dmm--$-?GJJGgaj>? : 
r   c                     | j                   D cg c]E  \  }}|t        |      k  r2||j                         D ch c]  \  }}|j                  s| c}}fG c}}}}S c c}}w c c}}}}w )u  Branches that can fully account for ``supplied_keys`` (i.e. ``supplied ⊆ branch``).

        These are the ``Union`` members the user could be completing; a branch that doesn't
        contain every supplied field can't be the intended one. Yields ``(member, required_keys)``
        — the only branch information either caller needs. Returns ``[]`` when the supplied
        fields span multiple branches (over-supplied / ambiguous input) or when this is not a
        multi-branch ``Union``. In declaration order.
        )rW   r  r   r   )rZ   r"  r   r   r&  vs         r   _union_candidate_branchesz"Argument._union_candidate_branches  sf      $33
3C( CIIK>KDAq1::aK>?3
 	
>
s   *A(
A"A"A(
"A(
c                     | j                   sys
t               S | j                        }|s
t               S |D cg c]  \  }}|	 }}}t        fd|D              r
t               S t	        |fd      S c c}}w )a  Required child keys still owed by the chosen branch of a multi-branch ``Union``.

        Picks among the candidate branches (see :meth:`_union_candidate_branches`): if any is
        already fully satisfied, nothing is owed (``set()``); otherwise the candidate closest
        to completion (fewest missing required fields, ties broken by declaration order) guides
        which fields are still required. This convergent guidance means the prompt loop fills
        the same branch that :meth:`_resolve_union_member` later instantiates. Supplying one
        ``Union`` member's fields never demands a sibling member's
        required fields. Returns ``None`` when :attr:`hint` is not a multi-branch ``Union``
        (caller falls back to the static :attr:`Argument.required` per child).
        Nc              3   (   K   | ]	  }|k    y wr   rG   )r   r   r"  s     r   r   z8Argument._active_branch_required_keys.<locals>.<genexpr>  s     P9OXx=(9Os   c                      t        | z
        S r   )rv   )r   r"  s    r   <lambda>z7Argument._active_branch_required_keys.<locals>.<lambda>  s    H}D\@]r   )r   )rW   r  rf  r   min)rZ   r"  
candidatesr   r   required_per_candidates    `    r   r  z%Argument._active_branch_required_keys  s{     ## 5L33MB
5L>H!Ij{q((j!IP9OPP5L)/]^^ "Js   A:c                 H    | j                  |      D ]  \  }}||k  s|c S  y)uY  The ``Union`` member to instantiate given the converted ``data_keys``.

        Picks the first candidate branch (``data ⊆ branch``) whose required fields are all
        present, since :func:`instantiate_from_dict` cannot instantiate a bare ``Union``.
        Returns ``None`` if no branch is satisfied (caller raises a clean error).
        N)rf  )rZ   	data_keysr   r   s       r   r  zArgument._resolve_union_member   s1     !% > >y IFH9$ !J r   c                    | j                   D ch c]  }|j                  s|j                  d     }}| j                  r| j                  rz|sx| j                  d   d   j                         D ch c]  \  }}|j                  s| }}}| j                   D cg c]#  }|j                  r|j                  d   |v s"|% c}S | j                  |      }|9| j                   D cg c]#  }|j                  r|j                  d   |v s"|% c}S t        j                  |      }| j                  |      D 	cg c]
  \  }}	|		|	 c}	}S c c}w c c}}w c c}w c c}w c c}	}w )u  Direct child arguments the checker reports as required-and-absent (non-raising).

        Builds the provided-key set from token presence rather than converted values, so it
        can be called before/without conversion. When no child currently has a token (a
        fully-omitted composite) the checker returns every required child. For multi-branch
        ``Union`` composites, requiredness is branch-aware (see
        :meth:`_active_branch_required_keys`).

        Special case: a *required* multi-branch ``Union`` with no supplied fields hasn't
        committed to a branch, so :meth:`_active_branch_required_keys` owes nothing — which
        would leave an interactive prompt loop blind to a value it must collect. Default to
        the first branch's required fields so the loop converges on (and instantiates) it,
        matching the declaration-order preference of :meth:`_resolve_union_member`. This
        read-only query path only; conversion still errors on the composite itself.
        r
  r   r5   )
rQ   r   rH   rW   r   r   r  rk   fromkeysrc  )
rZ   r   r"  r&  re  first_branch_requiredr#  r  r   r   s
             r   _missing_childrenzArgument._missing_children  sR     6:]]W]EeFVFVB]WDMM-373G3G3J13M3S3S3U$d3U41aYZYcYcQ3U!$d#'==#0%8H8HUZZXZ^_tMt=  ;;MJ&'+}}s}eE<L<LQVQ[Q[\^Q_crQrE}ss}}]+,0,F,Ft,Le,L[QPXPd,Lee X$d
 tesF   EE1EEE-E?E'E9EE;
E#E#c                     | j                   r| j                  s|sy | j                  |      D ]O  \  }}|t        |      | j                  j
                  d   dz   dj                  |      z   }t        d| d       y )Nr   r   z->zRequired field "z]" is not accessible by Cyclopts; possibly due to conflicting POSITIONAL/KEYWORD requirements.)rT   r   rc  r#   rA   r   joinrb   )rZ   r  rH   r   missing_descriptions        r   r  z"Argument._run_missing_keys_checker(  s    ))$--"88>ND(#*H=="&//"7"7":T"ADIIdO"S"#6"7  8U  V 	 ?r   c                    dd l }|j                         d   }|d   dk(  r|d   }t        d |D              s{t        |      }|rn| j                  j                  | j                  |z         }|D cg c]  }|j                  r| }}|rt        |d         |t        |      dk(  rn|dd  }|rnt        ||j                        rt        t        |      | 	      ||c c}w )
Nr   r`   missinglocc              3   <   K   | ]  }t        |t                y wr   )r_   r^   )r   parts     r   r   z=Argument._handle_pydantic_validation_error.<locals>.<genexpr>?  s     =z$,s   r_  r   r5   r3  )r   errorsr   r   r   ra  rH   r@   r#   rv   r_   r&   rl   )rZ   excr   errorry  	candidatemissing_argumentsas           r   r   z*Argument._handle_pydantic_validation_error3  s    

Q=I%,C ===!#J	(,(?(?(I(IVZV_V_bkVk(I(l% 5F(V4EqQXX4E%(V(2<Ma<PQWZZ9~* !*!"I   c8334!CHtLRUUI )Ws   1C!C!r   r   )r   r;   )rG   )F)r   z-list[tuple[tuple[str, ...], Argument | None]])r"  set[str]r   zlist[tuple[Any, set[str]]])r"  r  r   zset[str] | None)ro  r  )r   zlist[Argument])R__name__
__module____qualname____doc__r   r  r@   r0   rY   r'   rA   r/   rB   rl   r   rE   r	   rF   r^   rH   r   r1   rK   rN   r]   rO   rk   rP   rQ   rR   rS   rT   r   rU   rV   rW   r   ro   propertyrI   setterr   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r)  r   r:  r  r   r   rB  ri   r   rH  rJ  re   r   rK  rS  rU  rZ  r   rc  rf  r  r  rs  r  r   rG   r   r   r>   r>   F   s   
  -FDK-
 ")4J	4 !3Iy3 cW5D#5 d+E3:+
 ""-D%S/-%N gu5FC5 $EEJtJ$U?Hc?$)$U$OGT#y.!O%*E%BH"B $EEJtJ%*5u5%QdQ-24eRW-X8d?X+0EPU+VDV"'5u"MOS4ZM@EdY^ej@kO=kp2d/$sI~*> /"   \\  F F ^^'T ' ' CT C C /dSj8SE3J+?? / / 

D 

 

!c !0E0L X\ 6 bdus{+e3c9D@OTUXZ]U]	< 26
Ci
 SE3J'$.	

 
 
uS#X#	$
>?sCx ?U3PS8_ ?J 26V_V_ SE3J'$.	V_
 V_ 
uS#X#	$V_p# %c3h0D*E "E "* MD M M  
}(T/ }~D :Qgfho (2/c3h 2/h 
' 
' B B c   KuS#X K KS3 S3: Sc S d  " 
*t 
* 
* +$ + +2D 2F4 F0 0.3 3%S/D2H 3@'t 'R&
_4
f8	 r   r>   )Lr  r   r  r  rM  r5  collections.abcr   r   
contextlibr   	functoolsr   r   r   r   r	   r
   r   attrsr   r   cyclopts._convertr   r   r   r   cyclopts.annotationsr   r   r   r   r   r   r   r   r   r   r   r   r   r   r    cyclopts.exceptionsr!   r"   r#   r$   r%   r&   cyclopts.field_infor'   r(   r)   r*   r+   r,   r-   cyclopts.parameterr.   r/   cyclopts.tokenr0   cyclopts.utilsr1   r2   r3   r4   utilsr6   r7   r8   r9   r[   r;   r>   rG   r   r   <module>r     s    /    	 
 .  % ; ;      "    H   D D  @ L L Lr   