
    l i	!                    h   d Z ddlmZ ddlZddlmZ ddlmZ ddlmZ ddlmZ ddlmZ dd	lm	Z	 dd
lm
Z
 ddlmZ ddlmZ ddlmZ ddlmZ ej        rddlmZ ddlmZ  e
dedef                   Zeeee         edef         f         Z	 d2d3dZd4d Zd5d&Zd6d)Zd7d,Zd8d-Zd9d0Z d:d1Z!dS );zhRoutines to handle adaption of legacy call signatures,
generation of deprecation notes and docstrings.

    )annotationsN)Any)Callable)List)Optional)Tuple)Type)TypeVar   )_ET)_ListenerFnType   )util)FullArgSpec)_ClsLevelDispatch)_HasEventsDispatch_F.)boundsincestrargnames	List[str]	converterOptional[Callable[..., Any]]returnCallable[[_F], _F]c                     d fd}|S )a_  legacy sig decorator


    :param since: string version for deprecation warning
    :param argnames: list of strings, which is *all* arguments that the legacy
     version accepted, including arguments that are still there
    :param converter: lambda that will accept tuple of this full arg signature
     and return tuple of new arg signature.

    fnr   r   c                p    t          | d          sg | _        | j                            f           | S )N_legacy_signatures)hasattrr    append)r   r   r   r   s    N/var/www/findabus/venv/lib/python3.11/site-packages/sqlalchemy/event/legacy.pylegz_legacy_signature.<locals>.leg6   sA    r/00 	'$&B!
$$eXy%ABBB	    r   r   r   r    )r   r   r   r$   s   ``` r#   _legacy_signaturer(   &   s4             Jr%   r   c                    d| _         | S )NT)_omit_standard_example)r   s    r#   r*   r*   ?   s     $BIr%   dispatch_collection_ClsLevelDispatch[_ET]r   argspecr   c           
        	  j         D ]\  d         dk    rddd         ndt                    t          |j                  k    rzt          |j                  u rdd j        dd                     j                  rd	nd
d}d j        d j        dd|d		rJ d	fd}nd 	fd}|c S S )Nz**kwTr   Fzdef (, , **kw )z The argument signature for the ".z+" event listener has changed as of version zl, and conversion for the old argument signature will be removed in a future release.  The new signature is ""argsr   kwr   c                 H    t          j                   J   |   S )Nversion)r   warn_deprecated)r7   r8   convr   r   warning_txts     r#   wrap_legz%_wrap_fn_for_legacy.<locals>.wrap_legh   s8    (eDDDD+++2ttT{++r%   c                     t          j        	           t          t          j        |                     fdD             }r |i |S  | S )Nr:   c                     g | ]
}|         S r'   r'   ).0nameargdicts     r#   
<listcomp>z9_wrap_fn_for_legacy.<locals>.wrap_leg.<locals>.<listcomp>r   s    %I%I%Igdm%I%I%Ir%   )r   r<   dictzip	arg_names)
r7   r8   args_from_dictrD   r   r+   r   has_kwr   r>   s
      @r#   r?   z%_wrap_fn_for_legacy.<locals>.wrap_lego   sx    (eDDDD"3':'Dd#K#KLLG%I%I%I%I%I%I%IN 3!r>8R888!r>22r%   )r7   r   r8   r   r   r   )	legacy_signatureslenr7   boolvarkwrC   joinrH   clsname)
r+   r   r-   formatted_defr?   r   r=   rJ   r   r>   s
   ``   @@@@@r#   _wrap_fn_for_legacyrR   D   s   
 "5!F 1 1xB<6!!F"~HHFx==C----&DM=
 =
 3
 3
 3
 $(((		-7888"***MM (///',,,EE!MM	  !!!!, , , , , , , , , ,3 3 3 3 3 3 3 3 3 3 3 OOO	r%   textindentc                l    d                     fd|                     d          D                       S )N
c              3  "   K   | ]	}|z   V  
d S Nr'   )rB   linerT   s     r#   	<genexpr>z_indent.<locals>.<genexpr>~   s'      @@tVd]@@@@@@r%   )rO   split)rS   rT   s    `r#   _indentr\   }   s6    99@@@@tzz$/?/?@@@@@@r%   sample_targetr   c                @   t          d                    d | j        dd         D                       d          }| j        rt	          d | j        D                       }nd }d}||rd|z  nd	|j        | j        rd
nd	d                    | j                  ||dz  }|S )NrV   c              3  $   K   | ]}d d|iz  V  dS )z%(arg)s = kw['%(arg)s']argNr'   )rB   r`   s     r#   rZ   z+_standard_listen_example.<locals>.<genexpr>   s?       
 
 &4
 
 
 
 
 
