hBFddlmZddlmZddlZddlmZddlmZm Z m Z m Z ddl Z ddl mZddlmZmZddlmZerdd lmZ d dd Z d dd Zdd Zdd Z d ddZddZGddZGddZdd dZgdZy)!) annotations)wrapsN)dedent) TYPE_CHECKINGAnyCallablecast)cache_readonly)FT)find_stack_level)Mappingc  |xs j}xst|xs|d|d td  fd }|xsd|d}dj}jrjj ddkr t |jj dd\} } } } | s| r | s t |td | jd |d |d t| |_|S)a Return a new function that emits a deprecation warning on use. To use this method for a deprecated function, another function `alternative` with the same signature must exist. The deprecated function will emit a deprecation warning, and in the docstring it will contain the deprecation directive with the provided version so it can be detected for future removal. Parameters ---------- name : str Name of function to deprecate. alternative : func Function to use instead. version : str Version of pandas in which the method has been deprecated. alt_name : str, optional Name to use in preference of alternative.__name__. klass : Warning, default FutureWarning stacklevel : int, default 2 msg : str The message to display in the warning. Default is '{name} is deprecated. Use {alt_name} instead.' z is deprecated, use instead.cDtj|i|S)N stacklevel)warningswarn)argskwargs alternativeklassr warning_msgs .wrapper?s# k5Z@D+F++zUse `z ` instead.zdeprecate needs a correctly formatted docstring in the target function (should have a one liner short summary, and opening quotes should be in their own line). Found:  z z .. deprecated:: z z returnCallable[..., Any]) __name__ FutureWarningr__doc__countAssertionErrorsplitrstrip)namerversionalt_namerrmsgr doc_error_msgempty1summaryempty2 doc_stringrs ` `` @r deprecater3s0D/;//H  "]EID6!5hZyIK ;,,  -5 *-C &--. 0    $ $T *Q . / /.9.A.A.G.Ga.P+ VG / /   " E      Nrch"tdsts tddfd }|S)a Decorator to deprecate a keyword argument of a function. Parameters ---------- old_arg_name : str Name of argument in function to deprecate new_arg_name : str or None Name of preferred argument in function. Use None to raise warning that ``old_arg_name`` keyword is deprecated. mapping : dict or callable If mapping is present, use it to translate old arguments to new arguments. A callable must do its own value checking; values not found in a dict will be forwarded unchanged. Examples -------- The following deprecates 'cols', using 'columns' instead >>> @deprecate_kwarg(old_arg_name='cols', new_arg_name='columns') ... def f(columns=''): ... print(columns) ... >>> f(columns='should work ok') should work ok >>> f(cols='should raise warning') # doctest: +SKIP FutureWarning: cols is deprecated, use columns instead warnings.warn(msg, FutureWarning) should raise warning >>> f(cols='should error', columns="can't pass do both") # doctest: +SKIP TypeError: Can only specify 'cols' or 'columns', not both >>> @deprecate_kwarg('old', 'new', {'yes': True, 'no': False}) ... def f(new=False): ... print('yes!' if new else 'no!') ... >>> f(old='yes') # doctest: +SKIP FutureWarning: old='yes' is deprecated, use new=True instead warnings.warn(msg, FutureWarning) yes! To raise a warning that a keyword will be removed entirely in the future >>> @deprecate_kwarg(old_arg_name='cols', new_arg_name=None) ... def f(cols='', another_param=''): ... print(cols) ... >>> f(cols='should raise warning') # doctest: +SKIP FutureWarning: the 'cols' keyword is deprecated and will be removed in a future version please takes steps to stop use of 'cols' should raise warning >>> f(another_param='should not raise warning') # doctest: +SKIP should not raise warning >>> f(cols='should raise warning', another_param='') # doctest: +SKIP FutureWarning: the 'cols' keyword is deprecated and will be removed in a future version please takes steps to stop use of 'cols' should raise warning getzAmapping from old to new argument values must be dict or callable!cVtdfd }tt|S)Nc F|jd}|Cdtdt}tj|t ||<|i|SHt r |}nj ||}ddt|ddt|d }n|}dtdtd}tj|t |j &dtdtd }t|||<|i|S) Nzthe ze keyword is deprecated and will be removed in a future version. Please take steps to stop the use of r=z keyword is deprecated, use rzCan only specify z or z , not both.)popreprrrr$callabler5 TypeError) rr old_arg_valuer- new_arg_valuefuncmapping new_arg_name old_arg_namers rrz:deprecate_kwarg.._deprecate_kwarg..wrapperss"JJ|T:M('tL1234484F3GI MM#}L+8F<(000(((/ (> (/ M=(Q |nAd=.A-BC+'.$}*=)>iI %2MtL123#L12)=  c=ZH::l+7+D,>+?@"<01>$C.('4|$(( (rr )rr r )r?rr@rArBrs` r_deprecate_kwargz)deprecate_kwarg.._deprecate_kwargs. t' )' ) ' )RAwrr?r r!r )hasattrr;r<)rBrAr@rrCs```` rdeprecate_kwargrFds?F77E#:8GCT O  + + Z rcd|vr|jd|syt|dk(r d|ddS|d}dj|d dDcgc] }d|zdz c}}d |d |dScc}w) a5 Convert the allow_args argument (either string or integer) of `deprecate_nonkeyword_arguments` function to a string describing it to be inserted into warning message. Parameters ---------- allowed_args : list, tuple or int The `allowed_args` argument for `deprecate_nonkeyword_arguments`, but None value is not allowed. Returns ------- str The substring describing the argument list in best way to be inserted to the warning message. Examples -------- `format_argument_list([])` -> '' `format_argument_list(['a'])` -> "except for the arguments 'a'" `format_argument_list(['a', 'b'])` -> "except for the arguments 'a' and 'b'" `format_argument_list(['a', 'b', 'c'])` -> "except for the arguments 'a', 'b' and 'c'" selfz except for the argument 'r'z, Nz except for the arguments z and ')removelenjoin) allow_argslastxrs r_format_argument_listrSs4&!  ZA +JqM?!<<"~yyCRAA#'C-AB+D6vQ??BsA&c|yd|S)zCSpecify which version of pandas the deprecation will take place in.zIn a future version of pandaszStarting with pandas version )r+s rfuture_version_msgrVs..wi88rcfd}|S)a Decorator to deprecate a use of non-keyword arguments of a function. Parameters ---------- version : str, optional The version in which positional arguments will become keyword-only. If None, then the warning message won't specify any particular version. allowed_args : list, optional In case of list, it must be the list of names of some first arguments of the decorated functions that are OK to be given as positional arguments. In case of None value, defaults to list of all arguments not having the default value. name : str, optional The specific name of the function to show in the warning message. If None, then the Qualified name of the function is used. ctj}  nn|jjDcgc]J}|j|j |j fvr$|j|jur |jLc}|jjDcgc]R}|j|j |j fvr*|jvr|j|jn|T}}|jd|j|}tt d xs jdt!fd}||_|Scc}wcc}w)Nkindc|jSNrY)ps rzBdeprecate_nonkeyword_arguments..decorate..<saffr)key) parametersz all arguments of z!{arguments} will be keyword-only.ct|kDr=tjjt t t |i|S)N) argumentsr)rNrrformatrSr$r )rrrPr?r-num_allow_argss rrzAdeprecate_nonkeyword_arguments..decorate..wrapperEsJ4y>) JJ)>z)JJK!/1 (( (r)inspect signaturer`valuesrZPOSITIONAL_ONLYPOSITIONAL_OR_KEYWORDdefaultemptyr*replace KEYWORD_ONLYsortrNrV __qualname__r __signature__) r?old_sigr] new_paramsnew_sigrrPr-rd allowed_argsr*r+s ` @@@rdecoratez0deprecate_nonkeyword_arguments..decorate&s##D)  #%J!++2244A66a//1H1HIIII(4J''..0 1 1,,a.E.EFFFF*, II1>>I *    1   ,-//Z/8Z!'*++=(t(())L N t )  )!(M s AE1*AE6rU)r+rtr*rus``` rdeprecate_nonkeyword_argumentsrv s8,\ Orcdfd }|S)a A decorator to take docstring templates, concatenate them and perform string substitution on them. This decorator will add a variable "_docstring_components" to the wrapped callable to keep track the original docstring template for potential usage. If it should be consider as a template, it will be saved as a string. Otherwise, it will be saved as callable, and later user __doc__ and dedent to get docstring. Parameters ---------- *docstrings : None, str, or callable The string / docstring / docstring template to be appended in order after default docstring under callable. **params The string which would be used to format docstring template. c fg}|jr$|jt|jD][}|t|dr|j |j .t |ts |jsK|j|]|Dcgc]4}t |tr tdkDr|jdin|6}}dj|Dcgc]-}t |tr|nt|jxsd/c}|_||_|Scc}wcc}w)N_docstring_componentsrrIrU) r%appendrrEextendry isinstancestrrNrcrO) decorateddocstring_components docstring componentparams_applied docstringsparamss r decoratorzdoc..decoratorksM57    ' 'y/@/@(A B#I y"9:$++33Is+y/@/@$++I6$2  2 )S)c&kAo I   &v & 2  GG "0  "0Ii-I--345"0    ! ')  s 9D)"2D.)r~r r!r rU)rrrs`` rdocrWs($L rc(eZdZdZddZddZddZy) Substitutiona/ A decorator to take a function's docstring and perform string substitution on it. This decorator should be robust even if func.__doc__ is None (for example, if -OO was passed to the interpreter) Usage: construct a docstring.Substitution with a sequence or dictionary suitable for performing substitution; then decorate a suitable function with the constructed object. e.g. sub_author_name = Substitution(author='Jason') @sub_author_name def some_function(x): "%(author)s wrote this function" # note that some_function.__doc__ is now "Jason wrote this function" One can also use positional arguments. sub_first_last_names = Substitution('Edgar Allen', 'Poe') @sub_first_last_names def some_function(x): "%s %s wrote the Raven" c8|r |r td|xs||_y)Nz+Only positional or keyword args are allowed)r'rrHrrs r__init__zSubstitution.__init__s F !NO Onf rc^|jxr|j|jz|_|Sr\)r%r)rHr?s r__call__zSubstitution.__call__s$||B t{{(B  rcrt|jtr|jj|i|yy)z8 Update self.params with supplied args. N)r|rdictupdaters rrzSubstitution.updates0 dkk4 ( DKK   / / )rN)r!NonerD)r# __module__ror%rrrrUrrrrs8% 0rrc.eZdZUdZded<dddZd dZy) Appenderaf A function decorator that will append an addendum to the docstring of the target function. This decorator should be robust even if func.__doc__ is None (for example, if -OO was passed to the interpreter). Usage: construct a docstring.Appender with a string to be joined to the original docstring. An optional 'join' parameter may be supplied which will be used to join the docstring and addendum. e.g. add_copyright = Appender("Copyright (c) 2009", join=' ') @add_copyright def my_dog(has='fleas'): "This docstring will have a copyright below" pass str | Noneaddendumc^|dkDrt|||_||_y||_||_y)Nr)indents)indentrrO)rHrrOrs rrzAppender.__init__s0 Q;"8W=DM %DM rc|jr |jnd|_|jr |jnd|_|j|jg}t|jj||_|S)NrI)r%rrrO)rHr?docitemss rrzAppender.__call__sX'+||t|| )- B LL$--0diinnX67  rN)rIr)rrrOr}rintr!r)r?r r!r )r#rror%__annotations__rrrUrrrrs&rrc|rt|tsydjdgdg|zz}|j|jdS)NrIrz )r|r}rOr()textrjointexts rrrsE z$,wwv7 223H ==D) **r)rr r3rFrvrrVr)NNN)r*r}rr"r+r}r,rrztype[Warning] | Nonerrr-rr!Callable[[F], F])Nr) rBr}rArr@z/Mapping[Any, Any] | Callable[[Any], Any] | Nonerrr!r)rPz list[str]r!r})r+rr!r})NN)r+rrtzlist[str] | Noner*rr!r)rzNone | str | Callabler!r)rJ)rrrrr!r}) __future__r functoolsrretextwraprtypingrrrr rpandas._libs.propertiesr pandas._typingr r pandas.util._exceptionsr collections.abcrr3rFrSrVrvrrrr__all__rUrrrsK" 25' "&H H#HH H H  H HH\@D uuu=u u  up#@L9&*J J"J J JZ:B,0,0^""J+ r