From f2b27fb90809bdf464e66b9f3be8037e9a72c0f7 Mon Sep 17 00:00:00 2001
From: Eric Wieser <wieser.eric@gmail.com>
Date: Sat, 4 Mar 2017 02:39:14 +0000
Subject: DOC: expand_dims and squeeze are inverses

[ci skip]
---
 numpy/core/fromnumeric.py | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'numpy/core/fromnumeric.py')

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 58f8696d2..ed7c7eb93 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1162,6 +1162,16 @@ def squeeze(a, axis=None):
         dimensions of length 1 removed. This is always `a` itself
         or a view into `a`.
 
+    Raises
+    ------
+    ValueError
+        If `axis` is not `None`, and an axis being squeezed is not of length 1
+
+    See Also
+    --------
+    expand_dims : The inverse operation, adding singleton dimensions
+    reshape : Insert, remove, and combine dimensions, and resize existing ones
+
     Examples
     --------
     >>> x = np.array([[[0], [1], [2]]])
@@ -1169,7 +1179,13 @@ def squeeze(a, axis=None):
     (1, 3, 1)
     >>> np.squeeze(x).shape
     (3,)
-    >>> np.squeeze(x, axis=(2,)).shape
+    >>> np.squeeze(x, axis=0).shape
+    (3, 1)
+    >>> np.squeeze(x, axis=1).shape
+    Traceback (most recent call last):
+    ...
+    ValueError: cannot select an axis to squeeze out which has size not equal to one
+    >>> np.squeeze(x, axis=2).shape
     (1, 3)
 
     """
-- 
cgit v1.2.1