U
    [h.                  	   @  s  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 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dedZedddZdNdddddd d!d"d#ZdOddddd d%d&d'ZdPdd(dddd d)d*d+ZdQdddd-d.d/d0ZdRddd2d3d2d4d5d6d7Zdd8d9d:d;d<Z dSddd8d4d=d>d?Z!d@d4dAdBdCZ"dddDdEdFZ#dTdGddddddGdHdIdJZ$dUdddddd2ddKdLdMZ%dS )VzSHelpers related to deprecation of functions, methods, classes, other
functionality.    )annotationsN)Any)Callable)Dict)Match)Optional)Sequence)Set)Tuple)Type)TypeVar)Union   )compat)_hash_limit_string)_warnings_warn)	decorator)inject_docstring_text)inject_param_text   )exc_T)Zbound_FzCallable[..., Any]strzType[exc.SADeprecationWarning]intzOptional[str]None)msgversiontype_
stacklevelcodereturnc                 C  s&   || |d}||_ t||d d d S )Nr    r   r   )Zdeprecated_sincer   )r   r   r   r   r    warn r%   B./venv/lib/python3.8/site-packages/sqlalchemy/util/deprecations.py_warn_with_version*   s    r'      )r   r   r   r    r!   c                 C  s   t | |tj||d d S )Nr"   )r'   r   SADeprecationWarning)r   r   r   r    r%   r%   r&   warn_deprecated7   s        r*   zSequence[Any])r   argsr   r   r    r!   c                 C  s(   |rt | d|} t| |tj||d dS )zhIssue a deprecation warning with a parameterized string,
    limiting the number of registrations.

    
   r"   N)r   r'   r   r)   )r   r+   r   r   r    r%   r%   r&   warn_deprecated_limited?   s        r-   __init__zCallable[[Type[_T]], Type[_T]])r   messageconstructorr!   c                   s.   dp
df ddd fdd}|S )N.. deprecated:: %s %s Type[_T])clsr!   c                   s   t |  tjt d S )Nfunc)_decorate_cls_with_warningr   r)   dict)r4   r0   headerr/   r   r%   r&   decorateV   s    z deprecated_cls.<locals>.decorater%   )r   r/   r0   r;   r%   r9   r&   deprecated_clsQ   s    
r<   Tboolz(Optional[Type[exc.SADeprecationWarning]]zCallable[[_F], _F])r   r/   add_deprecation_to_docstringwarningenable_warningsr!   c                   s`   |rdpdf nddkr&ddkr4t jd 7 ddd fdd	}|S )
a  Decorates a function and issues a deprecation warning on use.

    :param version:
      Issue version in the warning.

    :param message:
      If provided, issue message in the warning.  A sensible default
      is used if not provided.

    :param add_deprecation_to_docstring:
      Default True.  If False, the wrapped function's __doc__ is left
      as-is.  If True, the 'message' is prepended to the docs if
      provided, or sensible default if message is omitted.

    r1   r2   Nz$Call to deprecated function %(func)sz (deprecated since: %s)r   fnr!   c                   s8   d k	st d k	st t| t| jd  dS )Nr5   )r@   )AssertionError_decorate_with_warningr8   __name__)rB   r@   r:   r/   r   r?   r%   r&   r;      s    zdeprecated.<locals>.decorate)r   r)   )r   r/   r>   r?   r@   r;   r%   rF   r&   
deprecatedc   s    rG   r   z0Callable[[Callable[..., _T]], Callable[..., _T]])r/   kwr!   c                 K  s   t d| tjd|S )N2.0r/   r?   )rI   )rG   r   ZMovedIn20Warning)r/   rH   r%   r%   r&   moved_20   s      rK   )api_namealternativerH   r!   c                 K  s   t d| }|r(dddd|d }nd}d| |d	f }d
| krl|dd}|sl|ddksltd|  |r||d| 7 }tj}td||d|S )Nz^:(attr|func|meth):Z	attributefunctionmethod)attrr6   methr   Z	constructzPThe %s %s is considered legacy as of the 1.x series of SQLAlchemy and %s in 2.0.zbecomes a legacy constructz:attr:Zwarn_on_attribute_accessFr@   zattribute %s will emit a warning on read access.  If you *really* want this, add warn_on_attribute_access=True.  Otherwise please add enable_warnings=False. rI   rJ   )rI   )	rematchgrouppopgetrC   r   ZLegacyAPIWarningrG   )rL   rM   rH   Ztype_regr   r/   Zattribute_okZwarning_clsr%   r%   r&   became_legacy_20   s2    

rX   zTuple[str, str])specsr!   c                    s^   i  i i   D ]*\}\}}||< t| |< tj|< qddd fdd}|S )aK  Decorates a function to warn on use of certain parameters.

    e.g. ::

        @deprecated_params(
            weak_identity_map=(
                "0.7",
                "the :paramref:`.Session.weak_identity_map parameter "
                "is deprecated.",
            )
        )
        def some_function(**kwargs): ...

    r   rA   c              	     s  t | }|jd k	r\tt|jt|jt|j d  |jtt	n:|j
