o dr7@sdZddlmZddlmZmZmZmZddlZ ddl m Z ddl m Z mZedeeZedeedZd d Zd d Zd?ddZddZd?ddZd?ddZ d@dAddZdBdCd d!ZdDd%d&ZedEd(d)ZedFd,d)ZdGd/d)ZdHd3d4ZdId6d7ZdJd;d<Zd?d=d>Z dS)KzV Module that contains many useful utilities for validating data or function arguments ) annotations)IterableSequenceTypeVaroverloadN)lib)is_bool is_integerBoolishT BoolishNoneTc Csl|dkrtdt|t|kr4t||}t||}|dkr"dnd}t|d|d|d|d d S) z Checks whether 'args' has length of at most 'compat_args'. Raises a TypeError if that is not the case, similar to in Python when a function is called with too many arguments. rz*'max_fname_arg_count' must be non-negativeargument argumentsz() takes at most  z (z given)N) ValueErrorlen TypeError)fnameargsmax_fname_arg_count compat_argsZ max_arg_countZactual_arg_countr rK/app/.heroku/python/lib/python3.10/site-packages/pandas/util/_validators.py_check_arg_lengths  rc Cs|D]J}z)||}||}|dur|dus|dur |dur d}n||k}t|s,tdWnty>||||u}Ynw|sLtd|d|dqdS)z Check that the keys in `arg_val_dict` are mapped to their default values as specified in `compat_args`. Note that this function is to be called only when it has been checked that arg_val_dict.keys() is a subset of compat_args NFz'match' is not a booleanzthe 'z=' parameter is not supported in the pandas implementation of z())rr)rZ arg_val_dictrkeyZv1Zv2matchrrr_check_for_default_values/s*  rreturnNonecCs,t||||tt||}t|||dS)a Checks whether the length of the `*args` argument passed into a function has at most `len(compat_args)` arguments and whether or not all of these elements in `args` are set to their default values. Parameters ---------- fname : str The name of the function being passed the `*args` parameter args : tuple The `*args` parameter passed into a function max_fname_arg_count : int The maximum number of arguments that the function `fname` can accept, excluding those in `args`. Used for displaying appropriate error messages. Must be non-negative. compat_args : dict A dictionary of keys and their associated default values. In order to accommodate buggy behaviour in some versions of `numpy`, where a signature displayed keyword arguments but then passed those arguments **positionally** internally when calling downstream implementations, a dict ensures that the original order of the keyword arguments is enforced. Raises ------ TypeError If `args` contains more values than there are `compat_args` ValueError If `args` contains values that do not correspond to those of the default values specified in `compat_args` N)rdictzipr)rrrrkwargsrrr validate_argsUs r"cCs8t|t|}|rt|d}t|d|ddS)z} Checks whether 'kwargs' contains any keys that are not in 'compat_args' and raises a TypeError if there is one. rz'() got an unexpected keyword argument ''N)setlistr)rr!rdiffZbad_argrrr_check_for_invalid_keys~s  r'cCs$|}t|||t|||dS)a Checks whether parameters passed to the **kwargs argument in a function `fname` are valid parameters as specified in `*compat_args` and whether or not they are set to their default values. Parameters ---------- fname : str The name of the function being passed the `**kwargs` parameter kwargs : dict The `**kwargs` parameter passed into `fname` compat_args: dict A dictionary of keys that `kwargs` is allowed to have and their associated default values Raises ------ TypeError if `kwargs` contains keys not in `compat_args` ValueError if `kwargs` contains keys in `compat_args` that do not map to the default values specified in `compat_args` N)copyr'r)rr!rkwdsrrrvalidate_kwargss r*cCsht||t|||tt||}|D]}||vr&t|d|dq||t|||dS)a Checks whether parameters passed to the *args and **kwargs argument in a function `fname` are valid parameters as specified in `*compat_args` and whether or not they are set to their default values. Parameters ---------- fname: str The name of the function being passed the `**kwargs` parameter args: tuple The `*args` parameter passed into a function kwargs: dict The `**kwargs` parameter passed into `fname` max_fname_arg_count: int The minimum number of arguments that the function `fname` requires, excluding those in `args`. Used for displaying appropriate error messages. Must be non-negative. compat_args: dict A dictionary of keys that `kwargs` is allowed to have and their associated default values. Raises ------ TypeError if `args` contains more values than there are `compat_args` OR `kwargs` contains keys not in `compat_args` ValueError if `args` contains values not at the default value (`None`) `kwargs` contains keys in `compat_args` that do not map to the default value as specified in `compat_args` See Also -------- validate_args : Purely args validation. validate_kwargs : Purely kwargs validation. z-() got multiple values for keyword argument 'r#N)rtuplevaluesrr rupdater*)rrr!rrZ args_dictrrrrvalidate_args_and_kwargss( r.TFvalue none_allowedbool int_allowedcCsNt|}|r |p |du}|r|pt|t}|s%td|dt|jd|S)aR Ensure that argument passed in arg_name can be interpreted as boolean. Parameters ---------- value : bool Value to be validated. arg_name : str Name of the argument. To be reflected in the error message. none_allowed : bool, default True Whether to consider None to be a valid boolean. int_allowed : bool, default False Whether to consider integer value to be a valid boolean. Returns ------- value The same value as input. Raises ------ ValueError If the value is not a valid boolean. NzFor argument "z$" expected type bool, received type .)r isinstanceintrtype__name__)r/Zarg_namer0r2Z good_valuerrrvalidate_bool_kwargs r8validate_scalar_dict_valuecCsddlm}|dur|durtd|dur"|dur"||}||fS|durB|durB|r>t|ttfr>tdt|jd||fS|durN|durNtd||fS)a$ Validate the keyword arguments to 'fillna'. This checks that exactly one of 'value' and 'method' is specified. If 'method' is specified, this validates that it's a valid method. Parameters ---------- value, method : object The 'value' and 'method' keyword arguments for 'fillna'. validate_scalar_dict_value : bool, default True Whether to validate that 'value' is a scalar or dict. Specifically, validate that it is not a list or tuple. Returns ------- value, method : object r)clean_fill_methodNz(Must specify a fill 'value' or 'method'.z>"value" parameter must be a scalar or dict, but you passed a ""z)Cannot specify both 'value' and 'method'.) Zpandas.core.missingr:rr4r%r+rr6r7)r/methodr9r:rrrvalidate_fillna_kwargs s"  r=qfloat | Iterable[float] np.ndarraycCslt|}d}|jdkr"d|krdks nt||d|Stdd|Ds4t||d|S)a Validate percentiles (used by describe and quantile). This function checks if the given float or iterable of floats is a valid percentile otherwise raises a ValueError. Parameters ---------- q: float or iterable of floats A single percentile or an iterable of percentiles. Returns ------- ndarray An ndarray of the percentiles if valid. Raises ------ ValueError if percentiles are not in given interval([0, 1]). zApercentiles should all be in the interval [0, 1]. Try {} instead.rr gY@css(|]}d|ko dknVqdS)rr Nr).0qsrrr Ns&z&validate_percentile..)npZasarrayndimrformatall)r>Zq_arrmsgrrrvalidate_percentile1s  rI ascendingcCdSNrrJrrrvalidate_ascendingSrNSequence[BoolishT]list[BoolishT]cCrKrLrrMrrrrNXrObool | int | Sequence[BoolishT]bool | int | list[BoolishT]cs8dddt|tst|dfiSfdd|DS)z8Validate ``ascending`` kwargs for ``sort_index`` method.FT)r0r2rJcsg|] }t|dfiqSrM)r8)rAitemr!rr esz&validate_ascending..)r4rr8rMrrUrrN]s  closed str | Nonetuple[bool, bool]cCsPd}d}|durd}d}||fS|dkrd}||fS|dkr$d}||fStd)a% Check that the `closed` argument is among [None, "left", "right"] Parameters ---------- closed : {None, "left", "right"} Returns ------- left_closed : bool right_closed : bool Raises ------ ValueError : if argument is not among valid values FNTleftrightz/Closed has to be either 'left', 'right' or None)r)rWZ left_closedZ right_closedrrrvalidate_endpointshsr\ inclusivecCs6d}t|trddddd|}|durtd|S)aD Check that the `inclusive` argument is among {"both", "neither", "left", "right"}. Parameters ---------- inclusive : {"both", "neither", "left", "right"} Returns ------- left_right_inclusive : tuple[bool, bool] Raises ------ ValueError : if argument is not among valid values N)TTTF)FT)FF)ZbothrZr[Zneitherz?Inclusive has to be either 'both', 'neither', 'left' or 'right')r4strgetr)r]Zleft_right_inclusiverrrvalidate_inclusives ralocr5lengthcCsZt|std|d||dkr||7}d|kr |ks+ntd|d||S)z Check that we have an integer between -length and length, inclusive. Standardize negative loc to within [0, length]. The exceptions we raise on failure match np.insert. z loc must be an integer between -z and r)r r IndexError)rbrcrrrvalidate_insert_locsrecCs*|tjur|dvrtd|ddSdS)N)Znumpy_nullableZpyarrowzdtype_backend z= is invalid, only 'numpy_nullable' and 'pyarrow' are allowed.)rZ no_defaultr)Z dtype_backendrrrcheck_dtype_backends  rf)rrr^)r/r r0r1r2r1rr )T)r9r1)r>r?rr@)rJr rr )rJrPrrQ)rJrRrrS)rWrXrrY)r]rXrrY)rbr5rcr5rr5)!__doc__ __future__rtypingrrrrnumpyrDZ pandas._libsrZpandas.core.dtypes.commonrr r1r5r r rrr"r'r*r.r8r=rIrNr\rarerfrrrrs6    &) ; * '"    ! "