o i5@sUddlmZddlZddlZddlZddlmZddlmZddl m Z ddl m Z ddl mZmZmZmZddlmZerKdd lmZdd lmZejd krWdd lmZnzdd lmZWneymdFddZYnwddlmZerddlmZddl mZddlmZedZ edZ!dddZ"de#d<dddGd"d#Z$dFd$d%Z%dHd&d'Z&dId*d+Z'dJd/d0Z( dKdLd4d5Z)dMd7d8Z*dNd9d:Z+dOd>d?Z,dPdCdDZ-gdEZ.dS)Q) annotationsN) defaultdict)Sequence)wraps)Path) TYPE_CHECKINGAnyTypeVarget_args)DeprecationType)Callable)IdentityFunction)  deprecatedmessagestrreturnr cCst|SN)_deprecate_functionrrP/home/app/Keep/.python/lib/python3.10/site-packages/polars/_utils/deprecation.pyrsr) issue_warning)Mapping) ParamSpec) AmbiguousPTZearliestZlatest)TFzMapping[bool, Ambiguous]USE_EARLIEST_TO_AMBIGUOUSversionr#NonecCs&|r |d|d}t|tdS)a 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)striprDeprecationWarning)rr#rrrissue_deprecation_warning/s r(cdfdd }|S)z+Decorator to mark a function as deprecated.functionCallable[P, T]rcs.td fdd }t|_|_|S) NargsP.argskwargsP.kwargsrrcst|i|Srr(r,r.)r*rrrwrapperDsz6_deprecate_function..decorate..wrapperr,r-r.r/rr)rinspect signature __signature__Z__deprecated__r*r2rr*rdecorateCs  z%_deprecate_function..decorateNr*r+rr+r)rr9rrrr@s rcCsddd}|S)zJDecorator to mark `streaming` argument as deprecated due to being renamed.r*r+rcs&td fdd }t|_|S) Nr,r-r.r/rrcsFd|vrtd|drd|d<nd|vrd|d<|d=|i|S)NZ streamingzIthe `streaming` parameter was deprecated in 1.25.0; use `engine` instead.Zenginez in-memoryr0r1r8rrr2Ts z@deprecate_streaming_parameter..decorate..wrapperr3rr4r5r6r7rr8rr9Ss z/deprecate_streaming_parameter..decorateNr:r)r9rrrdeprecate_streaming_parameterPs r<old_namenew_namecdfdd }|S)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. r*r+rcs,td fdd }t|_|S) Nr,r-r.r/rrcs t|j|i|Sr)_rename_keyword_argument __qualname__r1)r*r>r=r#rrr2{s z>deprecate_renamed_parameter..decorate..wrapperr3r;r7r>r=r#r8rr9zs z-deprecate_renamed_parameter..decorateNr:r)r=r>r#r9rrBrdeprecate_renamed_parameteris rCr.dict[str, object] func_namec Cs||vrM||vr*|rd|nd}d|d|d|d|d|d|d }t||r1d |nd }td |d |d|d|d ||||<dSdS)z(Rename a keyword argument of a function.zwas deprecated in version z is deprecated`z` received both `z` and `z` as arguments; `z` z, use `z ` insteadz in version r!zthe argument `z` for `z$` is deprecated. It was renamed to `.N) TypeErrorr(pop)r=r>r.rEr#Z is_deprecatedmsgZ in_versionrrrr@s.r@ allowed_argslist[str] | None str | Nonecr?)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. r*r+rcst}dur n dd|jDfdd|jD}|jddd|j|d}tdurHdjd }|jt d nt dfdd }||_ |S)NcSs0g|]}|j|j|jfvr|j|jur|jqSr)kindPOSITIONAL_ONLYPOSITIONAL_OR_KEYWORDdefaultemptyname.0prrr s  zDdeprecate_nonkeyword_arguments..decorate..cs:g|]}|j|j|jfvr|jvr|j|jdn|qS)rN)rNrOrPrSreplace KEYWORD_ONLYrT) allow_argsrrrWs cSs|jSrrX)rVrrrszBdeprecate_nonkeyword_arguments..decorate..)key) parameterszall arguments of zo{except_args} will be keyword-only in the next breaking release. Use keyword arguments to silence this warning.)Z except_argsr,r-r.r/rrcs&t|kr td|i|S)Nr")lenr(r1)r*rJnum_allowed_argsr#rrr2s  zAdeprecate_nonkeyword_arguments..decorate..wrapperr3) r4r5r^valuessortrYr_rAformat_format_argument_listrr6)r*Zold_sig new_paramsZnew_sigZ msg_formatr2rKrr#)r[r*rJr`rr9s*    z0deprecate_nonkeyword_arguments..decorateNr:r)rKrr#r9rrfrdeprecate_nonkeyword_argumentss-rg list[str]cCshd|vr |d|s dSt|dkrd|dS|d}ddd |d dD}d|d |S) zaFormat allowed arguments list for use in the warning message of `deprecate_nonkeyword_arguments`.selfr!z except for rz, cSsg|]}|qSrr)rUxrrrrWsz)_format_argument_list..Nz and )remover_join)rKlastr,rrrrds  rdcr))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. r*r+rcs(td fdd }t|_|S) Nr,r-r.r/rrcsz|}Wnty|i|YSwtddt|tr*t|tr.|f}n t|ts7t|}||}|i|S)Nz passing `zP` as a keyword argument is deprecated. Pass it as a positional argument instead.)rIKeyErrorr( isinstancerrtuple)r,r. arg_value)r*r=rrr2s   zJdeprecate_parameter_as_multi_positional..decorate..wrapperr3r;r7r=r8rr9 s z9deprecate_parameter_as_multi_positional..decorateNr:r)r=r9rrtr'deprecate_parameter_as_multi_positionalsrusource module_pathdefaultdict[str, list[str]]cs`t|}gd fdd d fdd ttGfd d d tj}||S)N decoratorrrrcs:t|tjrd|jvr|jSdSt|tjr|jSdS)NZ deprecater!)rqastNameidCallfunc)ryrrrr.s   z._find_deprecated_functions..deprecatedrEcsdg|S)NrG)rn)rE)rw object_pathrrqualified_name5sz2_find_deprecated_functions..qualified_namecs0eZdZd fdd Zd fdd ZeZd S) z3_find_deprecated_functions..FunctionVisitornoderrr$cs"|j||dSr)appendrS generic_visitrI)rir)rrrvisit_ClassDef;s   zB_find_deprecated_functions..FunctionVisitor.visit_ClassDefcsNtfdd|jDr ddd}||j||dS)Nc3s|] }|VqdSrr)rUd)decorator_namerrr AszX_find_deprecated_functions..FunctionVisitor.visit_FunctionDef..Z deprecate_rr*)anydecorator_list removeprefixrYrrSr)rirr])rrresults)rrvisit_FunctionDef@s  zE_find_deprecated_functions..FunctionVisitor.visit_FunctionDefN)rrrr$)__name__ __module__rArrvisit_AsyncFunctionDefr)rrrrrrFunctionVisitor:sr)ryrrr)rErrr)rzparserlist NodeVisitorvisit)rvrwtreerr)rrwrrrr_find_deprecated_functions(s  rtypesr dict[str, list[str]]c sttt}D]}||vr"d|dtt|dd}t|qttjdj j }t t | dD]K}||}d|jd}|jd d d ,}t||d D]\} } | |vrid|d }t|| | qWWdn1s{wYq5fddtDS)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', ]} zunrecognised deprecation type z. Expected one (or more) of rjrkZpolarsz*.pyrGz.pyrzutf-8)encoding)rvrwz. Ncs&i|]}r |vr|t|qSr)sorted)rUdeprrrr s z)identify_deprecations..)setr r reprr ValueErrorrsysmodules__file__parentrrrglob relative_tornparts removesuffixopenrreaditemsextend) rZ valid_typestprJ package_pathZpy_filerel_pathrwsrcZdeprecation_typeZ func_namesrrridentify_deprecationsNs>     r)rgrurCr<rr)rrrr )rrr#rrr$)rr )r=rr>rr#rrr ) r=rr>rr.rDrErr#rrr$)NN)rKrLrrMr#rrr )rKrhrr)r=rrr )rvrrwrrrx)rr rr)/ __future__rrzr4r collectionsrcollections.abcr functoolsrpathlibrtypingrrr r Zpolars._typingr r Zpolars._utils.variousr version_infowarningsrZtyping_extensions ImportErrorrrrrrrr __annotations__r(rr<rCr@rgrdrurr__all__rrrrsT                  M  * & ?