Clarify docstring for numpy.array_split

Before this addition, people could expect that only the last sub-array would have a different size. The added documentation and example make clear what the function really does.

1 files changed, 7 insertions, 1 deletions

diff --git a/numpy/lib/shape_base.py b/numpy/lib/shape_base.py
index deab938ea..a8977bd4c 100644
--- a/numpy/lib/shape_base.py
+++ b/numpy/lib/shape_base.py
@@ -421,7 +421,9 @@ def array_split(ary, indices_or_sections, axis=0):
     Please refer to the ``split`` documentation.  The only difference
     between these functions is that ``array_split`` allows
     `indices_or_sections` to be an integer that does *not* equally
-    divide the axis.
+    divide the axis. For an array of length l that should be split 
+    into n sections, it returns l % n sub-arrays of size l//n + 1 
+    and the rest of size l//n.
 
     See Also
     --------
@@ -433,6 +435,10 @@ def array_split(ary, indices_or_sections, axis=0):
     >>> np.array_split(x, 3)
         [array([ 0.,  1.,  2.]), array([ 3.,  4.,  5.]), array([ 6.,  7.])]
 
+    >>> x = np.arange(7.0)
+    >>> np.array_split(x, 3)
+        [array([ 0.,  1.,  2.]), array([ 3.,  4.]), array([ 5.,  6.])]
+
     """
     try:
         Ntotal = ary.shape[axis]