ENH: add NpyIter_Close, nditer__{enter,exit}__

1 files changed, 40 insertions, 8 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index c2348b462..193093109 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -319,8 +319,9 @@ add_newdoc('numpy.core', 'nditer',
             addop = np.add
             it = np.nditer([x, y, out], [],
                         [['readonly'], ['readonly'], ['writeonly','allocate']])
-            for (a, b, c) in it:
-                addop(a, b, out=c)
+            with it:
+                for (a, b, c) in it:
+                    addop(a, b, out=c)
             return it.operands[2]
 
     Here is the same function, but following the C-style pattern::
@@ -344,13 +345,12 @@ add_newdoc('numpy.core', 'nditer',
 
             it = np.nditer([x, y, out], ['external_loop'],
                     [['readonly'], ['readonly'], ['writeonly', 'allocate']],
-                    op_axes=[range(x.ndim)+[-1]*y.ndim,
-                             [-1]*x.ndim+range(y.ndim),
+                    op_axes=[list(range(x.ndim)) + [-1] * y.ndim,
+                             [-1] * x.ndim + list(range(y.ndim)),
                              None])
-
-            for (a, b, c) in it:
-                mulop(a, b, out=c)
-
+            with it:
+                for (a, b, c) in it:
+                    mulop(a, b, out=c)
             return it.operands[2]
 
         >>> a = np.arange(2)+1
@@ -381,6 +381,31 @@ add_newdoc('numpy.core', 'nditer',
         >>> luf(lambda i,j:i*i + j/2, a, b)
         array([  0.5,   1.5,   4.5,   9.5,  16.5])
 
+    If operand flags `"writeonly"` or `"readwrite"` are used the operands may
+    be views into the original data with the WRITEBACKIFCOPY flag. In this case
+    nditer must be used as a context manager. The temporary
+    data will be written back to the original data when the `` __exit__``
+    function is called but not before::
+
+        >>> a = np.arange(6, dtype='i4')[::-2]
+        >>> with nditer(a, [],
+        ...        [['writeonly', 'updateifcopy']],
+        ...        casting='unsafe',
+        ...        op_dtypes=[np.dtype('f4')]) as i:
+        ...    i.operands[0][:] = [-1, -2, -3]
+        ...    # a still unchanged here
+        >>> a
+        array([-1, -2, -3])
+
+    It is important to note that once the iterator is exited, dangling
+    references (like `x` in the example) may or may not share data with
+    the original data `a`. If writeback semantics were active, i.e. if
+    `x.base.flags.writebackifcopy` is `True`, then exiting the iterator
+     will sever the connection between `x` and `a`, writing to `x` will
+    no longer write to `a`. If writeback semantics are not active, then
+    `x.data` will still point at some part of `a.data`, and writing to
+    one will affect the other.
+
     """)
 
 # nditer methods
@@ -524,6 +549,13 @@ add_newdoc('numpy.core', 'nested_iters',
 
     """)
 
+add_newdoc('numpy.core', 'nditer', ('close',
+    """
+    close()
+
+    Resolve all writeback semantics in operands.
+
+    """))
 
 
 ###############################################################################