doc / astype updates

Author: sinhrks

doc/source/timeseries.rst

@@ -1604,18 +1604,20 @@ Period Dtypes
 .. versionadded:: 0.19.0
 
 ``PeriodIndex`` has a custom ``period`` dtype. This is a pandas extension
-dtype similar to the timezone aware dtype (``datetime64[ns, tz]``).
+dtype similar to the :ref:`timezone aware dtype <timeseries.timezone_series>` (``datetime64[ns, tz]``).
+
+.. _timeseries.timezone_series:
 
 The ``period`` dtype holds the ``freq`` attribute and is represented with
-``period[freq]``, using :ref:`frequency strings <timeseries.offset_aliases>`.
+``period[freq]`` like ``period[D]`` or ``period[M]``, using :ref:`frequency strings <timeseries.offset_aliases>`.
 
 .. ipython:: python
 
    pi = pd.period_range('2016-01-01', periods=3, freq='M')
    pi
    pi.dtype
 
-The ``period`` dtype can be used in ``.astype(...)``. It allows to change the
+The ``period`` dtype can be used in ``.astype(...)``. It allows one to change the
 ``freq`` of a ``PeriodIndex`` like ``.asfreq()`` and convert a
 ``DatetimeIndex`` to ``PeriodIndex`` like ``to_period()``:
 
@@ -1624,6 +1626,9 @@ The ``period`` dtype can be used in ``.astype(...)``. It allows to change the
    # change monthly freq to daily freq
    pi.astype('period[D]')
 
+   # convert to DatetimeIndex
+   pi.astype('datetime64[ns]')
+
    # convert to PeriodIndex
    dti = pd.date_range('2011-01-01', freq='M', periods=3)
    dti

doc/source/whatsnew/v0.19.0.txt

@@ -634,8 +634,8 @@ Furthermore:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``PeriodIndex`` now has its own ``period`` dtype. The ``period`` dtype is a
-pandas extension dtype which extends NumPy dtype like ``"category"`` (:issue:`13941`).
-As a consequence of this change, `PeriodIndex` no longer has an integer dtype:
+pandas extension dtype like ``category`` or :ref:`timezone aware dtype <timeseries.timezone_series>` (``datetime64[ns, tz]``). (:issue:`13941`).
+As a consequence of this change, ``PeriodIndex`` no longer has an integer dtype:
 
 Previous Behavior:
 

pandas/core/algorithms.py

@@ -405,6 +405,7 @@ def _value_counts_arraylike(values, dropna=True):
 
     if needs_i8_conversion(dtype) or is_period_type:
 
+        from pandas.tseries.index import DatetimeIndex
         from pandas.tseries.period import PeriodIndex
 
         if is_period_type:
@@ -424,7 +425,6 @@ def _value_counts_arraylike(values, dropna=True):
 
         # dtype handling
         if is_datetimetz_type:
-            from pandas.tseries.index import DatetimeIndex
             keys = DatetimeIndex._simple_new(keys, tz=orig.dtype.tz)
         if is_period_type:
             keys = PeriodIndex._simple_new(keys, freq=freq)

pandas/tests/indexes/test_datetimelike.py

@@ -790,8 +790,6 @@ def test_astype_raises(self):
         self.assertRaises(ValueError, idx.astype, float)
         self.assertRaises(ValueError, idx.astype, 'timedelta64')
         self.assertRaises(ValueError, idx.astype, 'timedelta64[ns]')
-        self.assertRaises(ValueError, idx.astype, 'datetime64')
-        self.assertRaises(ValueError, idx.astype, 'datetime64[ns]')
 
     def test_shift(self):
 

pandas/tests/types/test_common.py

@@ -6,16 +6,39 @@
 from pandas.types.dtypes import DatetimeTZDtype, PeriodDtype, CategoricalDtype
 from pandas.types.common import pandas_dtype, is_dtype_equal
 
+import pandas.util.testing as tm
+
 _multiprocess_can_split_ = True
 
 
