
    c+k                        U d Z dZddlZddlZddlZddl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mZ ddlmZ ej(                  d	k\  rdd
lmZ nddlZ G d dej0                        Zd ZdedefdZdedefdZdedefdZ G d de      Z dKde!defdZ"da#eeeee   f      e$d<   dee   fdZ%	 	 	 dLdedee&   deeef   dee   de!dee   ddfd Z' G d! d"e      Z( G d# d$e      Z) G d% d&e&      Z* G d' d(e*      Z+ G d) d*e*      Z, G d+ d,e*      Z- G d- d.e*      Z.	 dMd/ed0edee   defd1Z/ e/d2e/3      Z0eeeee   gef   e$d2<   dMd4edee   defd5Z1 e1d6       e1d7      	 dNdee   dee   de!defd8              Z2 G d9 d:e      Z3 e/d;e23      Z4e3e$d;<   d< Z5 e5       Z6dMd/ed=edee   defd>Z7dMd/ed=edee   defd?Z8 e8d@dAB       e8dCdDB      	 	 	 dLdedDedee   de!d=ee   defdE              Z9 e/dFe93      Z:eee   ee   e!gef   e$dF<   ddde+dfd/edGe;dHee   dee   dee   de;fdIZ<	 	 	 dOdGe;d/ee   dHee   dee   de;f
dJZ=y)PzDeprecation utilities.zrestructuredtext en    N)Enumwarn)WRAPPER_ASSIGNMENTSWRAPPER_UPDATES)AnyCallableDictOptionalType)Protocol)      )metadatac                       e Zd ZdZd Zd Zy)FakeDistributionzKsee https://github.com/python/importlib_metadata/blob/main/CHANGES.rst#v600c                      y N selfs    </usr/lib/python3/dist-packages/logilab/common/deprecation.pylocate_filezFakeDistribution.locate_file(           c                      y r   r   r   s    r   	read_textzFakeDistribution.read_text+   r   r   N)__name__
__module____qualname____doc__r   r   r   r   r   r   r   %   s    Qr   r   c                 P    t        | d      r| j                  } t        | d      r| S )a  
    This is another super edge magic case which is needed because we uses
    lazy_wraps because of logilab.common.modutils.LazyObject and because
    __name__ has special behavior and doesn't work like a normal attribute and
    that __getattribute__ of lazy_wraps is bypassed.

    Therefor, to get the real callable name when several lazy_wrapped
    decorator are used we need to travers the __wrapped__ attributes chain.
    __wrapped__)hasattrr#   )functions    r   #_unstack_all_deprecation_decoratorsr&   /   s,     (M
*'' (M
* Or   some_callablereturnc                 ,    t        |       j                  S r   )r&   r   r'   s    r   get_real__name__r+   ?   s    .}=FFFr   c                 ,    t        |       j                  S r   )r&   r   r*   s    r   get_real__module__r-   C   s    .}=HHHr   wrappedc                 ,     dt         dt         f fd}|S )a  
    This is the equivalent of the @wraps decorator of functools except it won't
    try to grabs attributes of the targeted function on decoration but on access.

    This is needed because of logilab.common.modutils.LazyObject.

    Indeed: if you try to decorate a LazyObject with @wraps, wraps will try to
    access attributes of LazyObject and this will trigger the attempt to import
    the module decorated by LazyObject which you don't want to do when you just
    want to mark this LazyObject has been a deprecated objet that you only
    wants to trigger if the user try to use it.

    Usage: like @wraps()

    >>> @lazy_wraps(function)
    >>> def wrapper(*args, **kwargs): ...
    wrapperr(   c                     dt         dt        ffd}|| _        t        D ](  }t	        | |      j                  t	        |i              * | _        | S )N	attributer(   c                 ^    |t         v rt        |      S t        | j                  |   |      S r   )r   getattrsuper	__class____getattribute__)r   r2   r.   s     r   r7   zGlazy_wraps.<locals>.update_wrapper_attributes.<locals>.__getattribute__[   s/    //w	22?	JJr   )strr   r7   r   r4   updater#   )r0   r7   r2   r.   s      r   update_wrapper_attributesz-lazy_wraps.<locals>.update_wrapper_attributesZ   sa    	Kc 	Kc 	K $4 ( 	PIGY'..ww	2/NO	P &r   r	   )r.   r:   s   ` r   
lazy_wrapsr<   G   s    &8    %$r   c            	       \    e Zd ZdZ	 ddedee   dee   ddfdZdedefd	Zded
eddfdZ	y)DeprecationWrapperzIproxy to print a warning on access to any attribute of the wrapped objectNproxiedmsgversionr(   c                 6    || _         |r|nd| _        || _        y )N )_proxied_msgrA   )r   r?   r@   rA   s       r   __init__zDeprecationWrapper.__init__p   s     % #	&-r   attrc                 ~    t        | j                  t        i d| j                         t	        | j
                  |      S )Nr   deprecation_classdeprecation_class_kwargs
