Skip to content

Commit aa92172

Browse files
CLN: re-wrap docstrings in pandas\compat\numpy\function.py (#36979)
1 parent 0dcef9b commit aa92172

File tree

1 file changed

+45
-54
lines changed

1 file changed

+45
-54
lines changed

pandas/compat/numpy/function.py

+45-54
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,18 @@
11
"""
2-
For compatibility with numpy libraries, pandas functions or
3-
methods have to accept '*args' and '**kwargs' parameters to
4-
accommodate numpy arguments that are not actually used or
5-
respected in the pandas implementation.
6-
7-
To ensure that users do not abuse these parameters, validation
8-
is performed in 'validators.py' to make sure that any extra
9-
parameters passed correspond ONLY to those in the numpy signature.
10-
Part of that validation includes whether or not the user attempted
11-
to pass in non-default values for these extraneous parameters. As we
12-
want to discourage users from relying on these parameters when calling
13-
the pandas implementation, we want them only to pass in the default values
14-
for these parameters.
15-
16-
This module provides a set of commonly used default arguments for functions
17-
and methods that are spread throughout the codebase. This module will make it
2+
For compatibility with numpy libraries, pandas functions or methods have to
3+
accept '*args' and '**kwargs' parameters to accommodate numpy arguments that
4+
are not actually used or respected in the pandas implementation.
5+
6+
To ensure that users do not abuse these parameters, validation is performed in
7+
'validators.py' to make sure that any extra parameters passed correspond ONLY
8+
to those in the numpy signature. Part of that validation includes whether or
9+
not the user attempted to pass in non-default values for these extraneous
10+
parameters. As we want to discourage users from relying on these parameters
11+
when calling the pandas implementation, we want them only to pass in the
12+
default values for these parameters.
13+
14+
This module provides a set of commonly used default arguments for functions and
15+
methods that are spread throughout the codebase. This module will make it
1816
easier to adjust to future upstream changes in the analogous numpy signatures.
1917
"""
2018
from distutils.version import LooseVersion
@@ -92,11 +90,10 @@ def process_skipna(skipna, args):
9290

9391
def validate_argmin_with_skipna(skipna, args, kwargs):
9492
"""
95-
If 'Series.argmin' is called via the 'numpy' library,
96-
the third parameter in its signature is 'out', which
97-
takes either an ndarray or 'None', so check if the
98-
'skipna' parameter is either an instance of ndarray or
99-
is None, since 'skipna' itself should be a boolean
93+
If 'Series.argmin' is called via the 'numpy' library, the third parameter
94+
in its signature is 'out', which takes either an ndarray or 'None', so
95+
check if the 'skipna' parameter is either an instance of ndarray or is
96+
None, since 'skipna' itself should be a boolean
10097
"""
10198
skipna, args = process_skipna(skipna, args)
10299
validate_argmin(args, kwargs)
@@ -105,11 +102,10 @@ def validate_argmin_with_skipna(skipna, args, kwargs):
105102

106103
def validate_argmax_with_skipna(skipna, args, kwargs):
107104
"""
108-
If 'Series.argmax' is called via the 'numpy' library,
109-
the third parameter in its signature is 'out', which
110-
takes either an ndarray or 'None', so check if the
111-
'skipna' parameter is either an instance of ndarray or
112-
is None, since 'skipna' itself should be a boolean
105+
If 'Series.argmax' is called via the 'numpy' library, the third parameter
106+
in its signature is 'out', which takes either an ndarray or 'None', so
107+
check if the 'skipna' parameter is either an instance of ndarray or is
108+
None, since 'skipna' itself should be a boolean
113109
"""
114110
skipna, args = process_skipna(skipna, args)
115111
validate_argmax(args, kwargs)
@@ -130,8 +126,8 @@ def validate_argmax_with_skipna(skipna, args, kwargs):
130126
ARGSORT_DEFAULTS, fname="argsort", max_fname_arg_count=0, method="both"
131127
)
132128

133-
# two different signatures of argsort, this second validation
134-
# for when the `kind` param is supported
129+
# two different signatures of argsort, this second validation for when the
130+
# `kind` param is supported
135131
ARGSORT_DEFAULTS_KIND: Dict[str, Optional[int]] = {}
136132
ARGSORT_DEFAULTS_KIND["axis"] = -1
137133
ARGSORT_DEFAULTS_KIND["order"] = None
@@ -142,11 +138,10 @@ def validate_argmax_with_skipna(skipna, args, kwargs):
142138