-def test_pandas_dtype():
+class TestPandasDtype(tm.TestCase):
+
+    def test_numpy_dtype(self):
+        for dtype in ['M8[ns]', 'm8[ns]', 'object', 'float64', 'int64']:
+            self.assertEqual(pandas_dtype(dtype), np.dtype(dtype))
+
+    def test_numpy_string_dtype(self):
+        # do not parse freq-like string as period dtype
+        self.assertEqual(pandas_dtype('U'), np.dtype('U'))
+        self.assertEqual(pandas_dtype('S'), np.dtype('S'))
+
+    def test_datetimetz_dtype(self):
+        for dtype in ['datetime64[ns, US/Eastern]',
+                      'datetime64[ns, Asia/Tokyo]',
+                      'datetime64[ns, UTC]']:
+            self.assertIs(pandas_dtype(dtype), DatetimeTZDtype(dtype))
+            self.assertEqual(pandas_dtype(dtype), DatetimeTZDtype(dtype))
+            self.assertEqual(pandas_dtype(dtype), dtype)
+
+    def test_categorical_dtype(self):
+        self.assertEqual(pandas_dtype('category'), CategoricalDtype())
 
-    assert pandas_dtype('datetime64[ns, US/Eastern]') == DatetimeTZDtype(
-        'datetime64[ns, US/Eastern]')
-    assert pandas_dtype('category') == CategoricalDtype()
-    for dtype in ['M8[ns]', 'm8[ns]', 'object', 'float64', 'int64']:
-        assert pandas_dtype(dtype) == np.dtype(dtype)
+    def test_period_dtype(self):
+        for dtype in ['period[D]', 'period[3M]', 'period[U]',
+                      'Period[D]', 'Period[3M]', 'Period[U]']:
+            self.assertIs(pandas_dtype(dtype), PeriodDtype(dtype))
+            self.assertEqual(pandas_dtype(dtype), PeriodDtype(dtype))
+            self.assertEqual(pandas_dtype(dtype), dtype)
 
 
 def test_dtype_equal():

pandas/tests/types/test_dtypes.py

@@ -12,7 +12,7 @@
                                  is_period_dtype, is_period,
                                  is_dtype_equal, is_datetime64_ns_dtype,
                                  is_datetime64_dtype, is_string_dtype,
-                                 _coerce_to_dtype, pandas_dtype)
+                                 _coerce_to_dtype)
 import pandas.util.testing as tm
 
 _multiprocess_can_split_ = True
@@ -268,25 +268,6 @@ def test_coerce_to_dtype(self):
         self.assertEqual(_coerce_to_dtype('period[3M]'),
                          PeriodDtype('period[3M]'))
 
-    def test_pandas_dtype(self):
-        self.assertEqual(pandas_dtype('period[D]'),
-                         PeriodDtype('period[D]'))
-        self.assertEqual(pandas_dtype('period[3M]'),
-                         PeriodDtype('period[3M]'))
-        self.assertEqual(pandas_dtype('period[U]'),
-                         PeriodDtype('period[U]'))
-        # capital P
-        self.assertEqual(pandas_dtype('Period[D]'),
-                         PeriodDtype('period[D]'))
-        self.assertEqual(pandas_dtype('Period[3M]'),
-                         PeriodDtype('period[3M]'))
-        self.assertEqual(pandas_dtype('Period[U]'),
-                         PeriodDtype('period[U]'))
-
-        # do not parse freq-like string as period dtype
-        self.assertEqual(pandas_dtype('U'), np.dtype('U'))
-        self.assertEqual(pandas_dtype('S'), np.dtype('S'))
-
     def test_compat(self):
         self.assertFalse(is_datetime64_ns_dtype(self.dtype))
         self.assertFalse(is_datetime64_ns_dtype('period[D]'))
@@ -305,6 +286,11 @@ def test_construction_from_string(self):
         with tm.assertRaises(TypeError):
             PeriodDtype.construct_from_string('foo[D]')
 
+        with tm.assertRaises(TypeError):
+            PeriodDtype.construct_from_string('datetime64[ns]')
+        with tm.assertRaises(TypeError):
+            PeriodDtype.construct_from_string('datetime64[ns, US/Eastern]')
+
     def test_is_dtype(self):
         self.assertTrue(PeriodDtype.is_dtype(self.dtype))
         self.assertTrue(PeriodDtype.is_dtype('period[D]'))

pandas/tseries/period.py

@@ -10,6 +10,8 @@
                                  is_integer_dtype,
                                  is_float_dtype,
                                  is_scalar,
+                                 is_datetime64_dtype,
+                                 is_datetime64tz_dtype,
                                  is_timedelta64_dtype,
                                  is_period_dtype,
                                  is_bool_dtype,
@@ -411,13 +413,17 @@ def asof_locs(self, where, mask):
         return result
 
     @Appender(_index_shared_docs['astype'])