d k	r|j
tt	ndt|j tddddd fdd}| jd k	r| jpd}|rt|dd	  D }|| }||_|S )
Nr%   r   r   rB   r+   kwargsr!   c                   s   D ]T}| d kr || d k	s<| d k	r|| | krt | | | dd q krt|r d k	s|tt       dd D ](}||krt | | | dd q| ||S Nr(   r#   )r'   set
differencerC   )rB   r+   r[   m)check_any_kwcheck_defaultscheck_kwdefaultsmessagesversion_warningsversionsr%   r&   warned   s>    
z3deprecated_params.<locals>.decorate.<locals>.warnedr2   c                 S  s2   i | ]*\}\}}|d |dkr dn||p(df qS )r1   rI   z1.4r2   r%   ).0paramr   r/   r%   r%   r&   
<dictcomp>  s
   
 z7deprecated_params.<locals>.decorate.<locals>.<dictcomp>)r   Zinspect_getfullargspecrc   r8   zipr+   lenr]   intersectionr^   ZkwonlydefaultsZvarkwr   __doc__r   items)rB   specrg   doc	decoratedrd   rY   re   rf   )r`   ra   rb   rc   r&   r;      s<    


&!z#deprecated_params.<locals>.decorate)ro   _sanitize_restructured_textr   r)   )rY   ri   r   r/   r;   r%   rs   r&   deprecated_params   s    Iru   )textr!   c                 C  s0   ddddd}t ddd | } t d	|| S )
Nz
Match[str]r   )r_   r!   c                 S  s$   |  dd\}}|dkr |d7 }|S )Nr   r   )r6   rQ   z()rU   )r_   r   namer%   r%   r&   repl-  s    z)_sanitize_restructured_text.<locals>.replz:ref:`(.+) <.*>`c                 S  s   d|  d S )Nz"%s"r   rw   )r_   r%   r%   r&   <lambda>3      z-_sanitize_restructured_text.<locals>.<lambda>z\:(\w+)\:`~?(?:_\w+)?\.?(.+?)`)rS   sub)rv   ry   r%   r%   r&   rt   ,  s    rt   r3   )r4   r0   wtyper/   r   docstring_headerr!   c           	   	   C  s  | j d k	r| j pd}|d k	r|d k	r2|t|d; }t|tjrF|d7 }t||d}d }t| tkrt| j}||d< |dd  |dd  t| j	| j
|} |d k	r|| }n|| _ |d k	rt| |}|d k	r|d k	st|d k	stt| |t||||d  | S )Nr2   r5   @ (Background on SQLAlchemy 2.0 at: :ref:`migration_20_toplevel`)r   rn   __dict____weakref__)rn   r8   
issubclassr   Base20DeprecationWarningr   typer   rV   rE   	__bases__getattrrC   setattrrD   )	r4   r0   r}   r/   r   r~   rq   Zconstructor_fnZclsdictr%   r%   r&   r7   7  sH    


    r7   )r6   r}   r/   r   r~   r@   r!   c           
        s   t ttjrd}nd}tddddd fdd}| jdk	rP| jpRd}|dk	r|t| jd	; }||7 }t||d
}|| }	||	_fdd|	_	|	S )z=Wrap a function with a warnings.warn and augmented docstring.r   r2   r   r   rZ   c                   s0     p| dd}|s&tdd | ||S )NZ_sa_skip_warningFr(   r#   )rV   r'   )rB   r+   r[   Zskip_warningr@   r/   r   r}   r%   r&   rg   {  s    
 z&_decorate_with_warning.<locals>.warnedNr5   r   c                     s   t  ddS r\   )r'   r%   )r/   r   r}   r%   r&   rz     s
      z(_decorate_with_warning.<locals>.<lambda>)
rt   r   r   r   r   rn   r8   rE   r   Z_sa_warn)
r6   r}   r/   r   r~   r@   Zdoc_onlyrg   rq   rr   r%   r   r&   rD   g  s     
 rD   )N)r(   N)r(   N)r.   )NTNT)N)N)NT)&rn   Z
__future__r   rS   typingr   r   r   r   r   r   r	   r
   r   r   r   r2   r   Zlanghelpersr   r   r   r   r   r   r   r   r'   r*   r-   r<   rG   rK   rX   ru   rt   r7   rD   r%   r%   r%   r&   <module>	   s^              6	 &e 5  