143139
def validate_argsort_with_ascending(ascending, args, kwargs):
144140
"""
145-
If 'Categorical.argsort' is called via the 'numpy' library, the
146-
first parameter in its signature is 'axis', which takes either
147-
an integer or 'None', so check if the 'ascending' parameter has
148-
either integer type or is None, since 'ascending' itself should
149-
be a boolean
141+
If 'Categorical.argsort' is called via the 'numpy' library, the first
142+
parameter in its signature is 'axis', which takes either an integer or
143+
'None', so check if the 'ascending' parameter has either integer type or is
144+
None, since 'ascending' itself should be a boolean
150145
"""
151146
if is_integer(ascending) or ascending is None:
152147
args = (ascending,) + args
@@ -164,10 +159,10 @@ def validate_argsort_with_ascending(ascending, args, kwargs):
164159

165160
def validate_clip_with_axis(axis, args, kwargs):
166161
"""
167-
If 'NDFrame.clip' is called via the numpy library, the third
168-
parameter in its signature is 'out', which can takes an ndarray,
169-
so check if the 'axis' parameter is an instance of ndarray, since
170-
'axis' itself should either be an integer or None
162+
If 'NDFrame.clip' is called via the numpy library, the third parameter in
163+
its signature is 'out', which can takes an ndarray, so check if the 'axis'
164+
parameter is an instance of ndarray, since 'axis' itself should either be
165+
an integer or None
171166
"""
172167
if isinstance(axis, ndarray):
173168
args = (axis,) + args
@@ -190,10 +185,9 @@ def validate_clip_with_axis(axis, args, kwargs):
190185

191186
def validate_cum_func_with_skipna(skipna, args, kwargs, name):
192187
"""
193-
If this function is called via the 'numpy' library, the third
194-
parameter in its signature is 'dtype', which takes either a
195-
'numpy' dtype or 'None', so check if the 'skipna' parameter is
196-
a boolean or not
188+
If this function is called via the 'numpy' library, the third parameter in
189+
its signature is 'dtype', which takes either a 'numpy' dtype or 'None', so
190+
check if the 'skipna' parameter is a boolean or not
197191
"""
198192
if not is_bool(skipna):
199193
args = (skipna,) + args
@@ -294,10 +288,9 @@ def validate_cum_func_with_skipna(skipna, args, kwargs, name):
294288

295289
def validate_take_with_convert(convert, args, kwargs):
296290
"""
297-
If this function is called via the 'numpy' library, the third
298-
parameter in its signature is 'axis', which takes either an
299-
ndarray or 'None', so check if the 'convert' parameter is either
300-
an instance of ndarray or is None
291+
If this function is called via the 'numpy' library, the third parameter in
292+
its signature is 'axis', which takes either an ndarray or 'None', so check
293+
if the 'convert' parameter is either an instance of ndarray or is None
301294
"""
302295
if isinstance(convert, ndarray) or convert is None:
303296
args = (convert,) + args
@@ -360,10 +353,9 @@ def validate_expanding_func(name, args, kwargs) -> None:
360353

361354
def validate_groupby_func(name, args, kwargs, allowed=None) -> None:
362355
"""
363-
'args' and 'kwargs' should be empty, except for allowed
364-
kwargs because all of
365-
their necessary parameters are explicitly listed in
366-
the function signature
356+
'args' and 'kwargs' should be empty, except for allowed kwargs because all
357+
of their necessary parameters are explicitly listed in the function
358+
signature
367359
"""
368360
if allowed is None:
369361
allowed = []
@@ -382,9 +374,8 @@ def validate_groupby_func(name, args, kwargs, allowed=None) -> None:
382374

383375
def validate_resampler_func(method: str, args, kwargs) -> None:
384376
"""
385-
'args' and 'kwargs' should be empty because all of
386-
their necessary parameters are explicitly listed in
387-
the function signature
377+
'args' and 'kwargs' should be empty because all of their necessary
378+
parameters are explicitly listed in the function signature
388379
"""
389380
if len(args) + len(kwargs) > 0:
390381
if method in RESAMPLER_NUMPY_OPS:
@@ -398,8 +389,8 @@ def validate_resampler_func(method: str, args, kwargs) -> None:
398389

399390
def validate_minmax_axis(axis: Optional[int]) -> None:
400391
"""
401-
Ensure that the axis argument passed to min, max, argmin, or argmax is
402-
zero or None, as otherwise it will be incorrectly ignored.
392+
Ensure that the axis argument passed to min, max, argmin, or argmax is zero
393+
or None, as otherwise it will be incorrectly ignored.
403394
404395
Parameters
405396
----------

0 commit comments

Comments
 (0)