U
    cc-                     @   s  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 ddlmZ ddlm	Z	 dd	lm
Z
 d
dlmZ dZedd dkrdZd-ddZd.ddZd/ddZd0ddZd1ddZd2ddZd3dd Zd!d" Zd4d#d$Zd%d& Zd'd( Zd5d)d*Zd6d+d,ZdS )7zSHelpers related to deprecation of functions, methods, classes, other
functionality.    N   )compat)_hash_limit_string)_warnings_warn)	decorator)inject_docstring_text)inject_param_text   )excFSQLALCHEMY_WARN_20false)trueyes1Tc                 C   s:   t |tjrtsd S || |d}||_t||d d d S )Ncoder   
stacklevel)
issubclassr
   Base20DeprecationWarningr   deprecated_sincer   )msgversiontype_r   r   warn r   @/tmp/pip-unpacked-wheel-8u86ls_i/sqlalchemy/util/deprecations.py_warn_with_version   s    
r      c                 C   s   t | |tj||d d S Nr   )r   r
   SADeprecationWarning)r   r   r   r   r   r   r   warn_deprecated*   s        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   argsr   r   r   r   r   r   warn_deprecated_limited0   s        r$   c                 C   s   t | tjjtj||d d S r   )r   r
   RemovedIn20Warningr   )r   r   r   r   r   r   warn_deprecated_20<   s    r&   __init__c                    s&   dp
df  fdd}|S )N.. deprecated:: %s %s c                    s   t |  tjt d S )Nfunc)_decorate_cls_with_warningr
   r    dictclsconstructorheadermessager   r   r   decorateJ   s    z deprecated_cls.<locals>.decorater   )r   r3   r1   r4   r   r0   r   deprecated_clsG   s    
r5   c                    sJ   d| |sdndf |r$d| 7 |r0t jnt j fdd}|S )Nzg.. deprecated:: 1.4 The %s class is considered legacy as of the 1.x series of SQLAlchemy and %s in 2.0.will be removedbecomes a legacy construct c                    s   t |  jS )N)r,   r   r.   r1   r3   warning_clsr   r   r4   m   s    z#deprecated_20_cls.<locals>.decorate)r
   LegacyAPIWarningr%   )Zclsnamealternativer1   becomes_legacyr4   r   r9   r   deprecated_20_clsW   s    
r>   c                    s|   dkrdkrt jd|r0dp(df nddkr@ddkrNt jt jk	rdd 7  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.

    2.0N1.4r(   r)   z$Call to deprecated function %(func)sz (deprecated since: %s)c                    s    t | t| jd  dS )Nr*   )enable_warnings)_decorate_with_warningr-   __name__)fnrA   r2   r3   r   warningr   r   r4      s    zdeprecated.<locals>.decorate)r
   r%   r    )r   r3   Zadd_deprecation_to_docstringrF   rA   r4   r   rE   r   
deprecatedz   s$    

rG   c                 K   s   t d| tjd|S )Nr?   r3   rF   )r?   )rG   r
   ZMovedIn20Warning)r3   kwr   r   r   moved_20   s      rJ   c           	      K   s   t d| }|r(dddd|d }nd}d| ||s:d	nd
f }d| krt|dd}|st|ddksttd|  |r|d| 7 }|rtj}ntj}t	d||d|S )Nz^:(attr|func|meth):	attributefunctionmethod)attrr+   methr   Z	constructzPThe %s %s is considered legacy as of the 1.x series of SQLAlchemy and %s in 2.0.r6   r7   z:attr:Zwarn_on_attribute_accessFrA   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.r8   r?   rH   )r?   )
rematchgrouppopgetAssertionErrorr
   r;   r%   rG   )	Zapi_namer<   r=   rI   Ztype_regr   r3   Zattribute_okr:   r   r   r   deprecated_20   s:    
