
    h5                    L   % S SK Jr  S SKrS SKrS SKrS SKJr  S SKJr  S SK	J
r
  S SKJr  S SKJrJrJrJrJr  S SKJr  \R*                  S	:  a  S S
KJr  O S S
KJr  S SKJr  \(       a9  S SKJr  \R*                  S:  a  S SKJr  OS SKJr  S SKJr  \" S5      r\" S5      r SSS.r!S\"S'   SS.S&S jjr#S%S jr$S'S jr%        S(S jr&            S)S jr' S*       S+S jjr(S,S  jr)    S-S! jr*      S.S" jr+S/S# jr,/ S$Qr-g! \ a        S%S jr Nf = f)0    )annotationsN)defaultdict)Sequence)wraps)Path)TYPE_CHECKINGAnyCallableTypeVarget_args)DeprecationType)      )
deprecatedc                    [        U 5      $ N)_deprecate_function)messages    S/home/james-whalen/.local/lib/python3.13/site-packages/polars/_utils/deprecation.pyr   r      s     'w//    )issue_warning)Mapping)r   
   )	ParamSpec)	AmbiguousPTearliestlatest)TFzMapping[bool, Ambiguous]USE_EARLIEST_TO_AMBIGUOUS versionc               ^    U(       a  U R                  5        SU S3n [        U [        5        g)z
Issue a deprecation warning.

Parameters
----------
message
    The message associated with the warning.
version
    The version in which deprecation occurred
    (if the version number was not already included in `message`).
z
(Deprecated in version )N)stripr   DeprecationWarning)r   r#   s     r   issue_deprecation_warningr(   /   s,     ]]_%%>wiqI'-.r   c                   ^  SU 4S jjnU$ )z+Decorator to mark a function as deprecated.c                |   >^  [        T 5      SU U4S jj5       n[        R                  " T 5      Ul        TUl        U$ )Nc                 *   > [        T5        T" U 0 UD6$ r   r(   )argskwargsfunctionr   s     r   wrapper6_deprecate_function.<locals>.decorate.<locals>.wrapperD   s    %g.T,V,,r   r-   zP.argsr.   zP.kwargsreturnr   )r   inspect	signature__signature____deprecated__)r/   r0   r   s   ` r   decorate%_deprecate_function.<locals>.decorateC   s;    	x	- 
	- !( 1 1( ;!(r   r/   Callable[P, T]r3   r;    )r   r8   s   ` r   r   r   @   s     Or   c                     SS jn U $ )zJDecorator to mark `streaming` argument as deprecated due to being renamed.c                j   ^  [        T 5      SU 4S jj5       n[        R                  " T 5      Ul        U$ )Nc                 r   > SU;   a)  [        S5        US   (       a  SUS'   OSU;  a  SUS'   US	 T" U 0 UD6$ )N	streamingzIthe `streaming` parameter was deprecated in 1.25.0; use `engine` instead.enginez	in-memoryr,   )r-   r.   r/   s     r   r0   @deprecate_streaming_parameter.<locals>.decorate.<locals>.wrapperT   sT    f$)_ +&'2F8$V+'2F8$;'T,V,,r   r2   r   r4   r5   r6   )r/   r0   s   ` r   r8   /deprecate_streaming_parameter.<locals>.decorateS   s3    	x	- 
	- !( 1 1( ;r   r:   r<   )r8   s    r   deprecate_streaming_parameterrE   P   s    & Or   c                   ^ ^^ SUU U4S jjnU$ )a  
Decorator to mark a function parameter as deprecated due to being renamed.

Use as follows:

    @deprecate_renamed_parameter("old_name", new_name="new_name")
    def myfunc(new_name): ...

Ensure that you also update the function docstring with a note about the
deprecation, specifically adding a `.. versionchanged:: 0.0.0` directive
that states which parameter was renamed to which new name and in which
version the rename happened.
c                r   >^  [        T 5      SU UUU4S jj5       n[        R                  " T 5      Ul        U$ )Nc                 F   > [        TTUTR                  T5        T" U 0 UD6$ r   )_rename_keyword_argument__qualname__)r-   r.   r/   new_nameold_namer#   s     r   r0   >deprecate_renamed_parameter.<locals>.decorate.<locals>.wrapper{   s.    $(FH,A,A7 T,V,,r   r2   rC   )r/   r0   rK   rL   r#   s   ` r   r8   -deprecate_renamed_parameter.<locals>.decoratez   s8    	x	- 	- 
	- !( 1 1( ;r   r:   r<   )rL   rK   r#   r8   s   ``` r   deprecate_renamed_parameterrO   i   s    "	 	 Or   c                    X;   ar  X;   a3  U(       a  SU 3OSnSU< SU < SU< SU < SU SU< S	3n[        U5      eU(       a  S
U 3OSn[        SU  SU SU SU S3	5        UR                  U 5      X!'   gg)z(Rename a keyword argument of a function.zwas deprecated in version zis deprecated`z` received both `z` and `z` as arguments; `z` z, use `z	` insteadz in version r!   zthe argument `z` for `z$` is deprecated. It was renamed to `.N)	TypeErrorr(   pop)rL   rK   r.   	func_namer#   is_deprecatedmsg
in_versions           r   rI   rI      s     :A,WI6  I= 1(WXL QL=/IO  C. 18|G9-b
!XJgi[ 9""*1ZL;	
 "::h/! r   c                   ^ ^^ SU UU4S jjnU$ )a  
Decorator for deprecating the use of non-keyword arguments in a function.

Use as follows:

    @deprecate_nonkeyword_arguments(allowed_args=["self", "val"], version="1.0.0")
    def myfunc(self, val: int = 0, other: int: = 0): ...

Ensure that you also update the function docstring with a note about the
deprecation, specifically adding a `.. versionchanged:: 0.0.0` directive
that states that we now expect keyword args and in which version this
update happened.

Parameters
----------
allowed_args
    The names of some first arguments of the decorated function that are allowed to
    be given as positional arguments. Should include "self" when decorating class
    methods. If set to None (default), equal to all arguments that do not have a
    default value.
message
    Optionally overwrite the default warning message.
version
    The Polars version number in which the warning is first issued.
c                (  >^ ^^	 [         R                  " T 5      nT
b  T
nOwUR                  R                  5        Vs/ s HR  nUR                  UR
                  UR                  4;   d  M+  UR                  UR                  L d  MF  UR                  PMT     nnUR                  R                  5        Vs/ s HT  nUR                  UR
                  UR                  4;   a)  UR                  U;  a  UR                  UR                  S9OUPMV     nnUR                  S S9  UR                  US9n[        U5      m	Tc)  ST R                   S3nUR                  [!        U5      S9mOTm[#        T 5      S	U UU	U4S jj5       nXWl        U$ s  snf s  snf )
Nkindc                    U R                   $ r   r[   )ps    r   <lambda>Bdeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.<lambda>   s    affr   )key)
parameterszall arguments of zo{except_args} will be keyword-only in the next breaking release. Use keyword arguments to silence this warning.)except_argsc                 F   > [        U 5      T:  a
  [        TTS9  T" U 0 UD6$ )Nr"   )lenr(   )r-   r.   r/   rW   num_allowed_argsr#   s     r   r0   Adeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.wrapper   s*    4y++)#w?T,V,,r   r2   )r4   r5   rb   valuesr\   POSITIONAL_ONLYPOSITIONAL_OR_KEYWORDdefaultemptynamereplaceKEYWORD_ONLYsortre   rJ   format_format_argument_listr   r6   )r/   old_sig
allow_argsr^   
new_paramsnew_sig
msg_formatr0   rW   rf   allowed_argsr   r#   s   `       @@r   r8   0deprecate_nonkeyword_arguments.<locals>.decorate   s   ##H-#%J !++2244A66a//1H1HII  II( 4   ''..0
 1	 1,,a.E.EFFFF*, II1>>I*
  1 	 
 	,-//Z/8z??#H$9$9#: ;B B  ##0Ej0Q#RCC	x	- 	- 
	-
 !(K
s   *F
+F
F
4AFr:   r<   )rx   r   r#   r8   s   ``` r   deprecate_nonkeyword_argumentsrz      s    :+ +Z Or   c                    SU ;   a  U R                  S5        U (       d  g[        U 5      S:X  a	  SU S   < 3$ U S   nSR                  U SS  Vs/ s H  o"< PM     sn5      nSU S	U< 3$ s  snf )
zaFormat allowed arguments list for use in the warning message of `deprecate_nonkeyword_arguments`.selfr!      z except for r   z, Nz and )removere   join)rx   lastxr-   s       r   rr   rr      s    F#	\	a	l1o011ByyL",=>,=qE(,=>?dV511 ?s   A,c                   ^  SU 4S jjnU$ )a  
Decorator to mark a function argument as deprecated due to being made multi-positional.

Use as follows:

    @deprecate_parameter_as_multi_positional("columns")
    def myfunc(*columns): ...

Ensure that you also update the function docstring with a note about the
deprecation, specifically adding a `.. versionchanged:: 0.0.0` directive
that states that we now expect positional args and in which version this
update happened.
c                n   >^  [        T 5      SU U4S jj5       n[        R                  " T 5      Ul        U$ )Nc                 *  >  UR                  T5      n[        ST S35        [        U[        5      (       a  [        U[
        5      (       a  U4nO [        U[        5      (       d  [        U5      nX-   n T" U 0 UD6$ ! [         a    T" U 0 UD6s $ f = f)Nz	passing `zP` as a keyword argument is deprecated. Pass it as a positional argument instead.)rT   KeyErrorr(   
isinstancer   strtuple)r-   r.   	arg_valuer/   rL   s      r   r0   Jdeprecate_parameter_as_multi_positional.<locals>.decorate.<locals>.wrapper  s    1"JJx0	 &H: &= =
 i22jC6P6P&L		511!),	#DT,V,,  10001s   A= =BBr2   rC   )r/   r0   rL   s   ` r   r8   9deprecate_parameter_as_multi_positional.<locals>.decorate  s3    	x	- 
	-& !( 1 1( ;r   r:   r<   )rL   r8   s   ` r   'deprecate_parameter_as_multi_positionalr      s    "0 Or   c                   ^^^^^ [         R                  " U 5      n/ mSU4S jjmSUU4S jjm[        [        5      m " UUUU4S jS[         R                  5      nU" 5       R                  U5        T$ )Nc                   > [        U [        R                  5      (       a  SU R                  ;   a  U R                  $ S$ [        U [        R                  5      (       a  T" U R
                  5      $ g)N	deprecater!   )r   astNameidCallfunc)	decoratorr   s    r   r   ._find_deprecated_functions.<locals>.deprecated0  sQ    i**#.),,#>9<<FBF	388,,inn--r   c                0   > SR                  T/TQU P5      $ )NrR   )r   )rU   module_pathobject_paths    r   qualified_name2_find_deprecated_functions.<locals>.qualified_name7  s    xx>{>I>??r   c                  >   > \ rS rSrSU4S jjrSU UU4S jjr\rSrg)3_find_deprecated_functions.<locals>.FunctionVisitori<  c                ~   > TR                  UR                  5        U R                  U5        TR                  5         g r   )appendrm   generic_visitrT   )r|   noder   s     r   visit_ClassDefB_find_deprecated_functions.<locals>.FunctionVisitor.visit_ClassDef=  s-    tyy)t$OOr   c                   >^ [        UU4S jUR                   5       5      (       aE  TR                  S5      R                  SS5      nTU   R	                  T" UR
                  5      5        U R                  U5        g )Nc              3  8   >#    U  H  nT" U5      =mv   M     g 7fr   r<   ).0ddecorator_namer   s     r   	<genexpr>X_find_deprecated_functions.<locals>.FunctionVisitor.visit_FunctionDef.<locals>.<genexpr>C  s     R>Qjm3N3>Qs   
deprecate_r   r/   )anydecorator_listremoveprefixrn   r   rm   r   )r|   r   ra   r   r   r   resultss      @r   visit_FunctionDefE_find_deprecated_functions.<locals>.FunctionVisitor.visit_FunctionDefB  se    Rd>Q>QRRR$11,?GG * ##N499$=>t$r   r<   N)r   r	   r3   None)__name__
__module__rJ   __firstlineno__r   r   visit_AsyncFunctionDef__static_attributes__)r   r   r   r   s   r   FunctionVisitorr   <  s    	
	% 	% "3r   r   )r   r	   r3   r   )rU   r   r3   r   )r   parser   listNodeVisitorvisit)sourcer   treer   r   r   r   r   s    `  @@@@r   _find_deprecated_functionsr   *  sb     99VDK@ @ $G3 3#// 3  D!Nr   c            	     B   [        [        [        5      5      nU  H1  nX!;  d  M
  SU< S[        [	        U5      5      SS  3n[        U5      e   [        [        R                  S   R                  5      R                  n[        [        5      nUR                  S5       H  nUR                  U5      nSR                  UR                   5      R#                  S5      nUR%                  S	S
S9 n	['        U	R)                  5       US9R+                  5        H/  u  pX;  a  SW< S3n[        U5      eXZ   R-                  U5        M1     SSS5        M     [	        U5       Vs0 s H  nU (       a  X;   d  M  U[	        X\   5      _M!     sn$ ! , (       d  f       M  = fs  snf )a%  
Return a dict identifying functions/methods that are deprecated in some way.

Parameters
----------
*types
    The types of deprecations to identify.
    If empty, all types are returned; recognised values are:
        - "function"
        - "renamed_parameter"
        - "streaming_parameter"
        - "nonkeyword_arguments"
        - "parameter_as_multi_positional"

Examples
--------
>>> from polars._utils.deprecation import identify_deprecations
>>> identify_deprecations("streaming_parameter")  # doctest: +IGNORE_RESULT
{'streaming_parameter': [
    'functions.lazy.collect_all',
    'functions.lazy.collect_all_async',
    'lazyframe.frame.LazyFrame.collect',
    'lazyframe.frame.LazyFrame.collect_async',
    'lazyframe.frame.LazyFrame.explain',
    'lazyframe.frame.LazyFrame.show_graph',
]}
zunrecognised deprecation type z.
Expected one (or more) of r}   r~   polarsz*.pyrR   z.pyrzutf-8)encoding)r   r   z.
N)setr   r   reprsorted
ValueErrorr   sysmodules__file__parentr   r   rglobrelative_tor   partsremovesuffixopenr   readitemsextend)typesvalid_typestprW   package_pathr   py_filerel_pathr   srcdeprecation_type
func_namesdeps                r   identify_deprecationsr   P  s   8 h/0K 0 7--1&2E-Fq-L,MO  S/!  H-667>>L$G%%f-&&|4hhx~~.;;EB\\#\0C0Jxxz'1 eg1,  $6 ;2&DC$S/))00<1 10 .$ '?"C 	"VGL!!"  10s   .AF
!F5F

F	)rz   r   rO   rE   r   r   )r   r   r3   *Callable[[Callable[P, T]], Callable[P, T]])r   r   r#   r   r3   r   )r3   r   )rL   r   rK   r   r#   r   r3   r   )rL   r   rK   r   r.   zdict[str, object]rU   r   r#   r   r3   r   )NN)rx   zlist[str] | Noner   z
str | Noner#   r   r3   r   )rx   z	list[str]r3   r   )rL   r   r3   r   )r   r   r   r   r3   zdefaultdict[str, list[str]])r   r   r3   zdict[str, list[str]]).
__future__r   r   r4   r   collectionsr   collections.abcr   	functoolsr   pathlibr   typingr   r	   r
   r   r   polars._typingr   version_infowarningsr   typing_extensionsImportErrorpolars._utils.variousr   r   r   r   r   r   r    __annotations__r(   r   rE   rO   rI   rz   rr   r   r   r   __all__r<   r   r   <module>r      s   " 
  
 # $   B B *w#00 0'
7"$/(#AA 7 3  ?A /" 2 .1/>000 0 	0
 0 
08 BFJ"J4>JSVJ/JZ2))/)X##!# #L<~y  0	0	07	00s   D D#"D#