From 8951fae791726d61d5138f6f9b8ff964a8a6e164 Mon Sep 17 00:00:00 2001 From: Simon Hawkins Date: Thu, 8 Oct 2020 12:30:16 +0100 Subject: [PATCH] CLN: re-wrap docstrings in pandas\compat\numpy\function.py --- pandas/compat/numpy/function.py | 99 +++++++++++++++------------------ 1 file changed, 45 insertions(+), 54 deletions(-) diff --git a/pandas/compat/numpy/function.py b/pandas/compat/numpy/function.py index 938f57f504b04..c074b06042e26 100644 --- a/pandas/compat/numpy/function.py +++ b/pandas/compat/numpy/function.py @@ -1,20 +1,18 @@ """ -For compatibility with numpy libraries, pandas functions or -methods have to accept '*args' and '**kwargs' parameters to -accommodate numpy arguments that are not actually used or -respected in the pandas implementation. - -To ensure that users do not abuse these parameters, validation -is performed in 'validators.py' to make sure that any extra -parameters passed correspond ONLY to those in the numpy signature. -Part of that validation includes whether or not the user attempted -to pass in non-default values for these extraneous parameters. As we -want to discourage users from relying on these parameters when calling -the pandas implementation, we want them only to pass in the default values -for these parameters. - -This module provides a set of commonly used default arguments for functions -and methods that are spread throughout the codebase. This module will make it +For compatibility with numpy libraries, pandas functions or methods have to +accept '*args' and '**kwargs' parameters to accommodate numpy arguments that +are not actually used or respected in the pandas implementation. + +To ensure that users do not abuse these parameters, validation is performed in +'validators.py' to make sure that any extra parameters passed correspond ONLY +to those in the numpy signature. Part of that validation includes whether or +not the user attempted to pass in non-default values for these extraneous +parameters. As we want to discourage users from relying on these parameters +when calling the pandas implementation, we want them only to pass in the +default values for these parameters. + +This module provides a set of commonly used default arguments for functions and +methods that are spread throughout the codebase. This module will make it easier to adjust to future upstream changes in the analogous numpy signatures. """ from distutils.version import LooseVersion @@ -92,11 +90,10 @@ def process_skipna(skipna, args): def validate_argmin_with_skipna(skipna, args, kwargs): """ - If 'Series.argmin' is called via the 'numpy' library, - the third parameter in its signature is 'out', which - takes either an ndarray or 'None', so check if the - 'skipna' parameter is either an instance of ndarray or - is None, since 'skipna' itself should be a boolean + If 'Series.argmin' is called via the 'numpy' library, the third parameter + in its signature is 'out', which takes either an ndarray or 'None', so + check if the 'skipna' parameter is either an instance of ndarray or is + None, since 'skipna' itself should be a boolean """ skipna, args = process_skipna(skipna, args) validate_argmin(args, kwargs) @@ -105,11 +102,10 @@ def validate_argmin_with_skipna(skipna, args, kwargs): def validate_argmax_with_skipna(skipna, args, kwargs): """ - If 'Series.argmax' is called via the 'numpy' library, - the third parameter in its signature is 'out', which - takes either an ndarray or 'None', so check if the - 'skipna' parameter is either an instance of ndarray or - is None, since 'skipna' itself should be a boolean + If 'Series.argmax' is called via the 'numpy' library, the third parameter + in its signature is 'out', which takes either an ndarray or 'None', so + check if the 'skipna' parameter is either an instance of ndarray or is + None, since 'skipna' itself should be a boolean """ skipna, args = process_skipna(skipna, args) validate_argmax(args, kwargs) @@ -130,8 +126,8 @@ def validate_argmax_with_skipna(skipna, args, kwargs): ARGSORT_DEFAULTS, fname="argsort", max_fname_arg_count=0, method="both" ) -# two different signatures of argsort, this second validation -# for when the `kind` param is supported +# two different signatures of argsort, this second validation for when the +# `kind` param is supported ARGSORT_DEFAULTS_KIND: Dict[str, Optional[int]] = {} ARGSORT_DEFAULTS_KIND["axis"] = -1 ARGSORT_DEFAULTS_KIND["order"] = None @@ -142,11 +138,10 @@ def validate_argmax_with_skipna(skipna, args, kwargs): def validate_argsort_with_ascending(ascending, args, kwargs): """ - If 'Categorical.argsort' is called via the 'numpy' library, the - first parameter in its signature is 'axis', which takes either - an integer or 'None', so check if the 'ascending' parameter has - either integer type or is None, since 'ascending' itself should - be a boolean + If 'Categorical.argsort' is called via the 'numpy' library, the first + parameter in its signature is 'axis', which takes either an integer or + 'None', so check if the 'ascending' parameter has either integer type or is + None, since 'ascending' itself should be a boolean """ if is_integer(ascending) or ascending is None: args = (ascending,) + args @@ -164,10 +159,10 @@ def validate_argsort_with_ascending(ascending, args, kwargs): def validate_clip_with_axis(axis, args, kwargs): """ - If 'NDFrame.clip' is called via the numpy library, the third - parameter in its signature is 'out', which can takes an ndarray, - so check if the 'axis' parameter is an instance of ndarray, since - 'axis' itself should either be an integer or None + If 'NDFrame.clip' is called via the numpy library, the third parameter in + its signature is 'out', which can takes an ndarray, so check if the 'axis' + parameter is an instance of ndarray, since 'axis' itself should either be + an integer or None """ if isinstance(axis, ndarray): args = (axis,) + args @@ -190,10 +185,9 @@ def validate_clip_with_axis(axis, args, kwargs): def validate_cum_func_with_skipna(skipna, args, kwargs, name): """ - If this function is called via the 'numpy' library, the third - parameter in its signature is 'dtype', which takes either a - 'numpy' dtype or 'None', so check if the 'skipna' parameter is - a boolean or not + If this function is called via the 'numpy' library, the third parameter in + its signature is 'dtype', which takes either a 'numpy' dtype or 'None', so + check if the 'skipna' parameter is a boolean or not """ if not is_bool(skipna): args = (skipna,) + args @@ -294,10 +288,9 @@ def validate_cum_func_with_skipna(skipna, args, kwargs, name): def validate_take_with_convert(convert, args, kwargs): """ - If this function is called via the 'numpy' library, the third - parameter in its signature is 'axis', which takes either an - ndarray or 'None', so check if the 'convert' parameter is either - an instance of ndarray or is None + If this function is called via the 'numpy' library, the third parameter in + its signature is 'axis', which takes either an ndarray or 'None', so check + if the 'convert' parameter is either an instance of ndarray or is None """ if isinstance(convert, ndarray) or convert is None: args = (convert,) + args @@ -360,10 +353,9 @@ def validate_expanding_func(name, args, kwargs) -> None: def validate_groupby_func(name, args, kwargs, allowed=None) -> None: """ - 'args' and 'kwargs' should be empty, except for allowed - kwargs because all of - their necessary parameters are explicitly listed in - the function signature + 'args' and 'kwargs' should be empty, except for allowed kwargs because all + of their necessary parameters are explicitly listed in the function + signature """ if allowed is None: allowed = [] @@ -382,9 +374,8 @@ def validate_groupby_func(name, args, kwargs, allowed=None) -> None: def validate_resampler_func(method: str, args, kwargs) -> None: """ - 'args' and 'kwargs' should be empty because all of - their necessary parameters are explicitly listed in - the function signature + 'args' and 'kwargs' should be empty because all of their necessary + parameters are explicitly listed in the function signature """ if len(args) + len(kwargs) > 0: if method in RESAMPLER_NUMPY_OPS: @@ -398,8 +389,8 @@ def validate_resampler_func(method: str, args, kwargs) -> None: def validate_minmax_axis(axis: Optional[int]) -> None: """ - Ensure that the axis argument passed to min, max, argmin, or argmax is - zero or None, as otherwise it will be incorrectly ignored. + Ensure that the axis argument passed to min, max, argmin, or argmax is zero + or None, as otherwise it will be incorrectly ignored. Parameters ----------