stacklevelrA   )send_warningrE   DeprecationWarningrA   r4   rD   )r   rG   s     r   __getattr__zDeprecationWrapper.__getattr__w   s4    II0%'LL	
 t}}d++r   valuec                     |dv r|| j                   |<   y t        | j                  t        i d| j                         t        | j                  ||       y )N)rD   rE   r   rI   )__dict__rM   rE   rN   rA   setattrrD   )r   rG   rP   s      r   __setattr__zDeprecationWrapper.__setattr__   sJ    ''"'DMM$		"4)+ DMM4/r   NN)
r   r   r    r!   r   r   r8   rF   rO   rT   r   r   r   r>   r>   m   sf    S QU..!)#.@H.	., , ,0 0C 0D 0r   r>   numberc                 b   t        j                         }t        | dz         D ]  }|j                   n|j                  } |j                  d   r|j                  d   S t
        j                  j                  |j                  d         d   }|j                  d      r|dt        d        }|S )z
    automagically try to determine the package name from which the warning has
    been triggered by loop other calling frames.

    If it fails to do so, return an empty string.
       N__package____file__z.py)
sys	_getframerangef_back	f_globalsospathsplitendswithlen)rV   framei	file_names       r   _get_module_namerh      s     MMOE6A: <<	 }%}--eooj9:1=I% mU,	r   _cached_path_to_packagec           	      T   dt         j                  vry t        i at               j	                         D ]  }|j
                  rIt        |d      r=|j
                  D ]-  }|j                  t        t        |j                  |            <   / X|j
                  sed|j                  v st|j
                  D ]0  }|j                  d   t        t        |j                  |            <   2  	 t        j                  t        j                  t        |                   S # t        $ r Y y w xY w)N)COLLECT_DEPRECATION_WARNINGS_PACKAGE_NAMEname)r`   environri   r   discoverfilesr$   rl   r8   r   r   getinspectgetfiler&   	TypeError)python_objectdistributionfiles      r   _get_package_namerw      s   2"**D &"$ -.779 	6L!!glF&C(.. eDS_SdSd+C0H0H0N,OPe!!f0E0E&E(.. 6D %--f5 ,L44T:;6	6&**OO?NO
 	
  s   *0D 	D'&D'reasonrJ   rK   rA   rL   module_namec                 v    |r|rd|d|d| } n|r	d|d| } n
