Document the PyArray_Diagonal transition scheme.

3 files changed, 61 insertions, 32 deletions

diff --git a/doc/release/2.0.0-notes.rst b/doc/release/2.0.0-notes.rst
index 978d9139e..557305998 100644
--- a/doc/release/2.0.0-notes.rst
+++ b/doc/release/2.0.0-notes.rst
@@ -8,6 +8,41 @@ Highlights
 ==========
 
 
+Compatibility notes
+===================
+
+In a future version of numpy, the functions np.diag, np.diagonal, and
+the diagonal method of ndarrays will return a view onto the original
+array, instead of producing a copy as they do now. This makes a
+difference if you write to the array returned by any of these
+functions. To facilitate this transition, numpy 1.7 produces a
+DeprecationWarning if it detects that you may be attempting to write
+to such an array. See the documentation for np.diagonal 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.
+
+Full-array boolean indexing used to allow boolean arrays with a size
+non-broadcastable to the array size. Now it forces this to be broadcastable.
+Since this affects some legacy code, this change will require discussion
+during alpha or early beta testing, and a decision to either keep the
+stricter behavior, or add in a hack to allow the previous behavior to
+work.
+
+Attempting to write to a read-only array (one with
+``arr.flags.writeable`` set to ``False``) used to raise either a
+RuntimeError, ValueError, or TypeError inconsistently, depending on
+which code path was taken. It now consistently raises a ValueError.
+
+The <ufunc>.reduce functions evaluate some reductions in a different
+order than in previous versions of NumPy, generally providing higher
+performance. Because of the nature of floating-point arithmetic, this
+may subtly change some results, just as linking NumPy to a different
+BLAS implementations such as MKL can.
+
+
 New features
 ============
 
@@ -162,35 +197,6 @@ Changes
 General
 -------
 
-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.
-
-Full-array boolean indexing used to allow boolean arrays with a size
-non-broadcastable to the array size. Now it forces this to be broadcastable.
-Since this affects some legacy code, this change will require discussion
-during alpha or early beta testing, and a decision to either keep the
-stricter behavior, or add in a hack to allow the previous behavior to
-work.
-
-Attempting to write to a read-only array (one with
-``arr.flags.writeable`` set to ``False``) used to raise either a
-RuntimeError, ValueError, or TypeError inconsistently, depending on
-which code path was taken. It now consistently raises a ValueError.
-
-The functions np.diag, np.diagonal, and <ndarray>.diagonal now return a
-view into the original array instead of making a copy. This makes these
-functions more consistent with NumPy's general approach of taking views
-where possible, and performs much faster as well. This has the
-potential to break code that assumes a copy is made instead of a view.
-
-The <ufunc>.reduce functions evaluates some reductions in a different
-order than in previous versions of NumPy, generally providing higher
-performance. Because of the nature of floating-point arithmetic, this
-may subtly change some results, just as linking NumPy to a different
-BLAS implementations such as MKL can.
-
 The function np.concatenate tries to match the layout of its input
 arrays. Previously, the layout did not follow any particular reason,
 and depended in an undesirable way on the particular axis chosen for
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index dae109a98..2b108bcf9 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -932,7 +932,27 @@ def diagonal(a, offset=0, axis1=0, axis2=1):
     removing `axis1` and `axis2` and appending an index to the right equal
     to the size of the resulting diagonals.
 
-    As of NumPy 1.7, this function always returns a view into `a`.
+    In versions of NumPy prior to 1.7, this function always returned a new,
+    independent array containing a copy of the values in the diagonal.
+
+    In NumPy 1.7, it continues to return a copy of the diagonal, but depending
+    on this fact is deprecated. Writing to the resulting array continues to
+    work as it used to, but a DeprecationWarning will be issued.
+
+    In NumPy 1.8, it will switch to returning a read-only view on the original
+    array. Attempting to write to the resulting array will produce an error.
+
+    In NumPy 1.9, it will still return a view, but this view will no longer be
+    marked read-only. Writing to the returned array will alter your original
+    array as well.
+
+    If you don't write to the array returned by this function, then you can
+    just ignore all of the above.
+
+    If you depend on the current behavior, then we suggest copying the
+    returned array explicitly, i.e., use ``np.diagonal(a).copy()`` instead of
+    just ``np.diagonal(a)``. This will work with both past and future versions
+    of NumPy.
 
     Parameters
     ----------
diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py
index 2b518aeae..eab8f867a 100644
--- a/numpy/lib/twodim_base.py
+++ b/numpy/lib/twodim_base.py
@@ -223,12 +223,15 @@ def diag(v, k=0):
     """
     Extract a diagonal or construct a diagonal array.
 
-    As of NumPy 1.7, extracting a diagonal always returns a view into `v`.
+    See the more detailed documentation for ``numpy.diagonal`` if you use this
+    function to extract a diagonal and wish to write to the resulting array;
+    whether it returns a copy or a view depends on what version of numpy you
+    are using.
 
     Parameters
     ----------
     v : array_like
-        If `v` is a 2-D array, return a view of its `k`-th diagonal.
+        If `v` is a 2-D array, return a copy of its `k`-th diagonal.
         If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th
         diagonal.
     k : int, optional