-    def astype(self, dtype, copy=True):
+    def astype(self, dtype, copy=True, how='start'):
         dtype = pandas_dtype(dtype)
         if is_object_dtype(dtype):
             return self.asobject
         elif is_integer_dtype(dtype):
             return Index(self.values.astype('i8', copy=copy), name=self.name,
                          dtype='i8')
+        elif is_datetime64_dtype(dtype):
+            return self.to_timestamp(how=how)
+        elif is_datetime64tz_dtype(dtype):
+            return self.to_timestamp(how=how).tz_localize(dtype.tz)
         elif is_period_dtype(dtype):
             return self.asfreq(freq=dtype.freq)
         raise ValueError('Cannot cast PeriodIndex to dtype %s' % dtype)

pandas/tseries/tests/test_period.py

@@ -3096,6 +3096,25 @@ def test_period_dt64_round_trip(self):
         pi = dti.to_period(freq='H')
         tm.assert_index_equal(pi.to_timestamp(), dti)
 
+    def test_period_astype_to_timestamp(self):
+        pi = pd.PeriodIndex(['2011-01', '2011-02', '2011-03'], freq='M')
+
+        exp = pd.DatetimeIndex(['2011-01-01', '2011-02-01', '2011-03-01'])
+        tm.assert_index_equal(pi.astype('datetime64[ns]'), exp)
+
+        exp = pd.DatetimeIndex(['2011-01-31', '2011-02-28', '2011-03-31'])
+        tm.assert_index_equal(pi.astype('datetime64[ns]', how='end'), exp)
+
+        exp = pd.DatetimeIndex(['2011-01-01', '2011-02-01', '2011-03-01'],
+                               tz='US/Eastern')
+        res = pi.astype('datetime64[ns, US/Eastern]')
+        tm.assert_index_equal(pi.astype('datetime64[ns, US/Eastern]'), exp)
+
+        exp = pd.DatetimeIndex(['2011-01-31', '2011-02-28', '2011-03-31'],
+                               tz='US/Eastern')
+        res = pi.astype('datetime64[ns, US/Eastern]', how='end')
+        tm.assert_index_equal(res, exp)
+
     def test_to_period_quarterly(self):
         # make sure we can make the round trip
         for month in MONTHS:

pandas/types/dtypes.py

@@ -286,10 +286,8 @@ def __new__(cls, freq=None):
             # empty constructor for pickle compat
             return object.__new__(cls)
 
-        from pandas._period import Period
-        try:
-            freq = Period._maybe_convert_freq(freq)
-        except ValueError:
+        from pandas.tseries.offsets import DateOffset
+        if not isinstance(freq, DateOffset):
             freq = cls._parse_dtype_strict(freq)
 
         try:
@@ -302,16 +300,16 @@ def __new__(cls, freq=None):
 
     @classmethod
     def _parse_dtype_strict(cls, freq):
-        try:
-            m = cls._match.search(freq)
-            if m is not None:
-                from pandas._period import Period
-                freq = m.group('freq')
-                freq = Period._maybe_convert_freq(freq)
-                if freq is not None:
-                    return freq
-        except:
-            pass
+        if isinstance(freq, compat.string_types):
+            if freq.startswith('period[') or freq.startswith('Period['):
+                m = cls._match.search(freq)
+                if m is not None:
+                    freq = m.group('freq')
+            from pandas.tseries.frequencies import to_offset
+            freq = to_offset(freq)
+            if freq is not None:
+                return freq
+
         raise ValueError("could not construct PeriodDtype")
 
     @classmethod
@@ -342,7 +340,7 @@ def __hash__(self):
 
     def __eq__(self, other):
         if isinstance(other, compat.string_types):
-            return other == self.name
+            return other == self.name or other == self.name.title()
 
         return isinstance(other, PeriodDtype) and self.freq == other.freq
 
@@ -356,11 +354,14 @@ def is_dtype(cls, dtype):
         if isinstance(dtype, compat.string_types):
             # PeriodDtype can be instanciated from freq string like "U",
             # but dosn't regard freq str like "U" as dtype.
-            try:
-                if cls._parse_dtype_strict(dtype) is not None:
-                    return True
-                else:
+            if dtype.startswith('period[') or dtype.startswith('Period['):
+                try:
+                    if cls._parse_dtype_strict(dtype) is not None:
+                        return True
+                    else:
+                        return False
+                except ValueError:
                     return False
-            except ValueError:
+            else:
                 return False
         return super(PeriodDtype, cls).is_dtype(dtype)