|rd|d| } t         || fi ||       y)`Display a deprecation message only if the version is older than the
    compatible version.
    [ z] )rL   Nr   )rx   rJ   rK   rA   rL   ry   s         r   rM   rM      sG     w!,gv>	)62	%v.&=$<=*r   c                        e Zd ZdZdZdZdZdZy)DeprecationWarningKindargumentr2   callableclassmoduleN)r   r   r    ARGUMENT	ATTRIBUTECALLABLECLASSMODULEr   r   r   r   r      s    HIHEFr   r   c                       e Zd ZdZdZdZdZy)DeprecationWarningOperation
deprecatedmovedremovedrenamedN)r   r   r    
DEPRECATEDMOVEDREMOVEDRENAMEDr   r   r   r   r      s    JEGGr   r   c                   2    e Zd ZdZd	dededefdZdefdZy)
StructuredDeprecationWarningzZ
    Base class for all structured DeprecationWarning
    Mostly used with isinstance
    Nrx   packagerA   c                 .    || _         || _        || _        y r   )rx   r   rA   )r   rx   r   rA   s       r   rF   z%StructuredDeprecationWarning.__init__   s    !r   r(   c                     | j                   S r   )rx   r   s    r   __str__z$StructuredDeprecationWarning.__str__   s    {{r   rU   )r   r   r    r!   r8   rF   r   r   r   r   r   r      s-    
s S # 
 r   r   c                   >     e Zd Z	 	 ddedededededef fdZ xZS )	TargetRenamedDeprecationWarningrx   kindold_namenew_namer   rA   c                 ~    t         |   |||       t        j                  | _        || _        || _        || _        y N)r   rA   )r5   rF   r   r   	operationr   r   r   )r   rx   r   r   r   r   rA   r6   s          r   rF   z(TargetRenamedDeprecationWarning.__init__  s;     	'B4<<,0	%%r   rU   r   r   r    r8   r   rF   __classcell__r6   s   @r   r   r     sO     && %& 	&
 & & & &r   r   c            	       4     e Zd Z	 ddedededef fdZ xZS )"TargetDeprecatedDeprecationWarningrx   r   r   rA   c                 b    t         |   |||       t        j                  | _        || _        y r   )r5   rF   r   r   r   r   )r   rx   r   r   rA   r6   s        r   rF   z+TargetDeprecatedDeprecationWarning.__init__  s-     	'B4??,0	r   rU   r   r   s   @r   r   r     s0    ]a11!71BE1WZ1 1r   r   c                   :     e Zd Z	 	 ddededededef
 fdZ xZS )TargetRemovedDeprecationWarningrx   r   rl   r   rA   c                 p    t         |   |||       t        j                  | _        || _        || _        y r   )r5   rF   r   r   r   r   rl   )r   rx   r   rl   r   rA   r6   s         r   rF   z(TargetRemovedDeprecationWarning.__init__  s4     	'B4<<,0		r   rU   r   r   s   @r   r   r     sE      % 	
   r   r   c                   F     e Zd Z	 	 d
dedededededededef fd	Z xZS )TargetMovedDeprecationWarningrx   r   r   r   
old_module
new_moduler   rA   c	                     t         	|   |||       t        j                  | _        || _        || _        || _        || _        || _	        y r   )
r5   rF   r   r   r   r   r   r   r   r   )
r   rx   r   r   r   r   r   r   rA   r6   s
            r   rF   z&TargetMovedDeprecationWarning.__init__-  sI     	'B4::,0	%%))r   rU   r   r   s   @r   r   r   ,  sc     ** %* 	*
 * * * * * *r   r   r   new_functionc                 6     t               fd       }|S )a  use to tell that a callable has been renamed.

    It returns a callable wrapper, so that when its called a warning is printed
    telling what is the object new name.

    >>> old_function = renamed('old_function', new_function)
    >>> old_function()
    sample.py:57: DeprecationWarning: old_function has been renamed and is deprecated, uses
    new_function instead old_function()
    >>>
    c                      t         dt               dt        t        j                  t              t              ddt                      | i |S )Nz* has been renamed and is deprecated, uses  insteadr   r   r   rA   r   r   )rK   rL   rA   ry   )rM   r+   r   r   r   rw   r-   )argskwargsr   r   rA   s     r   r.   z!callable_renamed.<locals>.wrappedP  sp    *F#L12(< ,.77$,\:",\:& *<8	
" T,V,,r   r<   )r   r   rA   r.   s   ``` r   callable_renamedr   A  s#     - -( Nr   r   )r   r   old_argument_namec                 0     dt         dt         f fd}|S )a  
    callable decorator to allow getting backward compatibility for renamed keyword arguments.

    >>> @argument_removed("old")
    ... def some_function(new):
    ...     return new
    >>> some_function(old=42)
    sample.py:15: DeprecationWarning: argument old of callable some_function has been renamed and
    is deprecated, use keyword argument new instead some_function(old=42)
    42
    funcr(   c                 4     t                fd       }|S )Nc            
          |v rMt        d dt               dt        t        j                  t              ddt                     |=  | i |S )N	argument  of callable z# has been removed and is deprecated)r   rl   rA   r   r   rJ   rK   rL   rA   ry   )rM   r+   r   r   r   rw   r-   )r   r   r   r   rA   s     r   check_kwargsz5argument_removed.<locals>._wrap.<locals>.check_kwargs{  s     F* 12-@PQU@V?W X0 1&E 6 ? ? 1#*#4T#:	.  !# 24 8 ,-(((r   r   )r   r   r   rA   s   ` r   _wrapzargument_removed.<locals>._wrapz  s"    	D		) 
	)( r   r;   )r   rA   r   s   `` r   argument_removedr   m  s    H  0 Lr   rl   docc                 4     dt         dt         f fd}|S )r{   r   r(   c                 D     t               dt        f fd       }|S )Nr(   c            
          xs d}d|v r|t              z  }t        |t        t        j                  t              ddz   t                      | i |S )NzThe function "%s" is deprecatedz%s)r   rA   r   rX   rJ   rK   rA   rL   ry   )r+   rM   r   r   r   rw   r-   )r   r   messager   rx   rL   rA   s      r   r.   z7callable_deprecated.<locals>.decorator.<locals>.wrapped  sr    !F%FGw+D11"D2;;&06*
  %>.t4 (((r   r<   r	   )r   r.   rx   rL   rA   s   ` r   	decoratorz&callable_deprecated.<locals>.decorator  s(    	D		) 	) 
	)& r   r;   )rx   rA   rL   r   s   ``` r   callable_deprecatedr     s     X . r   c            	       4    e Zd Z	 ddee   dee   dedefdZy)CallableDeprecatedCallableNrx   rA   rL   r(   c                      y r   r   )r   rx   rA   rL   s       r   __call__z#CallableDeprecatedCallable.__call__  s     	r   NN   )r   r   r    r   r8   intr	   r   r   r   r   r   r     s2    ]^sm5=c]WZ	r   r   r   c                  $     G d dt               } | S )Nc                       e Zd ZdZd Zy)5_generate_class_deprecated.<locals>._class_deprecatedzCmetaclass to print a warning on instantiation of a deprecated classc                 `   t        | dd      dt        |       iz  }t        |t        | dt              t        | dt        j
                  t        |       t        | dd       d      t        | dt        d	            t        | d
d      t        | dd              t        j                  | g|i |S )N__deprecation_warning__z%(cls)s is deprecatedcls__deprecation_warning_class__$__deprecation_warning_class_kwargs____deprecation_warning_version__)r   r   rA   #__deprecation_warning_module_name__rX   "__deprecation_warning_stacklevel__r   )rJ   rK   ry   rL   rA   )
r4   r+   rM   r   r   r   rw   rh   typer   )r   r   r   r   s       r   r   z>_generate_class_deprecated.<locals>._class_deprecated.__call__  s    c#<>UV',Z G ")8:\# *1: 6 < <#4S#9#*30QSW#X* $>@PQR@S #3(LaP%FM%( ==6t6v66r   N)r   r   r    r!   r   r   r   r   _class_deprecatedr     s
    Q	7r   r   r   )r   s    r   _generate_class_deprecatedr     s    7D 7: r   r   c                 4     dt         dt         f fd}|S )a  
    class decorator to allow getting backward compatibility for renamed attributes.

    >>> @attribute_renamed(old_name="old", new_name="new")
    ... class SomeClass:
    ...     def __init__(self):
    ...         self.new = 42

    >>> some_class = SomeClass()
    >>> print(some_class.old)
    sample.py:15: DeprecationWarning: SomeClass.old has been renamed and is deprecated, use
    SomeClass.new instead
      print(some_class.old)
    42
    >>> some_class.old = 43
    sample.py:16: DeprecationWarning: SomeClass.old has been renamed and is deprecated, use
    SomeClass.new instead
      some_class.old = 43
    >>> some_class.old == some_class.new
    True
    klassr(   c           	           t                d dt                d ddt        f fd}d fd} fd}t         t        |||              S )	N.z) has been renamed and is deprecated, use r   r(   c                     t        t        t        j                  t	              ddt                     t        |       S Nr   r   r   )rM   r   r   r   rw   r-   r4   r   r   r   r   rx   rA   s    r   _get_oldz8attribute_renamed.<locals>._class_wrap.<locals>._get_old  sO    "A2<< ( (&07* .u5 4**r   c                     t        t        t        j                  t	              ddt                     t        | |       y r   )rM   r   r   r   rw   r-   rS   )r   rP   r   r   r   rx   rA   s     r   _set_oldz8attribute_renamed.<locals>._class_wrap.<locals>._set_old  sN    "A2<< ( (&07* .u5 D(E*r   c                     t        t        t        j                  t	              ddt                     t        |        y r   )rM   r   r   r   rw   r-   delattrr   s    r   _del_oldz8attribute_renamed.<locals>._class_wrap.<locals>._del_old'  sL    "A2<< ( (&07* .u5 D(#r   )r(   N)r+   r   rS   property)r   r   r   r   rx   r   r   rA   s   `   @r   _class_wrapz&attribute_renamed.<locals>._class_wrap  su    &'q
2[&'q
(< 	
	+c 	+ 	+"	+ 	+"	$ 	$" 	x(Hh!GHr   r   )r   r   rA   r   s   ``` r   attribute_renamedr     s    .;4 ;D ;z r   c                 4     dt         dt         f fd}|S )a  
    callable decorator to allow getting backward compatibility for renamed keyword arguments.

    >>> @argument_renamed(old_name="old", new_name="new")
    ... def some_function(new):
    ...     return new
    >>> some_function(old=42)
    sample.py:15: DeprecationWarning: argument old of callable some_function has been renamed and
    is deprecated, use keyword argument new instead
      some_function(old=42)
    42
    r   r(   c                 D     t               dt        f fd       }|S )Nr(   c                  *   |v r*|v r&t        d dt               d d d d       |v rYt        d dt               d dt        t        j
                  t              d	d
t                     |   |<   |=  | i |S )Nr   r   z has been renamed to z but you are both using z and z" has keyword arguments, only uses z: has been renamed and is deprecated, use keyword argument r   r   r   r   )
ValueErrorr+   rM   r   r   r   rw   r-   )r   r   r   r   r   rA   s     r   r   z5argument_renamed.<locals>._wrap.<locals>.check_kwargsN  s    6!h&&8 z7G7M6N O""*+CH:Uj B8*N  6!z7G7M6N O??GjR&E 6 ? ?$,$,#*#4T#:.  !# 24 8 $*(#3x 8$(((r   r   )r   r   r   r   rA   s   ` r   r   zargument_renamed.<locals>._wrapM  s)    	D		)X 	) 
	): r   r;   )r   r   rA   r   s   ``` r   argument_renamedr   ?  s    H  B Lr   modpathmodule_path)r   r   objnameobject_namec                 h     nt        d      ddd d fd}|S )a  use to tell that a callable has been moved to a new module.

    It returns a callable wrapper, so that when its called a warning is printed
    telling where the object can be found, import is done (and not before) and
    the actual object is called.

    NOTE: the usage is somewhat limited on classes since it will fail if the
    wrapper is use in a class ancestors list, use the `class_moved` function
    instead (which has no lazy import feature though).
    r   zobject r   z has been moved to c                      ddl m}  |      }t        t        t        j
                  
t        t        |            d
	dz           t        |      | i |S )Nr   )load_module_from_name)r   r   r   r   r   rA   r   rX   r   )logilab.common.modutilsr   rM   r   r   r   rw   r4   )r   r   r   mr   ry   r   r   r   rL   rA   s       r   callnewzcallable_moved.<locals>.callnew  st    A!+.;.77'$()",WQ-DE& !A~"	
" 'wq+&777r   )rh   )ry   r   rA   rL   r   r   r   r   s   ````` @@r   callable_movedr  q  sA    ( $/x[H!!$J 		G8 80 Nr   r   	new_classr   c                 ^    i | dt              d}|d<   |d<   |,t        j                   t              t              dd<   n|d<   d<   dd	<   |r|d
<   nt	        d      d
<   	 t         f      S # t        t        f$ r  G  fdd      cY S w xY w)a
  automatically creates a class which fires a DeprecationWarning
    when instantiated.

    >>> Set = class_renamed('Set', set, 'Set is now replaced by set')
    >>> s = Set()
    sample.py:57: DeprecationWarning: Set is now replaced by set
    s = Set()
    >>>
     is deprecated, use r   r   r   r   r   r   r   r   r   rX   c                   *     e Zd Z fdZ xZS )&class_renamed.<locals>.DeprecatedClassc                    j                  d dt               d      }t        |t        t        j
                  t              	t              dj                  dd      j                  dd              t        | "  |i | y )	Nr   r  r   r   r   r   r   rI   )	rp   r+   rM   r   r   r   rw   r5   rF   )
