REF/ENH: Constructors for DatetimeArray/TimedeltaArray

pandas/core/arrays/datetimelike.py

@@ -801,6 +801,25 @@ def _evaluate_compare(self, other, op):
 # -------------------------------------------------------------------
 # Shared Constructor Helpers
 
+def scalar_data_error(scalar, cls):
+    """
+    Produce the error message to issue when raising a TypeError if a scalar
+    is passed to an array constructor.
+
+    Parameters
+    ----------
+    scalar : object
+    cls : class
+
+    Returns
+    -------
+    message : str
+    """
+    return ('{cls}() must be called with a '
+            'collection of some kind, {data} was passed'
+            .format(cls=cls.__name__, data=repr(scalar)))
+
+
 def validate_periods(periods):
     """
     If a `periods` argument is passed to the Datetime/Timedelta Array/Index
@@ -888,6 +907,47 @@ def maybe_infer_freq(freq):
     return freq, freq_infer
 
 
+def maybe_define_freq(freq_infer, result):
+    """
+    If appropriate, infer the frequency of the given Datetime/Timedelta Array
+    and pin it to the object at the end of the construction.
+
+    Parameters
+    ----------
+    freq_infer : bool
+    result : DatetimeArray or TimedeltaArray
+
+    Notes
+    -----
+    This may alter `result` in-place, should only ever be called
+    from __new__/__init__.
+    """
+    if freq_infer:
+        inferred = result.inferred_freq
+        if inferred:
+            result.freq = frequencies.to_offset(inferred)
+
+
+def maybe_validate_freq(result, verify, freq, freq_infer, **kwargs):
+    """
+    If a frequency was passed by the user and not inferred or extracted
+    from the underlying data, then validate that the data is consistent with
+    the user-provided frequency.
+
+    Parameters
+    ----------
+    result : DatetimeIndex or TimedeltaIndex
+    verify : bool
+    freq : DateOffset or None
+    freq_infer : bool
+    **kwargs : arguments to pass to `_validate_frequency`
+        For DatetimeIndex this is just "ambiguous", empty for TimedeltaIndex
+    """
+    if verify and len(result) > 0:
+        if freq is not None and not freq_infer:
+            result._validate_frequency(result, freq, **kwargs)
+
+
 def validate_tz_from_dtype(dtype, tz):
     """
     If the given dtype is a DatetimeTZDtype, extract the implied

pandas/core/arrays/datetimes.py

@@ -119,7 +119,8 @@ def wrapper(self, other):
             if isinstance(other, list):
                 # FIXME: This can break for object-dtype with mixed types
                 other = type(self)(other)
-            elif not isinstance(other, (np.ndarray, ABCIndexClass, ABCSeries)):
+            elif not isinstance(other, (np.ndarray, ABCIndexClass, ABCSeries,
+                                        DatetimeArrayMixin)):
                 # Following Timestamp convention, __eq__ is all-False
                 # and __ne__ is all True, others raise TypeError.
                 return ops.invalid_comparison(self, other, op)
@@ -170,6 +171,8 @@ class DatetimeArrayMixin(dtl.DatetimeLikeArrayMixin):
     # Constructors
 
     _attributes = ["freq", "tz"]
+    _freq = None
+    _tz = None
 
     @classmethod
     def _simple_new(cls, values, freq=None, tz=None, **kwargs):
@@ -193,11 +196,16 @@ def _simple_new(cls, values, freq=None, tz=None, **kwargs):
         result._tz = timezones.tz_standardize(tz)
         return result
 
-    def __new__(cls, values, freq=None, tz=None, dtype=None):
+    def __new__(cls, values, freq=None, tz=None, dtype=None, copy=False):
+        if isinstance(values, (list, tuple)) or is_object_dtype(values):
+            values = cls._from_sequence(values, copy=copy)
+            # TODO: Can we set copy=False here to avoid re-coping?
+
         if tz is None and hasattr(values, 'tz'):
-            # e.g. DatetimeIndex
+            # e.g. DatetimeArray, DatetimeIndex
             tz = values.tz
 
