Merge pull request #8955 from eric-wieser/obj-identity

ENH: Allow ufunc.identity to be any python object

2 files changed, 46 insertions, 3 deletions

diff --git a/doc/release/1.16.0-notes.rst b/doc/release/1.16.0-notes.rst
index 3e00e4410..7f2a843eb 100644
--- a/doc/release/1.16.0-notes.rst
+++ b/doc/release/1.16.0-notes.rst
@@ -109,8 +109,13 @@ for unraveling. ``dims`` remains supported, but is now deprecated.
 C API changes
 =============
 
-The :c:data:`NPY_API_VERSION` was incremented to 0x0000D since
-``core_dim_flags`` and ``core_dim_sizes`` were added to :c:type:`PyUFuncObject`.
+The :c:data:`NPY_API_VERSION` was incremented to 0x0000D, due to the addition
+of:
+
+* :c:member:`PyUFuncObject.core_dim_flags`
+* :c:member:`PyUFuncObject.core_dim_sizes`
+* :c:member:`PyUFuncObject.identity_value`
+* :c:function:`PyUFunc_FromFuncAndDataAndSignatureAndIdentity`
 
 New Features
 ============
@@ -287,6 +292,25 @@ and other path-like objects in addition to a file object. Furthermore, the
 ``np.load`` function now also supports path-like objects when
 using memory mapping (``mmap_mode`` keyword argument).
 
+Better behaviour of ufunc identities during reductions
+------------------------------------------------------
+Universal functions have an ``.identity`` which is used when ``.reduce`` is
+called on an empty axis.
+
+As of this release, the logical binary ufuncs, `logical_and`, `logical_or`,
+and `logical_xor`, now have ``identity``s of type `bool`, where previously they
+were of type `int`. This restores the 1.14 behavior of getting ``bool``s when
+reducing empty object arrays with these ufuncs, while also keeping the 1.15
+behavior of getting ``int``s when reducing empty object arrays with arithmetic
+ufuncs like ``add`` and ``multiply``.
+
+Additionally, `logaddexp` now has an identity of ``-inf``, allowing it to be
+called on empty sequences, where previously it could not be.
+
+This is possible thanks to the new
+:c:function:`PyUFunc_FromFuncAndDataAndSignatureAndIdentity`, which allows
+arbitrary values to be used as identities now.
+
 
 Changes
 =======
diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst
index 07c7b0c80..0499ccf5b 100644
--- a/doc/source/reference/c-api.ufunc.rst
+++ b/doc/source/reference/c-api.ufunc.rst
@@ -169,8 +169,12 @@ Functions
     :param identity:
 
         Either :c:data:`PyUFunc_One`, :c:data:`PyUFunc_Zero`,
-        :c:data:`PyUFunc_None`. This specifies what should be returned when
+        :c:data:`PyUFunc_MinusOne`, or :c:data:`PyUFunc_None`.
+        This specifies what should be returned when
         an empty array is passed to the reduce method of the ufunc.
+        The special value :c:data:`PyUFunc_IdentityValue` may only be used with
+        the :c:func:`PyUFunc_FromFuncAndDataAndSignatureAndIdentity` method, to
+        allow an arbitrary python object to be used as the identity.
 
     :param name:
         The name for the ufunc as a ``NULL`` terminated string.  Specifying
@@ -206,6 +210,21 @@ Functions
         to calling PyUFunc_FromFuncAndData. A copy of the string is made,
         so the passed in buffer can be freed.
 
+.. c:function:: PyObject* PyUFunc_FromFuncAndDataAndSignatureAndIdentity(
+        PyUFuncGenericFunction *func, void **data, char *types, int ntypes, \
+        int nin, int nout, int identity, char *name, char *doc, int unused, char *signature,
+        PyObject *identity_value)
+
+   This function is very similar to `PyUFunc_FromFuncAndDataAndSignature` above,
+   but has an extra *identity_value* argument, to define an arbitrary identity
+   for the ufunc when ``identity`` is passed as ``PyUFunc_IdentityValue``.
+
+   :param identity_value:
+        The identity for the new gufunc. Must be passed as ``NULL`` unless the
+        ``identity`` argument is ``PyUFunc_IdentityValue``. Setting it to NULL
+        is equivalent to calling PyUFunc_FromFuncAndDataAndSignature.
+
+
 .. c:function:: int PyUFunc_RegisterLoopForType( \
         PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, \
         int* arg_types, void* data)