From 5569fd97190009c11c8a3c0dfd1cd1ce60dfafc6 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 23 Jan 2019 07:26:43 -0600 Subject: [PATCH 1/5] DOC: Add experimental note to DatetimeArray and TimedeltaArray DOC: Mention PeriodArray and IntervalArray Closes #24870 --- doc/source/whatsnew/v0.24.0.rst | 3 +++ pandas/core/arrays/datetimes.py | 12 +++++++++++ pandas/core/arrays/timedeltas.py | 35 ++++++++++++++++++++++++++++++++ 3 files changed, 50 insertions(+) diff --git a/doc/source/whatsnew/v0.24.0.rst b/doc/source/whatsnew/v0.24.0.rst index 3dd345890881c..3a1f56579c5e9 100644 --- a/doc/source/whatsnew/v0.24.0.rst +++ b/doc/source/whatsnew/v0.24.0.rst @@ -210,6 +210,9 @@ from the ``Series``: ser.array pser.array +These return an instance of :class:`IntervalArray` or :class:`arrays.PeriodArray`, +the new extension arrays that back interval and period data. + .. warning:: For backwards compatibility, :attr:`Series.values` continues to return diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index f2aeb1c1309de..d2e74ed6b15d0 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -218,6 +218,12 @@ class DatetimeArray(dtl.DatetimeLikeArrayMixin, .. versionadded:: 0.24.0 + .. warning:: + + DatetimeArray is currently experimental, and its API may change + without warning. In particular, :meth:`DatetimeArray.dtype` is + expected to change to always be an ``ExtensionDtype``. + Parameters ---------- values : Series, Index, DatetimeArray, ndarray @@ -511,6 +517,12 @@ def dtype(self): """ The dtype for the DatetimeArray. + .. warning:: + + A future version of pandas will change dtype to never be a + ``numpy.dtype``. Instead it will always be a subclass of + :class:`pandas.api.extensions.ExtensionDtype`. + Returns ------- numpy.dtype or DatetimeTZDtype diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index 910cb96a86216..b17cb9a215c3e 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -107,6 +107,28 @@ def wrapper(self, other): class TimedeltaArray(dtl.DatetimeLikeArrayMixin, dtl.TimelikeOps): + """ + Pandas ExtensionArray for timedelta data. + + .. versionadded :: 0.24.0 + + .. warning:: + + TimedeltaArray is currently experimental, and its API may change + without warning. In particular, :meth:`TimedeltaArray.dtype` is + expected to change to be an ``ExtensionDtype``. + + Parameters + ---------- + values : array-like + The timedelta data. + + dtype : numpy.dtype + Currently, only ``numpy.dtype("timedelta64[ns]")`` is accepted. + freq : Offset, optional + copy : bool, default False + Whether to copy the underlying array of data. + """ _typ = "timedeltaarray" _scalar_type = Timedelta __array_priority__ = 1000 @@ -128,6 +150,19 @@ def _box_func(self): @property def dtype(self): + """ + The dtype for the TimedeltaArray. + + .. warning:: + + A future version of pandas will change dtype to be an instance + of a :class:`pandas.api.extensions.ExtensionDtype` subclass, + not a ``numpy.dtype``. + + Returns + ------- + numpy.dtype + """ return _TD_DTYPE # ---------------------------------------------------------------- From e068fee345eba58589a6e4617c58e3fd7a5560d3 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 23 Jan 2019 07:30:51 -0600 Subject: [PATCH 2/5] wording --- pandas/core/arrays/datetimes.py | 9 +++++---- pandas/core/arrays/timedeltas.py | 5 +++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index d2e74ed6b15d0..d7a8417a71be2 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -221,8 +221,9 @@ class DatetimeArray(dtl.DatetimeLikeArrayMixin, .. warning:: DatetimeArray is currently experimental, and its API may change - without warning. In particular, :meth:`DatetimeArray.dtype` is - expected to change to always be an ``ExtensionDtype``. + without warning. In particular, :attr:`DatetimeArray.dtype` is + expected to change to always be an instance of an ``ExtensionDtype`` + subclass. Parameters ---------- @@ -520,8 +521,8 @@ def dtype(self): .. warning:: A future version of pandas will change dtype to never be a - ``numpy.dtype``. Instead it will always be a subclass of - :class:`pandas.api.extensions.ExtensionDtype`. + ``numpy.dtype``. Instead, :attr:`DatetimeArray.dtype` will + always be an instance of an ``ExtensionDtype`` subclass. Returns ------- diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index b17cb9a215c3e..8da963a6f948f 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -115,8 +115,9 @@ class TimedeltaArray(dtl.DatetimeLikeArrayMixin, dtl.TimelikeOps): .. warning:: TimedeltaArray is currently experimental, and its API may change - without warning. In particular, :meth:`TimedeltaArray.dtype` is - expected to change to be an ``ExtensionDtype``. + without warning. In particular, :attr:`TimedeltaArray.dtype` is + expected to change to be an instance of an ``ExtensionDtype`` + subclass. Parameters ---------- From 35337f3e38e42418ca496ec3c1246ff198d2a13b Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Wed, 23 Jan 2019 14:28:21 -0600 Subject: [PATCH 3/5] Update timedeltas.py [ci skip] --- pandas/core/arrays/timedeltas.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index 8da963a6f948f..4f0c96f7927da 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -110,7 +110,7 @@ class TimedeltaArray(dtl.DatetimeLikeArrayMixin, dtl.TimelikeOps): """ Pandas ExtensionArray for timedelta data. - .. versionadded :: 0.24.0 + .. versionadded:: 0.24.0 .. warning:: From e65fa9077ad3991965795499990e2d8bc77f1f2e Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 24 Jan 2019 08:35:30 -0600 Subject: [PATCH 4/5] integerarray --- doc/source/whatsnew/v0.24.0.rst | 5 +++++ pandas/core/arrays/integer.py | 39 ++++++++++++++++++++++++++++++--- 2 files changed, 41 insertions(+), 3 deletions(-) diff --git a/doc/source/whatsnew/v0.24.0.rst b/doc/source/whatsnew/v0.24.0.rst index 3a1f56579c5e9..b96fec586097d 100644 --- a/doc/source/whatsnew/v0.24.0.rst +++ b/doc/source/whatsnew/v0.24.0.rst @@ -29,6 +29,11 @@ Optional Integer NA Support Pandas has gained the ability to hold integer dtypes with missing values. This long requested feature is enabled through the use of :ref:`extension types `. Here is an example of the usage. +.. note:: + + IntegerArray is currently experimental. Its API or implementation may + change without warning. + We can construct a ``Series`` with the specified dtype. The dtype string ``Int64`` is a pandas ``ExtensionDtype``. Specifying a 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. (:issue:`20700`, :issue:`20747`, :issue:`22441`, :issue:`21789`, :issue:`22346`) diff --git a/pandas/core/arrays/integer.py b/pandas/core/arrays/integer.py index b3dde6bf2bd93..a6a4a49d3a939 100644 --- a/pandas/core/arrays/integer.py +++ b/pandas/core/arrays/integer.py @@ -225,24 +225,57 @@ class IntegerArray(ExtensionArray, ExtensionOpsMixin): """ Array of integer (optional missing) values. + .. versionadded:: 0.24.0 + + .. warning:: + + IntegerArray is currently experimental, and its API or internal + implementation may change without warning. + 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, True is missing To construct an IntegerArray from generic array-like input, use - ``integer_array`` function instead. + :func:`pandas.array` with one of the integer dtypes (see examples). + + See :ref:`integer_na` for more. Parameters ---------- - values : integer 1D numpy array - mask : boolean 1D numpy array + values : numpy.ndarray + A 1-d integer-dtype array. + mask : numpy.ndarray + A 1-d boolean-dtype array indicating missing values. copy : bool, default False + Whether to copy the `values` and `mask`. Returns ------- IntegerArray + Examples + -------- + Create an IntegerArray with :func:`pandas.array`. + + >>> int_array = pd.array([1, None, 3], dtype=pd.Int32Dtype()) + >>> int_array + + [1, NaN, 3] + Length: 3, dtype: Int32 + + String aliases for the dtypes are also available. They are capitalized. + + >>> pd.array([1, None, 3], dtype='Int32') + + [1, NaN, 3] + Length: 3, dtype: Int32 + + >>> pd.array([1, None, 3], dtype='UInt16') + + [1, NaN, 3] + Length: 3, dtype: UInt16 """ @cache_readonly From 5bec9e47a1ead6ad2ed07a4072b15a32a88e8186 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 24 Jan 2019 10:47:54 -0600 Subject: [PATCH 5/5] added integer_na --- doc/source/integer_na.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/source/integer_na.rst b/doc/source/integer_na.rst index eb0c5e3d05863..c5667e9319ca6 100644 --- a/doc/source/integer_na.rst +++ b/doc/source/integer_na.rst @@ -10,6 +10,12 @@ Nullable Integer Data Type .. versionadded:: 0.24.0 +.. note:: + + IntegerArray is currently experimental. Its API or implementation may + change without warning. + + In :ref:`missing_data`, we saw that pandas primarily uses ``NaN`` to represent missing data. Because ``NaN`` is a float, this forces an array of integers with any missing values to become floating point. In some cases, this may not matter