From f26e58f506e14655ac7bc6c033f49c5240d2533d Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 24 Jan 2019 10:48:54 -0600 Subject: [PATCH] DOC: Add experimental note to DatetimeArray and TimedeltaArray (#24882) * DOC: Add experimental note to DatetimeArray and TimedeltaArray --- doc/source/user_guide/integer_na.rst | 6 +++++ doc/source/whatsnew/v0.24.0.rst | 8 ++++++ pandas/core/arrays/datetimes.py | 13 ++++++++++ pandas/core/arrays/integer.py | 39 +++++++++++++++++++++++++--- pandas/core/arrays/timedeltas.py | 36 +++++++++++++++++++++++++ 5 files changed, 99 insertions(+), 3 deletions(-) diff --git a/doc/source/user_guide/integer_na.rst b/doc/source/user_guide/integer_na.rst index eb0c5e3d05863b..c5667e9319ca61 100644 --- a/doc/source/user_guide/integer_na.rst +++ b/doc/source/user_guide/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 diff --git a/doc/source/whatsnew/v0.24.0.rst b/doc/source/whatsnew/v0.24.0.rst index 4efe24789af28a..3b3fad22ce9499 100644 --- a/doc/source/whatsnew/v0.24.0.rst +++ b/doc/source/whatsnew/v0.24.0.rst @@ -32,6 +32,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`) @@ -213,6 +218,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 f2aeb1c1309dea..d7a8417a71be26 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -218,6 +218,13 @@ class DatetimeArray(dtl.DatetimeLikeArrayMixin, .. versionadded:: 0.24.0 + .. warning:: + + DatetimeArray is currently experimental, and its API may change + without warning. In particular, :attr:`DatetimeArray.dtype` is + expected to change to always be an instance of an ``ExtensionDtype`` + subclass. + Parameters ---------- values : Series, Index, DatetimeArray, ndarray @@ -511,6 +518,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, :attr:`DatetimeArray.dtype` will + always be an instance of an ``ExtensionDtype`` subclass. + Returns ------- numpy.dtype or DatetimeTZDtype diff --git a/pandas/core/arrays/integer.py b/pandas/core/arrays/integer.py index b3dde6bf2bd937..a6a4a49d3a9395 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 diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index 910cb96a862160..4f0c96f7927da1 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -107,6 +107,29 @@ 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, :attr:`TimedeltaArray.dtype` is + expected to change to be an instance of an ``ExtensionDtype`` + subclass. + + 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 +151,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 # ----------------------------------------------------------------