diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/arrays.classes.rst | 31 | ||||
| -rw-r--r-- | doc/source/reference/ufuncs.rst | 21 |
2 files changed, 36 insertions, 16 deletions
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 671c95bbf..f9abfbafa 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -47,14 +47,29 @@ customize: update meta-information from the "parent." Subclasses inherit a default implementation of this method that does nothing. -.. function:: __array_wrap__(array) - - This method should return an instance of the subclass from the - :class:`ndarray` object passed in. For example, this is called - after every :ref:`ufunc <ufuncs.output-type>` for the object with - the highest array priority. The ufunc-computed array object is - passed in and whatever is returned is passed to the - user. Subclasses inherit a default implementation of this method. +.. function:: __array_prepare__(array, context=None) + + At the beginning of every :ref:`ufunc <ufuncs.output-type>`, this + method is called on the input object with the highest array + priority, or the output object if one was specified. The output + array is passed in and whatever is returned is passed to the ufunc. + Subclasses inherit a default implementation of this method which + simply returns the output array unmodified. Subclasses may opt to + use this method to transform the output array into an instance of + the subclass and update metadata before returning the array to the + ufunc for computation. + +.. function:: __array_wrap__(array, context=None) + + At the end of every :ref:`ufunc <ufuncs.output-type>`, this method + is called on the input object with the highest array priority, or + the output object if one was specified. The ufunc-computed array + is passed in and whatever is returned is passed to the user. + Subclasses inherit a default implementation of this method, which + transforms the array into a new instance of the object's class. Subclasses + may opt to use this method to transform the output array into an + instance of the subclass and update metadata before returning the + array to the user. .. data:: __array_priority__ diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index 09b13dc89..8096e1497 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -102,19 +102,24 @@ Output type determination The output of the ufunc (and its methods) is not necessarily an :class:`ndarray`, if all input arguments are not :class:`ndarrays <ndarray>`. -All output arrays will be passed to the :obj:`__array_wrap__` -method of the input (besides :class:`ndarrays <ndarray>`, and scalars) -that defines it **and** has the highest :obj:`__array_priority__` of -any other input to the universal function. The default -:obj:`__array_priority__` of the ndarray is 0.0, and the default -:obj:`__array_priority__` of a subtype is 1.0. Matrices have -:obj:`__array_priority__` equal to 10.0. +All output arrays will be passed to the :obj:`__array_prepare__` and +:obj:`__array_wrap__` methods of the input (besides +:class:`ndarrays <ndarray>`, and scalars) that defines it **and** has +the highest :obj:`__array_priority__` of any other input to the +universal function. The default :obj:`__array_priority__` of the +ndarray is 0.0, and the default :obj:`__array_priority__` of a subtype +is 1.0. Matrices have :obj:`__array_priority__` equal to 10.0. The ufuncs can also all take output arguments. The output will be cast if necessary to the provided output array. If a class with an :obj:`__array__` method is used for the output, results will be written to the object returned by :obj:`__array__`. Then, if the class -also has an :obj:`__array_wrap__` method, the returned +also has an :obj:`__array_prepare__` method, it is called so metadata +may be determined based on the context of the ufunc (the context +consisting of the ufunc itself, the arguments passed to the ufunc, and +the ufunc domain.) The array object returned by +:obj:`__array_prepare__` is passed to the ufunc for computation. +Finally, if the class also has an :obj:`__array_wrap__` method, the returned :class:`ndarray` result will be passed to that method just before passing control back to the caller. |