U
|
®ý°dD ã
|
@ s8 d dl mZ d dlmZ d dlZd dlmZ d dlmZm Z m
|
Z
|
m Z d dl Z d dl mZ d dlmZmZ d dlmZ d/d
|
d d
|
d d dd ddddZd0d
|
d ddddddZdd
|
dddZd d
|
dd d Zd1d d d dd d d!Zd"dd#d$d%ZG d&d' d'ZG d(d) d)Zd2d dd
|
d+d,d-Z d)d.ddd!d%d d'gZ dS )3é )Ú annotations)ÚwrapsN)Údedent)ÚAnyÚCallableÚMappingÚcast)Úcache_readonly)ÚFÚT)Úfind_stack_levelé ÚstrúCallable[..., Any]ú
|
str | Noneztype[Warning] | NoneÚintzCallable[[F], F])ÚnameÚ alternativeÚversionÚalt_nameÚklassÚ
|
stacklevelÚmsgÚreturnc
|
sØ |p j }pt|p$| d| dt dd fdd }|pTd| d}d j } jrÔ j d
|
¡d k rt| j d
|
d ¡\} }
|
} } | s¢| rª|
|
sªt|td |
|
¡ d | d| dt| |_|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.r ©r c s t jd | |S )N©r )ÚwarningsÚwarn©ÚargsÚkwargs©r r r Z warning_msg© úNd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\pandas/util/_decorators.pyÚwrapper< s zdeprecate.<locals>.wrapperzUse `z
|
` instead.z§deprecate 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
|
|
|
) Ú__name__Ú FutureWarningr Ú__doc__ÚcountÚAssertionErrorÚsplitr Ústrip) r r r r r r r r% Z doc_error_msgZempty1ÚsummaryZempty2Z
|
doc_stringr# r" r$ Ú deprecate s4 "
|
|
ÿ
|
ÿýüúÿ r0 z/Mapping[Any, Any] | Callable[[Any], Any] | None)Ú old_arg_nameÚ new_arg_nameÚmappingr r c s@ dk r"t ds"t s"tdddd fdd }|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
|
NÚgetzAmapping from old to new argument values must be dict or callable!r
|
©Úfuncr c s, t dd fdd }tt|S )Nr r c s | d ¡}|d k rd krXdt dt }tj|td ||< | |S d k r¦trr|}n ||¡}d dt| d dt| d }n |}dt dt d}tj|td | ¡d k rdt d t d
|
}t|||< | |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 r z ' keyword is deprecated, use zCan only specify z or z , not both.)ÚpopÚreprr r r) Úcallabler4 Ú TypeError)r r! Z old_arg_valuer Z new_arg_value)r6 r3 r2 r1 r r# r$ r% ª s0
|
ÿ
|
|
$ÿÿÿz:deprecate_kwarg.<locals>._deprecate_kwarg.<locals>.wrapper)r r r
|
)r6 r% ©r3 r2 r1 r )r6 r$ Ú_deprecate_kwarg© s )z)deprecate_kwarg.<locals>._deprecate_kwarg)Úhasattrr: r; )r1 r2 r3 r r= r# r< r$ Údeprecate_kwarga s Cÿ-r? z list[str])Ú
|
allow_argsr c C sp d| kr| d¡ | sdS t| dkr6d| d dS | d }d d d
|
| d d
D ¡}d | d | dS d S )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'"
|
ÚselfÚ é z except for the argument 'r ú'éÿÿÿÿz, c S s g | ]}d | d qS )rD r# )Ú.0Úxr# r# r$ Ú
|
<listcomp>û s z)_format_argument_list.<locals>.<listcomp>Nz except for the arguments z and ')ÚremoveÚlenÚjoin)r@ Úlastr r# r# r$ Ú_format_argument_listÙ s
|
rM )r r c C s | dkr dS d| S dS )zCSpecify which version of pandas the deprecation will take place in.Nz In a future version of pandasz Starting with pandas version r# )r r# r# r$ Úfuture_version_msgÿ s rN zlist[str] | None)r Ú allowed_argsr r c s fdd}|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.
|
c s¦ t ¡}d k r ndd |j ¡ D fdd|j ¡ D }|jdd d |j|d}t t dpzj d t fd
|
d }||_
|
|S ) Nc S s0 g | ](}|j |j|jfkr|j|jkr|jqS r# )ÚkindÚPOSITIONAL_ONLYÚPOSITIONAL_OR_KEYWORDÚdefaultÚemptyr ©rF Úpr# r# r$ rH ) s ýzDdeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.<listcomp>c s: g | ]2}|j |j|jfkr2|j kr2|j|jd n|qS )©rP )rP rQ rR r ÚreplaceÚ KEYWORD_ONLYrU )r@ r# r$ rH 0 s üþýc S s | j S ©NrW )rV r# r# r$ Ú<lambda>9 ó zBdeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.<lambda>)Úkey)Ú
|
parametersz all arguments of z!{arguments} will be keyword-only.c s4 t | kr*tjjt dtt d | |S )N)Ú argumentsr )rJ r r ÚformatrM r) r r ©r@ r6 r Znum_allow_argsr# r$ r% B s ýzAdeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.wrapper) ÚinspectÚ signaturer^ ÚvaluesÚsortrX rJ rN Ú __qualname__r Ú __signature__)r6 Zold_sigÚ
|
new_paramsZnew_sigr% ©rO r r ra r$ Údecorate# s$
|
þ
|
ù ÿ z0deprecate_nonkeyword_arguments.<locals>.decorater# )r rO r rj r# ri r$ Ú deprecate_nonkeyword_arguments s .rk zNone | str | Callable)Ú
|
docstringsr c s ddd fdd }|S )aÏ
|
A decorator take docstring templates, concatenate them and perform string
|
substitution on it.
|
|
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.
|
r
|
)Ú decoratedr c s g }| j r| t| j ¡ D ]@}|d kr,q t|drD| |j¡ q t|tsT|j r | |¡ q fdd|D }d dd |D ¡| _ || _| S )NÚ_docstring_componentsc s2 g | ]*}t |tr*t d kr*|jf n|qS )r )Ú
|
isinstancer rJ r` ©rF Ú component)Úparamsr# r$ rH x s þÿ
|
ÿz*doc.<locals>.decorator.<locals>.<listcomp>rB c S s( g | ] }t |tr|n t|jp d qS )rB )ro r r r* rp r# r# r$ rH s þÿ) r* Úappendr r> Úextendrn ro r rK )rm Zdocstring_componentsZ docstringZparams_applied©rl rr r# r$ Ú decoratorh s.
|
ÿ
|
üüÿ ÿzdoc.<locals>.decoratorr# )rl rr rv r# ru r$ ÚdocT s &rw c @ s< e Zd ZdZddddZddddd Zddd
|
d Zd S ) Ú 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"
|
ÚNoner c O s |r|rt d|p|| _d S )Nz+Only positional or keyword args are allowed)r, rr ©rA r r! r# r# r$ Ú__init__² s zSubstitution.__init__r
|
r5 c C s |j o|j | j |_ |S rZ )r* rr )rA r6 r# r# r$ Ú__call__¸ s zSubstitution.__call__c O s t | jtr| jj|| dS )z8
|
Update self.params with supplied args.
|
N)ro rr ÚdictÚupdaterz r# r# r$ r~ ¼ s zSubstitution.updateN)r( Ú
|
__module__rf r* r{ r| r~ r# r# r# r$ rx s rx c @ s@ e Zd ZU dZded< dddddd d
|
d Zd d d ddZdS )Ú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
|
r ÚaddendumrB r r r ry )r rK Úindentsr c C s( |dkrt ||d| _n|| _|| _d S )Nr )r )Úindentr rK )rA r rK r r# r# r$ r{ Ú s zAppender.__init__r r5 c C sF |j r |j nd|_ | jr | jnd| _|j | jg}t| j |¡|_ |S )NrB )r* r r rK )rA r6 Zdocitemsr# r# r$ r| á s
|
zAppender.__call__N)rB r )r( r rf r* Ú__annotations__r{ r| r# r# r# r$ r Ä s
|
r rC )Útextr r c C s8 | rt | tsdS d dgdg| ¡}| | d¡¡S )NrB r& z )ro r rK r- )r
r Zjointextr# r# r$ r é s r r )NNr N)Nr )NN)rC ) Ú
|
__future__r Ú functoolsr rb Útextwrapr Útypingr r r r r Zpandas._libs.propertiesr Zpandas._typingr
|
r Zpandas.util._exceptionsr r0 r? rM rN rk rw rx r r Ú__all__r# r# r# r$ Ú<module> sD ù N üx&
|
ýMA/%ø
|