r%   r   r   z    c              3  "   K   | ]
\  }}}|V  d S rX   r'   )rB   r   r7   r=   s       r#   rZ   z+_standard_listen_example.<locals>.<genexpr>   s<       
 
!tT 
 
 
 
 
 
r%   zfrom sqlalchemy import event


@event.listens_for(%(sample_target)s, '%(event_name)s')
def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):
    "listen for the '%(event_name)s' event"

    # ... (event handling logic) ...
z (arguments as of %s)r3   r2   r1   )current_since
event_namehas_kw_argumentsnamed_event_argumentsexample_kw_argr]   )r\   rO   rH   rK   max__name__rJ   )r+   r]   r   rf   rb   rS   s         r#   _standard_listen_exampleri      s    
 		 
 
*4QqS9
 
 
 	
 	
 	 N ,  
 
%8%J
 
 
 
 

 	3 	 	7DL#m33"k(;(BJHH!%+>+H!I!I(&	 	 	D Kr%   c           	         d}| j         D ]5\  }}}|d||j        | j        rdndd                    |          |dz  z  }6|S )Nr3   a&  
# DEPRECATED calling style (pre-%(since)s, will be removed in a future release)
@event.listens_for(%(sample_target)s, '%(event_name)s')
def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):
    "listen for the '%(event_name)s' event"

    # ... (event handling logic) ...
z **kwr1   )r   rc   rd   re   r]   )rK   rh   rJ   rO   )r+   r]   r   rS   r   r7   r=   s          r#   _legacy_listen_examplesrk      sr    
 D0B 
 
tT7  k29AGGr)-4!. 	
$ Kr%   parent_dispatch_clsType[_HasEventsDispatch[_ET]]c                     j         d         \  }}}d| j        j        d                     fdj        D                       j        rdnddz  S )Nr   a=  
.. versionchanged:: %(since)s
    The :meth:`.%(clsname)s.%(event_name)s` event now accepts the 
    arguments %(named_event_arguments)s%(has_kw_arguments)s.
    Support for listener functions which accept the previous 
    argument signature(s) listed above as "deprecated" will be 
    removed in a future release.r1   c              3  >   K   | ]}d j         j        |dz  V  dS )z6:paramref:`.%(clsname)s.%(event_name)s.%(param_name)s`)rP   rc   
param_nameN)rh   rC   )rB   rp   r+   rl   s     r#   rZ   z-_version_signature_changes.<locals>.<genexpr>   sX       / /  I2;"5":", / / / / / /r%   r2   r3   )r   rP   rc   re   rd   )rK   rh   rC   rO   rH   rJ   )rl   r+   r   r7   r=   s   ``   r#   _version_signature_changesrq      s     ,=a@E4	+ *3-2%)YY / / / / / #6"?/ / / & & -@,F NB
 
	
r%   c                \   t          |dd          r|j        sJ |j        S d}t          |dd          }|t          t          | ||          d          z   }| j        r5|t          t          | ||          d          z  }|t          ||           z  }t          j        |j        |d          S )Nr*   Fz@.. container:: event_signatures

     Example argument forms::

_target_class_docobjz        r   )	getattr__doc__r\   ri   rK   rk   rq   r   inject_docstring_text)r+   rl   r   headerr]   rS   s         r#   _augment_fn_docsry      s    
 r+U33 zz	  /1DeLLMG !4mRHH  D , 
#$7KK
 
 	

 	*!4
 
 	
 %bj$:::r%   rX   )r   r   r   r   r   r   r   r   r&   )r+   r,   r   r   r-   r   r   r   )rS   r   rT   r   r   r   )r+   r,   r]   r   r   r   r   r   )r+   r,   r]   r   r   r   r   r   )rl   rm   r+   r,   r   r   )r+   r,   rl   rm   r   r   r   r   )"rv   
__future__r   typingr   r   r   r   r   r	   r
   registryr   r   r3   r   util.compatr   TYPE_CHECKINGattrr   baser   r   r   _LegacySignatureTyper(   r*   rR   r\   ri   rk   rq   ry   r'   r%   r#   <module>r      s    # " " " " "                                                  % % % % % %       % % % % % %	 )''''''(((((( WT#s(+,,,S$s)Xc3h-??@  /3    2   
6 6 6 6rA A A A& & & &R   8   <; ; ; ; ; ;r%   