rV   c                     sd   i  i i   D ]8\}\}}||< t| |< |dkrBtjntj|< q fdd}|S )a"  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."
            )

        )

    r?   c                    s   t | }|jd k	r\tt|jt|jt|j d  |jtt	ndt|j
 t fdd}| jd k	r| jpd}|rt|dd  D }|| }||_|S )Nr   c                    s   D ]T}| d kr || d k	s<| d k	r|| | krt | | | dd q krt|rt       dd D ](}||krt | | | dd q| ||S Nr   r   )r   set
difference)rD   r#   kwargsm)check_any_kwcheck_defaultscheck_kwdefaultsmessagesversion_warningsversionsr   r   warned  s<    
z3deprecated_params.<locals>.decorate.<locals>.warnedr)   c                 S   s2   i | ]*\}\}}|d |dkr dn||p(df qS )r(   r?   r@   r)   r   ).0paramr   r3   r   r   r   
<dictcomp>;  s
   
 z7deprecated_params.<locals>.decorate.<locals>.<dictcomp>)r   Zinspect_getfullargspecr_   r-   zipr#   lenrX   intersectionrY   varkwr   __doc__r   items)rD   specrc   doc	decoratedr`   specsra   rb   )r\   r]   r^   r_   r   r4     s4    

!z#deprecated_params.<locals>.decorate)rl   _sanitize_restructured_textr
   r%   r    )rq   re   r   r3   r4   r   rp   r   deprecated_params   s    Brs   c                 C   s(   dd }t ddd | } t d|| S )Nc                 S   s$   |  dd\}}|dkr |d7 }|S )Nr   r	   )r+   rO   z()rR   )r[   r   namer   r   r   replI  s    z)_sanitize_restructured_text.<locals>.replz:ref:`(.+) <.*>`c                 S   s   d|  d S )Nz"%s"r   rt   )r[   r   r   r   <lambda>O      z-_sanitize_restructured_text.<locals>.<lambda>z\:(\w+)\:`~?(?:_\w+)?\.?(.+?)`)rP   sub)textrv   r   r   r   rr   H  s    rr   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}t| tkrt| j}||d< |dd  |dd  t| j	| j
|} |d k	r|| }n|| _ |d k	rt| |}|d k	rt| |t||||d  | S )Nr)   r*   @ (Background on SQLAlchemy 2.0 at: :ref:`migration_20_toplevel`)r   rk   __dict____weakref__)rk   r-   r   r
   r   r   typer|   rS   rC   	__bases__getattrsetattrrB   )	r/   r1   wtyper3   r   docstring_headerrn   ZclsdictZconstructor_fnr   r   r   r,   S  sB    


    r,   c           
         s   t ttjrd}nd}t fdd}| jdk	rD| jpFd}|dk	rt|t| jd; }||7 }t||d}|| }	||	_fdd	|	_	|	S )
z=Wrap a function with a warnings.warn and augmented docstring.r{   r)   c                    s0     p| dd}|s&tdd | ||S )NZ_sa_skip_warningFr   r   )rS   r   )rD   r#   rZ   Zskip_warningrA   r3   r   r   r   r   rc     s    
 z&_decorate_with_warning.<locals>.warnedNr*   r   c                      s   t  ddS rW   )r   r   )r3   r   r   r   r   rw     s
      z(_decorate_with_warning.<locals>.<lambda>)
rr   r   r
   r   r   rk   r-   rC   r   Z_sa_warn)
r+   r   r3   r   r   rA   Zdoc_onlyrc   rn   ro   r   r   r   rB   |  s     rB   )N)r   N)r   N)r   N)r'   )Nr'   F)NTNT)NF)N)NT)rk   osrP   r)   r   Zlanghelpersr   r   r   r   r   r
   r   getenvlowerr   r!   r$   r&   r5   r>   rG   rJ   rV   rs   rr   r,   rB   r   r   r   r   <module>   sF   




     
%    
=
)b 
*   