API, DOC: Clarify and Enforce Array to be 1-D during SparseArray Init…

… Construction

closes #12794

Author: gfyoung <gfyoung17@gmail.com>

Closes #13011 from gfyoung/sparse-array-clarify and squashes the following commits:

0746e1d [gfyoung] API, DOC: Clarify and enforce array to be 1-D during SparseArray construction

pandas/sparse/array.py

@@ -87,11 +87,11 @@ def _wrap_result(name, data, sparse_index, fill_value):
 
 
 class SparseArray(PandasObject, np.ndarray):
-    """Data structure for labeled, sparse floating point data
+    """Data structure for labeled, sparse floating point 1-D data
 
     Parameters
     ----------
-    data : {array-like, Series, SparseSeries, dict}
+    data : {array-like (1-D), Series, SparseSeries, dict}
     kind : {'block', 'integer'}
     fill_value : float
         Defaults to NaN (code for missing)
@@ -563,7 +563,9 @@ def make_sparse(arr, kind='block', fill_value=nan):
     """
 
     arr = _sanitize_values(arr)
-    length = len(arr)
+
+    if arr.ndim > 1:
+        raise TypeError("expected dimension <= 1 data")
 
     if np.isnan(fill_value):
         mask = ~np.isnan(arr)

pandas/sparse/tests/test_array.py

@@ -234,6 +234,10 @@ def setslice():
         assertRaisesRegexp(TypeError, "item assignment", setitem)
         assertRaisesRegexp(TypeError, "item assignment", setslice)
 
+    def test_constructor_from_too_large_array(self):
+        assertRaisesRegexp(TypeError, "expected dimension <= 1 data",
+                           SparseArray, np.arange(10).reshape((2, 5)))
+
     def test_constructor_from_sparse(self):
         res = SparseArray(self.zarr)
         self.assertEqual(res.fill_value, 0)