some docs and tests

Author: jorisvandenbossche

pandas/core/arrays/integer.py

@@ -11,6 +11,7 @@
 from pandas.core.dtypes.generic import ABCSeries, ABCIndexClass
 from pandas.core.dtypes.common import (
     is_integer, is_scalar, is_float,
+    is_bool_dtype,
     is_float_dtype,
     is_integer_dtype,
     is_object_dtype,
@@ -85,6 +86,7 @@ def integer_array(values, dtype=None, copy=False):
     values : 1D list-like
     dtype : dtype, optional
         dtype to coerce
+    copy : boolean, default False
 
     Returns
     -------
@@ -198,33 +200,40 @@ def coerce_to_array(values, dtype, mask=None, copy=False):
 
 class IntegerArray(ExtensionArray, ExtensionOpsMixin):
     """
-    We represent an IntegerArray with 2 numpy arrays
+    Array of integer (optional missing) values.
+
+    We represent an IntegerArray with 2 numpy arrays:
+
     - data: contains a numpy integer array of the appropriate dtype
-    - mask: a boolean array holding a mask on the data, False is missing
+    - mask: a boolean array holding a mask on the data, True is missing
+
+    To construct an IntegerArray from generic array-like input, use
+    ``integer_array`` function instead.
+
+    Parameters
+    ----------
+    values : integer 1D numpy array
+    mask : boolean 1D numpy array
+    copy : bool, default False
+
+    Returns
+    -------
+    IntegerArray
+
     """
 
     @cache_readonly
     def dtype(self):
         return _dtypes[str(self._data.dtype)]
 
     def __init__(self, values, mask, copy=False):
-        """
-        Parameters
-        ----------
-        values : 1D list-like / IntegerArray
-        mask : 1D list-like, optional
-        dtype : subclass of _IntegerDtype, optional
-        copy : bool, default False
-
-        Returns
-        -------
-        IntegerArray
-        """
         if not (isinstance(values, np.ndarray)
-                and np.issubdtype(values.dtype, np.integer)):
-            raise TypeError("values should be integer numpy array")
-        if not (isinstance(mask, np.ndarray) and mask.dtype == np.bool_):
-            raise TypeError("mask should be boolean numpy array")
+                and is_integer_dtype(values.dtype)):
+            raise TypeError("values should be integer numpy array. Use "
+                            "the 'integer_array' function instead")
+        if not (isinstance(mask, np.ndarray) and is_bool_dtype(mask.dtype)):
+            raise TypeError("mask should be boolean numpy array. Use "
+                            "the 'integer_array' function instead")
 
         if copy:
             values = values.copy()

pandas/tests/extension/integer/test_integer.py

@@ -645,10 +645,45 @@ def test_conversions(data_missing):
             assert type(r) == type(e)
 
 
+def test_integer_array_constructor():
+    values = np.array([1, 2, 3, 4], dtype='int64')
+    mask = np.array([False, False, False, True], dtype='bool')
+
+    result = IntegerArray(values, mask)
+    expected = integer_array([1, 2, 3, np.nan], dtype='int64')
+    tm.assert_extension_array_equal(result, expected)
+
+    with pytest.raises(TypeError):
+        IntegerArray(values.tolist(), mask)
+
+    with pytest.raises(TypeError):
+        IntegerArray(values, mask.tolist())
+
+    with pytest.raises(TypeError):
+        IntegerArray(values.astype(float), mask)
+
+    with pytest.raises(TypeError):
+        IntegerArray(values)
+
+
+def test_integer_array_constructor_copy():
+    values = np.array([1, 2, 3, 4], dtype='int64')
+    mask = np.array([False, False, False, True], dtype='bool')
+
+    result = IntegerArray(values, mask)
+    assert result._data is values
+    assert result._mask is mask
+
+    result = IntegerArray(values, mask, copy=True)
+    assert result._data is not values
+    assert result._mask is not mask
+
+
 @pytest.mark.parametrize(
     'values',
     [
         ['foo', 'bar'],
+        ['1', '2'],
         'foo',
         1,
         1.0,
@@ -660,6 +695,15 @@ def test_to_integer_array_error(values):
         integer_array(values)
 
 
+def test_to_integer_array_float():
+    result = integer_array([1., 2.])
+    expected = integer_array([1, 2])
+    tm.assert_extension_array_equal(result, expected)
+
+    with pytest.raises(TypeError, match="cannot safely cast non-equivalent"):
+        integer_array([1.5, 2.])
+
+
 @pytest.mark.parametrize(
     'values, to_dtype, result_dtype',
     [
@@ -669,6 +713,7 @@ def test_to_integer_array_error(values):
 def test_to_integer_array(values, to_dtype, result_dtype):
     # convert existing arrays to IntegerArrays
     result = integer_array(values, dtype=to_dtype)
+    assert result.dtype == result_dtype()
     expected = integer_array(values, dtype=result_dtype())
     tm.assert_extension_array_equal(result, expected)