numpy/numpy — pull request #280 by njsmith (2012-05-16 13:42:09+00:00)
Title: Clean up diagonal

This pull request implements a transition scheme so that someday PyArray_Diagonal (and its interfaces numpy.diagonal, ndarray.diagonal, etc.) can return a view rather than a copy.

The proposed scheme is:

* Numpy 1.7: PyArray_Diagonal returns a copy (as before), but writes to this copy produce a DeprecationWarning.
* Numpy 1.8: PyArray_Diagonal returns a view, but writes to this view produce an error.
* Numpy 1.9: PyArray_Diagonal returns an ordinary view, transition complete.

The 1.7 DeprecationWarning is implemented by this pull request, which adds a new hidden flag called NPY_ARRAY_WARN_ON_WRITE ('hidden' in the sense that it isn't exposed to Python by the flagsobject, though you can still see it from Python if you want by checking arr.flags.num & 0x10000). This flag is propagated through views, and, if set, causes a warning to be issued on the first write to an array.

I recommend looking at the individual commit diffs rather than the overall pull-request diff, since each commit is a self-contained unit. In particular the first 3 are generally useful cleanups independently of whatever we do with PyArray_Diagonal, the 4th implements the actual change, and the 5th documents it.