FIX: Transition scheme for safer in-place ufunc operations

In numpy 1.6 and earlier, if you do
  np.add(int_arr, float_arr, out=int_arr)
or
  int_arr += float_arr
then the result will be silently truncated to integer values. This
often produces bugs, because it's easy to accidentally end up with an
integer array and not realize it.

Therefore, there seems to be consensus that we should switch to using
same_kind casting by default for in-place ufunc operations. However,
just switching this (as was done initially during the 1.7 development
cycle) breaks a lot of code, which is rude and violates our
deprecation policy.

This commit instead adds a special temporary casting rule which acts
like "unsafe", but also checks whether each operation would be allowed
under "same_kind" rules and issues a DeprecationWarning if not.

It also moves NPY_DEFAULT_ASSIGN_CASTING into the formal API instead
of leaving it as a #define. This way we can change it later, and any
code which references it and is compiled against this version of numpy
will automatically switch to whatever we change it too. This avoids
the situation where we want to remove the temporary magic value we're
using to create DeprecationWarnings now, but can't because it would be
an ABI break.

2 files changed, 14 insertions, 4 deletions

diff --git a/doc/release/1.7.0-notes.rst b/doc/release/1.7.0-notes.rst
index f8f54219c..c38f6eff1 100644
--- a/doc/release/1.7.0-notes.rst
+++ b/doc/release/1.7.0-notes.rst
@@ -33,10 +33,14 @@ np.diagonal, numpy 1.7 produces a FutureWarning if it detects
 that you may be attemping to write to such an array. See the documentation
 for array indexing for details.
 
-The default casting rule for UFunc out= parameters has been changed from
-'unsafe' to 'same_kind'.  Most usages which violate the 'same_kind'
-rule are likely bugs, so this change may expose previously undetected
-errors in projects that depend on NumPy.
+In a future version of numpy, the default casting rule for UFunc out=
+parameters will be changed from 'unsafe' to 'same_kind'. (This also
+applies to in-place operations like a += b, which is equivalent to
+np.add(a, b, out=a).) Most usages which violate the 'same_kind' rule
+are likely bugs, so this change may expose previously undetected
+errors in projects that depend on NumPy. In this version of numpy,
+such usages will continue to succeed, but will raise a
+DeprecationWarning.
 
 Full-array boolean indexing has been optimized to use a different,
 optimized code path.   This code path should produce the same results,
diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst
index 295d52ef4..afcb1302b 100644
--- a/doc/source/reference/ufuncs.rst
+++ b/doc/source/reference/ufuncs.rst
@@ -309,6 +309,12 @@ advanced usage and will not typically be used.
     'equiv', 'safe', 'same_kind', or 'unsafe'. See :func:`can_cast` for
     explanations of the parameter values.
 
+    In a future version of numpy, this argument will default to
+    'same_kind'. As part of this transition, starting in version 1.7,
+    ufuncs will produce a DeprecationWarning for calls which are
+    allowed under the 'unsafe' rules, but not under the 'same_kind'
+    rules.
+
 *order*
 
     .. versionadded:: 1.6