+        # TODO: what about if freq == 'infer'?
         if freq is None and hasattr(values, "freq"):
             # i.e. DatetimeArray, DatetimeIndex
             freq = values.freq
@@ -207,26 +215,46 @@ def __new__(cls, values, freq=None, tz=None, dtype=None):
         # if dtype has an embedded tz, capture it
         tz = dtl.validate_tz_from_dtype(dtype, tz)
 
-        if isinstance(values, DatetimeArrayMixin):
+        if lib.is_scalar(values):
+            raise TypeError(dtl.scalar_data_error(values, cls))
+        elif isinstance(values, ABCSeries):
+            # extract nanosecond unix timestamps
+            if tz is None:
+                # TODO: Try to do this in just one place
+                tz = values.dt.tz
+            values = np.array(values.view('i8'))
+        elif isinstance(values, DatetimeArrayMixin):
             # extract nanosecond unix timestamps
             values = values.asi8
+
         if values.dtype == 'i8':
             values = values.view('M8[ns]')
 
         assert isinstance(values, np.ndarray), type(values)
         assert is_datetime64_dtype(values)  # not yet assured nanosecond
-        values = conversion.ensure_datetime64ns(values, copy=False)
+        values = conversion.ensure_datetime64ns(values, copy=copy)
 
         result = cls._simple_new(values, freq=freq, tz=tz)
-        if freq_infer:
-            inferred = result.inferred_freq
-            if inferred:
-                result.freq = to_offset(inferred)
+        dtl.maybe_define_freq(freq_infer, result)
 
         # NB: Among other things not yet ported from the DatetimeIndex
         # constructor, this does not call _deepcopy_if_needed
         return result
 
+    @classmethod
+    def _from_sequence(cls, scalars, dtype=None, copy=False):
+        # list, tuple, or object-dtype ndarray/Index
+        values = np.array(scalars, dtype=np.object_, copy=copy)
+        if values.ndim != 1:
+            raise TypeError("Values must be 1-dimensional")
+
+        # TODO: See if we can decrease circularity
+        from pandas.core.tools.datetimes import to_datetime
+        values = to_datetime(values)
+
+        # pass dtype to constructor in order to convert timezone if necessary
+        return cls(values, dtype=dtype)
+
     @classmethod
     def _generate_range(cls, start, end, periods, freq, tz=None,
                         normalize=False, ambiguous='raise', closed=None):

pandas/core/arrays/period.py

@@ -165,7 +165,9 @@ class PeriodArray(dtl.DatetimeLikeArrayMixin, ExtensionArray):
 
     # --------------------------------------------------------------------
     # Constructors
-    def __init__(self, values, freq=None, copy=False):
+    def __init__(self, values, freq=None, dtype=None, copy=False):
+        freq = dtl.validate_dtype_freq(dtype, freq)
+
         if freq is not None:
             freq = Period._maybe_convert_freq(freq)
 

pandas/core/arrays/timedeltas.py

@@ -3,23 +3,22 @@
 
 import numpy as np
 
-from pandas._libs import tslibs
+from pandas._libs import tslibs, lib, algos
 from pandas._libs.tslibs import Timedelta, Timestamp, NaT
 from pandas._libs.tslibs.fields import get_timedelta_field
 from pandas._libs.tslibs.timedeltas import array_to_timedelta64
 
 from pandas import compat
 
 from pandas.core.dtypes.common import (
-    _TD_DTYPE, is_list_like)
+    _TD_DTYPE, is_list_like, is_object_dtype, is_timedelta64_dtype)
 from pandas.core.dtypes.generic import ABCSeries
 from pandas.core.dtypes.missing import isna
 
 import pandas.core.common as com
 from pandas.core.algorithms import checked_add_with_arr
 
 from pandas.tseries.offsets import Tick
-from pandas.tseries.frequencies import to_offset
 
 from . import datetimelike as dtl
 
@@ -112,9 +111,7 @@ def dtype(self):
 
     @classmethod
     def _simple_new(cls, values, freq=None, dtype=_TD_DTYPE):