r   r   r   r@   DeprecatedClassr6   
class_dictr  r   rA   s
       r   rF   z/class_renamed.<locals>.DeprecatedClass.__init__  s     nn-j 45Ei5P4QQYZ &E 6 < <$,$4Y$?#*#4Y#?.  *~~.RTUV&NN+LdS ot5tFvFr   )r   r   r    rF   r   )r6   r  r	  r  r   rA   s   @r   r  r    s    G Gr   r  )r+   r   r   rw   rh   class_deprecated	NameErrorrs   )	r   r  r   rA   ry   deprecated_warning_classdeprecated_warning_kwargsr  r	  s	   `` `   @@r   class_renamedr    s    $ "$J8@BRS\B]^,3J()2JJ./ (*00 (3(3>

9: >W
9:4;J0178J34<G
89<LQ<O
899,
CCy! 	G 	Gi 	G* 1s   9B "B,+B,c                    |t        |       }t        d      }| d|d|dt        |       dt        |       }t        d      }t        || |||t        t
        j                  |t        |       |t        |       |t        |       d      S )zZnice wrapper around class_renamed when a class has been moved into
    another module
    rX   zclass r   z is now available as )r   r   r   r   r   rA   r   )r   rA   ry   r  r  )r+   rh   r-   r  r   r   r   rw   )r  r   r   rA   r   ry   s         r   class_movedr    s     #I.!!$Jy)Y'	
 #1%K!>*00$,Y7 (3(3#
 r   )rX   )Nr   Nr   r   )NNN)>r!   __docformat__r`   r[   rq   enumr   warningsr   	functoolsr   r   typingr   r	   r
   r   r   typing_extensionsr   version_info	importlibr   importlib_metadataDistributionr   r&   r8   r+   r-   r<   objectr>   r   rh   ri   __annotations__rw   rN   rM   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r
  r   r   r  r   r   r  r  r   r   r   <module>r     sZ  $ % 	 
    : 6 6 &v8)66  GH G GIh I3 I#% #%X #%L0 0DS  6 ?C $sHSM'9":; B J "!%./ #38n c]	
  # 
.T $ #5 &&B &"1)E 1&B *$@ *, EI$$!)$4<SM$$N ?O%5?3(3-0(:	; 
% %hsm %x %P &%STSM+3C=MP  B  *:(;*
& 
B ./ T Ts TXc] TV^ Tn/s /c /HSM /U] /d 9}=9}= ""444 c]4 	4
 sm4 4 > >4n BR>Bx#s3X=>  "!!%<"DDD c]D c]	D
 #D 
DR #!!	((sm( c]( c]	(
 
(r   