From 476ce747b407a18f5c4dea618953b0ea9419fd2b Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Sat, 29 Apr 2017 21:40:21 +0100 Subject: [PATCH 1/5] DOC: Show full argument lists for ufuncs --- numpy/core/_internal.py | 45 +++++++++++++++++ numpy/core/src/umath/ufunc_object.c | 77 +++++++---------------------- numpy/core/tests/test_umath.py | 9 +++- 3 files changed, 72 insertions(+), 59 deletions(-) diff --git a/numpy/core/_internal.py b/numpy/core/_internal.py index d8d9168ac852..bd5a5f22bf5b 100644 --- a/numpy/core/_internal.py +++ b/numpy/core/_internal.py @@ -670,3 +670,48 @@ def array_ufunc_errmsg_formatter(ufunc, method, *inputs, **kwargs): return ('operand type(s) do not implement __array_ufunc__' '({!r}, {!r}, {}): {}' .format(ufunc, method, args_string, types_string)) + +def _ufunc_doc_signature_formatter(ufunc): + """ + Builds a signature string which resembles PEP 457 + + This is used to construct the first line of the docstring + """ + + # input arguments are simple + if ufunc.nin == 1: + in_args = 'x' + else: + in_args = ', '.join('x{}'.format(i+1) for i in range(ufunc.nin)) + + # output arguments are both keyword or positional + if ufunc.nout == 0: + out_args = ', /, out=()' + elif ufunc.nout == 1: + out_args = ', /, out=None' + else: + out_args = '[, {positional}], / [, out={default}]'.format( + positional=', '.join( + 'out{}'.format(i+1) for i in range(ufunc.nout)), + default=repr((None,)*ufunc.nout) + ) + + # keyword only args depend on whether this is a gufunc + kwargs = ( + ", casting='same_kind'" + ", order='K'" + ", dtype=None" + ", subok=True" + "[, signature" + ", extobj]" + ) + if ufunc.signature is None: + kwargs = ", where=True" + kwargs + + # join all the parts together + return '{name}({in_args}{out_args}, *{kwargs})'.format( + name=ufunc.__name__, + in_args=in_args, + out_args=out_args, + kwargs=kwargs + ) diff --git a/numpy/core/src/umath/ufunc_object.c b/numpy/core/src/umath/ufunc_object.c index 9b51969cb574..950914b4e9a2 100644 --- a/numpy/core/src/umath/ufunc_object.c +++ b/numpy/core/src/umath/ufunc_object.c @@ -45,6 +45,7 @@ #include "ufunc_object.h" #include "override.h" +#include "npy_import.h" /********** PRINTF DEBUG TRACING **************/ #define NPY_UF_DBG_TRACING 0 @@ -5559,29 +5560,6 @@ static struct PyMethodDef ufunc_methods[] = { *****************************************************************************/ -/* construct the string y1,y2,...,yn */ -static PyObject * -_makeargs(int num, char *ltr, int null_if_none) -{ - PyObject *str; - int i; - - switch (num) { - case 0: - if (null_if_none) { - return NULL; - } - return PyString_FromString(""); - case 1: - return PyString_FromString(ltr); - } - str = PyString_FromFormat("%s1, %s2", ltr, ltr); - for (i = 3; i <= num; ++i) { - PyString_ConcatAndDel(&str, PyString_FromFormat(", %s%d", ltr, i)); - } - return str; -} - static char _typecharfromnum(int num) { PyArray_Descr *descr; @@ -5596,47 +5574,30 @@ _typecharfromnum(int num) { static PyObject * ufunc_get_doc(PyUFuncObject *ufunc) { + static PyObject *_sig_formatter; + PyObject *doc; + + npy_cache_import( + "numpy.core._internal", + "_ufunc_doc_signature_formatter", + &_sig_formatter); + + if (_sig_formatter == NULL) { + return NULL; + } + /* * Put docstring first or FindMethod finds it... could so some * introspection on name and nin + nout to automate the first part * of it the doc string shouldn't need the calling convention - * construct name(x1, x2, ...,[ out1, out2, ...]) __doc__ */ - PyObject *outargs, *inargs, *doc; - outargs = _makeargs(ufunc->nout, "out", 1); - inargs = _makeargs(ufunc->nin, "x", 0); - - if (ufunc->doc == NULL) { - if (outargs == NULL) { - doc = PyUString_FromFormat("%s(%s)\n\n", - ufunc->name, - PyString_AS_STRING(inargs)); - } - else { - doc = PyUString_FromFormat("%s(%s[, %s])\n\n", - ufunc->name, - PyString_AS_STRING(inargs), - PyString_AS_STRING(outargs)); - Py_DECREF(outargs); - } - } - else { - if (outargs == NULL) { - doc = PyUString_FromFormat("%s(%s)\n\n%s", - ufunc->name, - PyString_AS_STRING(inargs), - ufunc->doc); - } - else { - doc = PyUString_FromFormat("%s(%s[, %s])\n\n%s", - ufunc->name, - PyString_AS_STRING(inargs), - PyString_AS_STRING(outargs), - ufunc->doc); - Py_DECREF(outargs); - } + doc = PyObject_CallFunctionObjArgs( + _sig_formatter, (PyObject *)ufunc, NULL); + if (doc == NULL) { + return NULL; } - Py_DECREF(inargs); + PyUString_ConcatAndDel(&doc, + PyUString_FromFormat("\n\n%s", ufunc->doc)); return doc; } diff --git a/numpy/core/tests/test_umath.py b/numpy/core/tests/test_umath.py index 51bf7c9425df..13f29504a866 100644 --- a/numpy/core/tests/test_umath.py +++ b/numpy/core/tests/test_umath.py @@ -2314,13 +2314,20 @@ class TestAttributes(TestCase): def test_attributes(self): add = ncu.add assert_equal(add.__name__, 'add') - assert_(add.__doc__.startswith('add(x1, x2[, out])\n\n')) self.assertTrue(add.ntypes >= 18) # don't fail if types added self.assertTrue('ii->i' in add.types) assert_equal(add.nin, 2) assert_equal(add.nout, 1) assert_equal(add.identity, 0) + def test_doc(self): + # don't bother checking the long list of kwargs, which are likely to + # change + assert_(ncu.add.__doc__.startswith( + "add(x1, x2, /, out=None, *, where=True")) + assert_(ncu.frexp.__doc__.startswith( + "frexp(x[, out1, out2], / [, out=(None, None)], *, where=True")) + class TestSubclass(TestCase): From ba6c1afc1fb5744f95a33c9ac8b3c7c1f1aa7a2d Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Tue, 2 May 2017 00:17:33 +0100 Subject: [PATCH 2/5] DOC: Refer to main ufunc docs for kwargs --- doc/source/reference/ufuncs.rst | 2 + .../core/code_generators/ufunc_docstrings.py | 183 ++++++++++-------- 2 files changed, 102 insertions(+), 83 deletions(-) diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index e82571f6cf58..987bbc4c5a76 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -286,6 +286,8 @@ them by defining certain special methods. For details, see :class:`ufunc` ============== +.. _ufuncs.kwargs: + Optional keyword arguments -------------------------- diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index 11f956b818e6..5e284c3a9bcd 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -10,13 +10,30 @@ """ from __future__ import division, absolute_import, print_function +import textwrap docdict = {} def get(name): return docdict.get(name) +# common parameter text to all ufuncs +_params_text = textwrap.dedent(""" + out : ndarray or tuple of ndarray, optional + Alternate array object(s) in which to put the result; if provided, it + must have a shape that the inputs broadcast to. + where : array_like, optional + Values of True indicate to calculate the ufunc at that position, values + of False indicate to leave the value in the output alone. + **kwargs + For other keyword-only arguments, see the + :ref:`ufunc docs `. +""").strip() + def add_newdoc(place, name, doc): + doc = textwrap.dedent(doc).strip() + doc = doc.replace('$PARAMS', _params_text) + docdict['.'.join((place, name))] = doc @@ -28,6 +45,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -70,6 +88,7 @@ def add_newdoc(place, name, doc): The arrays to be added. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which may be the shape of one or the other). + $PARAMS Returns ------- @@ -105,10 +124,7 @@ def add_newdoc(place, name, doc): x : array_like `x`-coordinate on the unit circle. For real arguments, the domain is [-1, 1]. - - out : ndarray, optional - Array of the same shape as `a`, to store results in. See - `doc.ufuncs` (Section "Output arguments") for more details. + $PARAMS Returns ------- @@ -168,10 +184,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. - out : ndarray, optional - Array of the same shape as `x`, to store results in. - See `doc.ufuncs` (Section "Output arguments") for details. - + $PARAMS Returns ------- @@ -221,10 +234,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like `y`-coordinate on the unit circle. - - out : ndarray, optional - Array of the same shape as `x`, in which to store the results. - See `doc.ufuncs` (Section "Output arguments") for more details. + $PARAMS Returns ------- @@ -278,9 +288,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See `doc.ufuncs`. + $PARAMS Returns ------- @@ -326,7 +334,7 @@ def add_newdoc(place, name, doc): Parameters ---------- x : array_like - Input values. `arctan` is applied to each element of `x`. + $PARAMS Returns ------- @@ -406,6 +414,7 @@ def add_newdoc(place, name, doc): x2 : array_like, real-valued `x`-coordinates. `x2` must be broadcastable to match the shape of `x1` or vice versa. + $PARAMS Returns ------- @@ -473,6 +482,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -525,6 +535,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Only integer and boolean types are handled. + $PARAMS Returns ------- @@ -576,9 +587,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Only integer and boolean types are handled. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -635,6 +644,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Only integer and boolean types are handled. + $PARAMS Returns ------- @@ -683,6 +693,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input data. + $PARAMS Returns ------- @@ -713,6 +724,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input data. + $PARAMS Returns ------- @@ -746,6 +758,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input value. + $PARAMS Returns ------- @@ -772,8 +785,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array in radians. - out : ndarray, optional - Output array of same shape as `x`. + $PARAMS Returns ------- @@ -823,6 +835,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -851,8 +864,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array in radians. - out : ndarray, optional - Output array of same shape as x. + $PARAMS Returns ------- @@ -888,9 +900,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Angle in radians. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -931,11 +941,10 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS h0 : array_like The value of the function at x = 0. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -969,9 +978,7 @@ def add_newdoc(place, name, doc): Dividend array. x2 : array_like Divisor array. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -1040,6 +1047,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Input arrays of the same shape. + $PARAMS Returns ------- @@ -1071,6 +1079,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS Returns ------- @@ -1134,9 +1143,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. - - out : ndarray, optional - Array to insert results into. + $PARAMS Returns ------- @@ -1168,6 +1175,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS Returns ------- @@ -1210,9 +1218,7 @@ def add_newdoc(place, name, doc): x : array_like The array of numbers for which the absolute values are required. If `x` is a scalar, the result `y` will also be a scalar. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -1243,6 +1249,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input data. + $PARAMS Returns ------- @@ -1280,6 +1287,7 @@ def add_newdoc(place, name, doc): Numerator. x2 : array_like Denominator. + $PARAMS Returns ------- @@ -1319,6 +1327,7 @@ def add_newdoc(place, name, doc): Dividend. x2 : array_like Divisor. + $PARAMS Returns ------- @@ -1369,6 +1378,7 @@ def add_newdoc(place, name, doc): Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which may be the shape of one or the other). + $PARAMS Returns ------- @@ -1404,6 +1414,7 @@ def add_newdoc(place, name, doc): Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which may be the shape of one or the other). + $PARAMS Returns ------- @@ -1434,9 +1445,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Leg of the triangle(s). - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -1478,6 +1487,7 @@ def add_newdoc(place, name, doc): ---------- x1 : array_like Only integer and boolean types are handled. + $PARAMS Returns ------- @@ -1549,9 +1559,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See `doc.ufuncs`. + $PARAMS Returns ------- @@ -1617,8 +1625,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values - out : array_like, optional - An array with the same shape as `x` to store the result. + $PARAMS Returns ------- @@ -1677,6 +1684,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -1758,6 +1766,7 @@ def add_newdoc(place, name, doc): Input values. x2 : array_like of integer type Number of zeros to append to `x1`. Has to be non-negative. + $PARAMS Returns ------- @@ -1794,6 +1803,7 @@ def add_newdoc(place, name, doc): Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which may be the shape of one or the other). + $PARAMS Returns ------- @@ -1821,6 +1831,7 @@ def add_newdoc(place, name, doc): Input arrays. If ``x1.shape != x2.shape``, they must be broadcastable to a common shape (which may be the shape of one or the other). + $PARAMS Returns ------- @@ -1850,6 +1861,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input value. + $PARAMS Returns ------- @@ -1896,6 +1908,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS Returns ------- @@ -1943,6 +1956,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS Returns ------- @@ -1996,6 +2010,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Input values. + $PARAMS Returns ------- @@ -2036,8 +2051,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Input values. - out : ndarray, optional - Array to store results in. + $PARAMS Returns ------- @@ -2074,6 +2088,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS Returns ------- @@ -2125,7 +2140,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Input arrays. `x1` and `x2` must be of the same shape. - + $PARAMS Returns ------- @@ -2159,6 +2174,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Logical NOT is applied to the elements of `x`. + $PARAMS Returns ------- @@ -2192,6 +2208,7 @@ def add_newdoc(place, name, doc): x1, x2 : array_like Logical OR is applied to the elements of `x1` and `x2`. They have to be of the same shape. + $PARAMS Returns ------- @@ -2226,6 +2243,7 @@ def add_newdoc(place, name, doc): x1, x2 : array_like Logical XOR is applied to the elements of `x1` and `x2`. They must be broadcastable to the same shape. + $PARAMS Returns ------- @@ -2273,6 +2291,7 @@ def add_newdoc(place, name, doc): x1, x2 : array_like The arrays holding the elements to be compared. They must have the same shape, or shapes that can be broadcast to a single shape. + $PARAMS Returns ------- @@ -2331,6 +2350,7 @@ def add_newdoc(place, name, doc): x1, x2 : array_like The arrays holding the elements to be compared. They must have the same shape, or shapes that can be broadcast to a single shape. + $PARAMS Returns ------- @@ -2389,6 +2409,7 @@ def add_newdoc(place, name, doc): x1, x2 : array_like The arrays holding the elements to be compared. They must have the same shape. + $PARAMS Returns ------- @@ -2446,6 +2467,7 @@ def add_newdoc(place, name, doc): x1, x2 : array_like The arrays holding the elements to be compared. They must have the same shape. + $PARAMS Returns ------- @@ -2498,6 +2520,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -2532,6 +2555,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Input arrays to be multiplied. + $PARAMS Returns ------- @@ -2565,6 +2589,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like or scalar Input array. + $PARAMS Returns ------- @@ -2609,9 +2634,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like Input arrays. - out : ndarray, optional - A placeholder the same shape as `x1` to store the result. - See `doc.ufuncs` (Section "Output arguments") for more details. + $PARAMS Returns ------- @@ -2660,6 +2683,7 @@ def add_newdoc(place, name, doc): The bases. x2 : array_like The exponents. + $PARAMS Returns ------- @@ -2717,6 +2741,7 @@ def add_newdoc(place, name, doc): The bases. x2 : array_like The exponents. + $PARAMS Returns ------- @@ -2763,8 +2788,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array in degrees. - out : ndarray, optional - Output array of same shape as `x`. + $PARAMS Returns ------- @@ -2800,6 +2824,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Angles in degrees. + $PARAMS Returns ------- @@ -2834,6 +2859,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -2873,9 +2899,7 @@ def add_newdoc(place, name, doc): Dividend array. x2 : array_like Divisor array. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -2920,9 +2944,7 @@ def add_newdoc(place, name, doc): Dividend array. x2 : array_like Divisor array. - out : tuple of ndarray, optional - Arrays into which the output is placed. Their types are preserved and - must be of the right shape to hold the output. + $PARAMS Returns ------- @@ -2959,6 +2981,7 @@ def add_newdoc(place, name, doc): Input values. x2 : array_like, int Number of bits to remove at the right of `x1`. + $PARAMS Returns ------- @@ -2993,6 +3016,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. + $PARAMS Returns ------- @@ -3027,6 +3051,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input values. + $PARAMS Returns ------- @@ -3058,9 +3083,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like The input value(s). - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See `doc.ufuncs`. + $PARAMS Returns ------- @@ -3090,9 +3113,7 @@ def add_newdoc(place, name, doc): Values to change the sign of. x2 : array_like The sign of `x2` is copied to `x1`. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See doc.ufuncs. + $PARAMS Returns ------- @@ -3125,9 +3146,7 @@ def add_newdoc(place, name, doc): Values to find the next representable value of. x2 : array_like The direction where to look for the next representable value of `x1`. - out : ndarray, optional - Array into which the output is placed. Its type is preserved and it - must be of the right shape to hold the output. See `doc.ufuncs`. + $PARAMS Returns ------- @@ -3152,6 +3171,7 @@ def add_newdoc(place, name, doc): ---------- x1 : array_like Values to find the spacing of. + $PARAMS Returns ------- @@ -3182,6 +3202,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Angle, in radians (:math:`2 \\pi` rad equals 360 degrees). + $PARAMS Returns ------- @@ -3241,8 +3262,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. - out : ndarray, optional - Output array of same shape as `x`. + $PARAMS Returns ------- @@ -3295,9 +3315,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like The values whose square-roots are required. - out : ndarray, optional - Alternate array object in which to put the result; if provided, it - must have the same shape as `x` + $PARAMS Returns ------- @@ -3344,9 +3362,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like The values whose cube-roots are required. - out : ndarray, optional - Alternate array object in which to put the result; if provided, it - must have the same shape as `x` + $PARAMS Returns ------- @@ -3371,6 +3387,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input data. + $PARAMS Returns ------- @@ -3399,6 +3416,7 @@ def add_newdoc(place, name, doc): ---------- x1, x2 : array_like The arrays to be subtracted from each other. + $PARAMS Returns ------- @@ -3434,8 +3452,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. - out : ndarray, optional - Output array of same shape as `x`. + $PARAMS Returns ------- @@ -3487,8 +3504,7 @@ def add_newdoc(place, name, doc): ---------- x : array_like Input array. - out : ndarray, optional - Output array of same shape as `x`. + $PARAMS Returns ------- @@ -3547,6 +3563,7 @@ def add_newdoc(place, name, doc): Dividend array. x2 : array_like Divisor array. + $PARAMS Returns ------- @@ -3599,6 +3616,7 @@ def add_newdoc(place, name, doc): Output array for the mantissa. Must have the same shape as `x`. out2 : ndarray, optional Output array for the exponent. Must have the same shape as `x`. + $PARAMS Returns ------- @@ -3641,8 +3659,7 @@ def add_newdoc(place, name, doc): Array of multipliers. x2 : array_like, int Array of twos exponents. - out : ndarray, optional - Output array for the result. + $PARAMS Returns ------- From bcc77f9229707714db43e8b69c5dacaa494aa184 Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Tue, 2 May 2017 00:27:11 +0100 Subject: [PATCH 3/5] DOC: Remove explanation of exception due to out This was covered by very few ufuncs, and is probably better to leave out. --- .../core/code_generators/ufunc_docstrings.py | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index 5e284c3a9bcd..e0d65d2a2a49 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -792,11 +792,6 @@ def add_newdoc(place, name, doc): y : ndarray The corresponding cosine values. - Raises - ------ - ValueError: invalid return array shape - if `out` is provided and `out.shape` != `x.shape` (See Examples) - Notes ----- If `out` is provided, the function writes the result into it, @@ -3269,11 +3264,6 @@ def add_newdoc(place, name, doc): y : ndarray The corresponding hyperbolic sine values. - Raises - ------ - ValueError: invalid return array shape - if `out` is provided and `out.shape` != `x.shape` (See Examples) - Notes ----- If `out` is provided, the function writes the result into it, @@ -3459,11 +3449,6 @@ def add_newdoc(place, name, doc): y : ndarray The corresponding tangent values. - Raises - ------ - ValueError: invalid return array shape - if `out` is provided and `out.shape` != `x.shape` (See Examples) - Notes ----- If `out` is provided, the function writes the result into it, @@ -3511,11 +3496,6 @@ def add_newdoc(place, name, doc): y : ndarray The corresponding hyperbolic tangent values. - Raises - ------ - ValueError: invalid return array shape - if `out` is provided and `out.shape` != `x.shape` (See Examples) - Notes ----- If `out` is provided, the function writes the result into it, From 0025c86b3a6e8e1b0345ce714af91c527e7167a3 Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Tue, 2 May 2017 10:59:22 +0100 Subject: [PATCH 4/5] DOC: Simplify the output of help(ufunc) The distinction between unary and binary is not too helpful, and ignores the fact that trinary ufuncs can exist. Also add a link to the ufunc docs --- numpy/add_newdocs.py | 58 ++++++++++++++++---------------------------- 1 file changed, 21 insertions(+), 37 deletions(-) diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index df79ae13634e..449196efbff9 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -5421,40 +5421,19 @@ def luf(lamdaexpr, *args, **kwargs): """ Functions that operate element by element on whole arrays. - To see the documentation for a specific ufunc, use np.info(). For - example, np.info(np.sin). Because ufuncs are written in C + To see the documentation for a specific ufunc, use `info`. For + example, ``np.info(np.sin)``. Because ufuncs are written in C (for speed) and linked into Python with NumPy's ufunc facility, Python's help() function finds this page whenever help() is called on a ufunc. - A detailed explanation of ufuncs can be found in the "ufuncs.rst" - file in the NumPy reference guide. + A detailed explanation of ufuncs can be found in the docs for :ref:`ufuncs`. - Unary ufuncs: - ============= + Calling ufuncs: + =============== - op(X, out=None) - Apply op to X elementwise - - Parameters - ---------- - X : array_like - Input array. - out : array_like - An array to store the output. Must be the same shape as `X`. - - Returns - ------- - r : array_like - `r` will have the same shape as `X`; if out is provided, `r` - will be equal to out. - - Binary ufuncs: - ============== - - op(X, Y, out=None) - Apply `op` to `X` and `Y` elementwise. May "broadcast" to make - the shapes of `X` and `Y` congruent. + op(*x[, out], where=True, **kwargs) + Apply `op` to the arguments `*x` elementwise, broadcasting the arguments. The broadcasting rules are: @@ -5463,18 +5442,23 @@ def luf(lamdaexpr, *args, **kwargs): Parameters ---------- - X : array_like - First input array. - Y : array_like - Second input array. - out : array_like - An array to store the output. Must be the same shape as the - output would have. + *x : array_like + Input arrays. + out : ndarray or tuple of ndarray, optional + Alternate array object(s) in which to put the result; if provided, it + must have a shape that the inputs broadcast to. + where : array_like, optional + Values of True indicate to calculate the ufunc at that position, values + of False indicate to leave the value in the output alone. + **kwargs + For other keyword-only arguments, see the :ref:`ufunc docs `. Returns ------- - r : array_like - The return value; if out is provided, `r` will be equal to out. + r : ndarray or tuple of ndarray + `r` will have the shape that the arrays in `x` broadcast to; if `out` is + provided, `r` will be equal to `out`. If the function has more than one + output, then the result will be a tuple of arrays. """) From 2e3202649692815e973f0e72820d25d5e536910d Mon Sep 17 00:00:00 2001 From: Eric Wieser Date: Mon, 8 May 2017 00:09:46 +0100 Subject: [PATCH 5/5] DOC: Correct parameter names for spacing and invert --- numpy/core/code_generators/ufunc_docstrings.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index e0d65d2a2a49..7beda59f2cd2 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -1480,7 +1480,7 @@ def add_newdoc(place, name, doc): Parameters ---------- - x1 : array_like + x : array_like Only integer and boolean types are handled. $PARAMS @@ -3164,7 +3164,7 @@ def add_newdoc(place, name, doc): Parameters ---------- - x1 : array_like + x : array_like Values to find the spacing of. $PARAMS