-        # `dtype` is passed by _shallow_copy in corner cases, should always
-        #  be timedelta64[ns] if present
-        assert dtype == _TD_DTYPE
+        _require_m8ns_dtype(dtype)
         assert isinstance(values, np.ndarray), type(values)
 
         if values.dtype == 'i8':
@@ -127,22 +124,48 @@ def _simple_new(cls, values, freq=None, dtype=_TD_DTYPE):
         result._freq = freq
         return result
 
-    def __new__(cls, values, freq=None):
+    def __new__(cls, values, freq=None, dtype=_TD_DTYPE, copy=False):
+        _require_m8ns_dtype(dtype)
+
+        if isinstance(values, (list, tuple)) or is_object_dtype(values):
+            values = cls._from_sequence(values, copy=copy)._data
+            # TODO: can we set copy=False to avoid re-copying?
 
         freq, freq_infer = dtl.maybe_infer_freq(freq)
 
-        values = np.array(values, copy=False)
-        if values.dtype == np.object_:
-            values = array_to_timedelta64(values)
+        if lib.is_scalar(values):
+            raise TypeError(dtl.scalar_data_error(values, cls))
+        elif isinstance(values, TimedeltaArrayMixin):
+            if freq is None and values.freq is not None:
+                freq = values.freq
+                freq_infer = False
+            values = values._data
 
-        result = cls._simple_new(values, freq=freq)
-        if freq_infer:
-            inferred = result.inferred_freq
-            if inferred:
-                result.freq = to_offset(inferred)
+        values = np.array(values, copy=copy)
+
+        if values.dtype == 'i8':
+            pass
+        elif not is_timedelta64_dtype(values):
+            raise TypeError(values.dtype)
+        elif values.dtype != _TD_DTYPE:
+            # i.e. non-nano unit
+            # TODO: use tslibs.conversion func? watch out for overflows
+            values = values.astype(_TD_DTYPE)
 
+        result = cls._simple_new(values, freq=freq)
+        dtl.maybe_define_freq(freq_infer, result)
         return result
 
+    @classmethod
+    def _from_sequence(cls, scalars, dtype=_TD_DTYPE, copy=False):
+        # list, tuple, or object-dtype ndarray/Index
+        values = np.array(scalars, dtype=np.object_, copy=copy)
+        if values.ndim != 1:
+            raise TypeError("Values must be 1-dimensional")
+
+        result = array_to_timedelta64(values)
+        return cls(result, dtype=dtype)
+
     @classmethod
     def _generate_range(cls, start, end, periods, freq, closed=None):
 
@@ -180,6 +203,23 @@ def _generate_range(cls, start, end, periods, freq, closed=None):
 
         return cls._simple_new(index, freq=freq)
 
+    # ----------------------------------------------------------------
+    # Array-Like Methods
+    # NB: these are appreciably less efficient than the TimedeltaIndex versions
+
+    @property
+    def is_monotonic_increasing(self):
+        return algos.is_monotonic(self.asi8, timelike=True)[0]
+
+    @property
+    def is_monotonic_decreasing(self):
+        return algos.is_monotonic(self.asi8, timelike=True)[1]
+
+    @property
+    def is_unique(self):
+        from pandas.core.algorithms import unique1d
+        return len(unique1d(self.asi8)) == len(self)
+
     # ----------------------------------------------------------------
     # Arithmetic Methods
 
@@ -413,3 +453,21 @@ def _generate_regular_range(start, end, periods, offset):
 
     data = np.arange(b, e, stride, dtype=np.int64)
     return data
+
+
+def _require_m8ns_dtype(dtype):
+    """
+    `dtype` is included in the constructor signature for consistency with
+    DatetimeArray and PeriodArray, but only timedelta64[ns] is considered
+    valid.  Raise if anything else is passed.
+
+    Parameters
+    ----------
+    dtype : dtype
+
+    Raises
+    ------
+    ValueError
+    """
+    if dtype != _TD_DTYPE:
+        raise ValueError("Only timedelta64[ns] dtype is valid.", dtype)