docs

Author: jreback

doc/source/whatsnew/v0.24.0.txt

@@ -8,6 +8,54 @@ v0.24.0
 New features
 ~~~~~~~~~~~~
 
+Integer NA Support
+^^^^^^^^^^^^^^^^^^
+
+TODO(update docs)
+Pandas has gained the ability to hold integer dtypes with missing values. This long requested feature is enable thru the use of ``ExtensionTypes`` . Here is an example of usage.
+
+We can construct a ``Series`` with the specified dtype. The dtype string ``Int64`` is a pandas ``ExtensionDtype``. Specifying an list or array using the traditional missing value
+marker of ``np.nan`` will infer to integer dtype. The display of the ``Series`` will also use the ``NaN`` to indicate missing values in string outputs.
+
+.. ipython:: python
+
+   s = pd.Series([1, 2, np.nan], dtype='Int64')
+   s
+
+
+Operations on these dtypes will propagate ``NaN`` as other pandas operations.
+
+.. ipython:: python
+
+   # arithmetic
+   s + 1
+
+   # comparison
+   s == 1
+
+   # indexing
+   s.iloc[1:3]
+
+   # operate with other dtypes
+   s + s.iloc[1:3]
+
+These dtypes can operate as part of ``DataFrames`` as well.
+
+.. ipython:: python
+
+   df = pd.DataFrame({'A': s, 'B': [1, 2, 3], 'C': list('aab')})
+   df
+   df.dtypes
+
+
+These dtypes can be merged & reshaped & casted as well.
+
+.. ipython:: python
+
+   pd.concat([df[['A']], df[['B', 'C']]], axis=1).dtypes
+   df['A'].astype(float)
+
+
 .. _whatsnew_0240.enhancements.other:
 
 Other Enhancements

pandas/tests/extension/integer/test_integer.py

@@ -412,3 +412,12 @@ def test_cross_type_arithmetic():
     result = df.A + df.B
     expected = pd.Series([2, np.nan, np.nan], dtype='Int64')
     tm.assert_series_equal(result, expected)
+
+
+# TODO(jreback) - these need testing / are broken
+
+# groupby
+
+# shift
+
+# set_index (destroys type)