ENH: support .strftime for datetimelikes (closes #10086)

Author: mortada

doc/source/api.rst

@@ -498,6 +498,7 @@ These can be accessed like ``Series.dt.<property>``.
    Series.dt.tz_localize
    Series.dt.tz_convert
    Series.dt.normalize
+   Series.dt.strftime
 
 **Timedelta Properties**
 

doc/source/basics.rst

@@ -1132,13 +1132,13 @@ For instance,
 ~~~~~~~~~~~~
 
 ``Series`` has an accessor to succinctly return datetime like properties for the
-*values* of the Series, if its a datetime/period like Series.
+*values* of the Series, if it is a datetime/period like Series.
 This will return a Series, indexed like the existing Series.
 
 .. ipython:: python
 
    # datetime
-   s = pd.Series(pd.date_range('20130101 09:10:12',periods=4))
+   s = pd.Series(pd.date_range('20130101 09:10:12', periods=4))
    s
    s.dt.hour
    s.dt.second
@@ -1164,20 +1164,36 @@ You can also chain these types of operations:
 
    s.dt.tz_localize('UTC').dt.tz_convert('US/Eastern')
 
+You can also format the datetime values with ``Series.dt.strftime``:
+
+.. ipython:: python
+
+   # DatetimeIndex
+   s = Series(date_range('20130101', periods=4))
+   s
+   s.dt.strftime('%Y/%m/%d')
+
+.. ipython:: python
+
+   # PeriodIndex
+   s = Series(period_range('20130101', periods=4))
+   s
+   s.dt.strftime('%Y/%m/%d')
+
 The ``.dt`` accessor works for period and timedelta dtypes.
 
 .. ipython:: python
 
    # period
-   s = pd.Series(pd.period_range('20130101', periods=4,freq='D'))
+   s = pd.Series(pd.period_range('20130101', periods=4, freq='D'))
    s
    s.dt.year
    s.dt.day
 
 .. ipython:: python
 
    # timedelta
-   s = pd.Series(pd.timedelta_range('1 day 00:00:05',periods=4,freq='s'))
+   s = pd.Series(pd.timedelta_range('1 day 00:00:05', periods=4, freq='s'))
    s
    s.dt.days
    s.dt.seconds

pandas/tests/test_series.py

@@ -81,9 +81,10 @@ def test_dt_namespace_accessor(self):
 
         ok_for_base = ['year','month','day','hour','minute','second','weekofyear','week','dayofweek','weekday','dayofyear','quarter','freq','days_in_month','daysinmonth']
         ok_for_period = ok_for_base + ['qyear']
+        ok_for_period_methods = ['strftime']
         ok_for_dt = ok_for_base + ['date','time','microsecond','nanosecond', 'is_month_start', 'is_month_end', 'is_quarter_start',
                                    'is_quarter_end', 'is_year_start', 'is_year_end', 'tz']
-        ok_for_dt_methods = ['to_period','to_pydatetime','tz_localize','tz_convert', 'normalize']
+        ok_for_dt_methods = ['to_period','to_pydatetime','tz_localize','tz_convert', 'normalize', 'strftime']
         ok_for_td = ['days','seconds','microseconds','nanoseconds']
         ok_for_td_methods = ['components','to_pytimedelta']
 
@@ -109,13 +110,12 @@ def compare(s, name):
                   Series(date_range('20130101',periods=5,freq='s')),
                   Series(date_range('20130101 00:00:00',periods=5,freq='ms'))]:
             for prop in ok_for_dt:
-
                 # we test freq below
                 if prop != 'freq':
                     compare(s, prop)
 
             for prop in ok_for_dt_methods:
-                getattr(s.dt,prop)
+                getattr(s.dt, prop)
 
             result = s.dt.to_pydatetime()
             self.assertIsInstance(result,np.ndarray)
@@ -140,13 +140,12 @@ def compare(s, name):
                   Series(timedelta_range('1 day 01:23:45',periods=5,freq='s')),
                   Series(timedelta_range('2 days 01:23:45.012345',periods=5,freq='ms'))]:
             for prop in ok_for_td:
-
                 # we test freq below
                 if prop != 'freq':
                     compare(s, prop)
 
             for prop in ok_for_td_methods:
-                getattr(s.dt,prop)
+                getattr(s.dt, prop)
 
             result = s.dt.components
             self.assertIsInstance(result,DataFrame)
@@ -169,13 +168,14 @@ def compare(s, name):
 
         # periodindex
         for s in [Series(period_range('20130101',periods=5,freq='D'))]:
-
             for prop in ok_for_period:
-
                 # we test freq below
                 if prop != 'freq':
                     compare(s, prop)
 
+            for prop in ok_for_period_methods:
+                getattr(s.dt, prop)
+
             freq_result = s.dt.freq
             self.assertEqual(freq_result, PeriodIndex(s.values).freq)
 
@@ -190,7 +190,7 @@ def get_dir(s):
 
         s = Series(period_range('20130101',periods=5,freq='D').asobject)
         results = get_dir(s)
-        tm.assert_almost_equal(results,list(sorted(set(ok_for_period))))
+        tm.assert_almost_equal(results, list(sorted(set(ok_for_period + ok_for_period_methods))))
 
         # no setting allowed
         s = Series(date_range('20130101',periods=5,freq='D'))
@@ -203,6 +203,28 @@ def f():
                 s.dt.hour[0] = 5
             self.assertRaises(com.SettingWithCopyError, f)
 
+    def test_strftime(self):
+        # GH 10086
+        s = Series(date_range('20130101', periods=5))
+        result = s.dt.strftime('%Y/%m/%d')
+        expected = Series(['2013/01/01', '2013/01/02', '2013/01/03', '2013/01/04', '2013/01/05'])
+        tm.assert_series_equal(result, expected)
+
+        s.iloc[0] = pd.NaT
+        result = s.dt.strftime('%Y/%m/%d')
+        expected = Series(['NaT', '2013/01/02', '2013/01/03', '2013/01/04', '2013/01/05'])
+        tm.assert_series_equal(result, expected)
+
+        datetime_index = date_range('20150301', periods=5)
+        result = datetime_index.strftime("%Y/%m/%d")
+        expected = ['2015/03/01', '2015/03/02', '2015/03/03', '2015/03/04', '2015/03/05']
+        self.assertEqual(result, expected)
+
+        period_index = period_range('20150301', periods=5)
+        result = period_index.strftime("%Y/%m/%d")
+        expected = ['2015/03/01', '2015/03/02', '2015/03/03', '2015/03/04', '2015/03/05']
+        self.assertEqual(result, expected)
+
     def test_valid_dt_with_missing_values(self):
 
         from datetime import date, time

pandas/tseries/base.py

@@ -17,6 +17,26 @@
 import pandas.algos as _algos
 
 
+
+class DatelikeOps(object):
+    """ common ops for DatetimeIndex/PeriodIndex, but not TimedeltaIndex """
+
+    def strftime(self, date_format):
+        """
+        Return a list of formmatted strings specified by date_format
+
+        Parameters
+        ----------
+        date_format : str
+            date format string (e.g. "%Y-%m-%d")
+
+        Returns
+        -------
+        a list formatted strings
+        """
+        return self.format(date_format=date_format)
+
+
 class DatetimeIndexOpsMixin(object):
     """ common ops mixin to support a unified inteface datetimelike Index """
 

pandas/tseries/common.py

@@ -125,7 +125,7 @@ def to_pydatetime(self):
                                            accessors=DatetimeIndex._datetimelike_ops,
                                            typ='property')
 DatetimeProperties._add_delegate_accessors(delegate=DatetimeIndex,
-                                           accessors=["to_period","tz_localize","tz_convert","normalize"],
+                                           accessors=["to_period","tz_localize","tz_convert","normalize","strftime"],
                                            typ='method')
 
 class TimedeltaProperties(Properties):
@@ -181,6 +181,9 @@ class PeriodProperties(Properties):
 PeriodProperties._add_delegate_accessors(delegate=PeriodIndex,
                                          accessors=PeriodIndex._datetimelike_ops,
                                          typ='property')
+PeriodProperties._add_delegate_accessors(delegate=PeriodIndex,
+                                         accessors=["strftime"],
+                                         typ='method')
 
 
 class CombinedDatetimelikeProperties(DatetimeProperties, TimedeltaProperties):

pandas/tseries/index.py

@@ -12,7 +12,7 @@
 from pandas.tseries.frequencies import (
     to_offset, get_period_alias,
     Resolution)
-from pandas.tseries.base import DatetimeIndexOpsMixin
+from pandas.tseries.base import DatelikeOps, DatetimeIndexOpsMixin
 from pandas.tseries.offsets import DateOffset, generate_range, Tick, CDay
 from pandas.tseries.tools import parse_time_string, normalize_date
 from pandas.util.decorators import cache_readonly, deprecate_kwarg
@@ -116,7 +116,7 @@ def _new_DatetimeIndex(cls, d):
     result.tz = tz
     return result
 
-class DatetimeIndex(DatetimeIndexOpsMixin, Int64Index):
+class DatetimeIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index):
     """
     Immutable ndarray of datetime64 data, represented internally as int64, and
     which can be boxed to Timestamp objects that are subclasses of datetime and

pandas/tseries/period.py

@@ -4,7 +4,7 @@
 import pandas.tseries.frequencies as frequencies
 from pandas.tseries.frequencies import get_freq_code as _gfc
 from pandas.tseries.index import DatetimeIndex, Int64Index, Index
-from pandas.tseries.base import DatetimeIndexOpsMixin
+from pandas.tseries.base import DatelikeOps, DatetimeIndexOpsMixin
 from pandas.tseries.tools import parse_time_string
 import pandas.tseries.offsets as offsets
 
@@ -92,7 +92,7 @@ def wrapper(self, other):
     return wrapper
 
 
-class PeriodIndex(DatetimeIndexOpsMixin, Int64Index):
+class PeriodIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index):
     """
     Immutable ndarray holding ordinal values indicating regular periods in
     time such as particular years, quarters, months, etc. A value of 1 is the
@@ -717,14 +717,17 @@ def __getitem__(self, key):
 
             return PeriodIndex(result, name=self.name, freq=self.freq)
 
-    def _format_native_types(self, na_rep=u('NaT'), **kwargs):
+    def _format_native_types(self, na_rep=u('NaT'), date_format=None, **kwargs):
 
         values = np.array(list(self), dtype=object)
         mask = isnull(self.values)
         values[mask] = na_rep
-
         imask = ~mask
-        values[imask] = np.array([u('%s') % dt for dt in values[imask]])
+
+        if date_format is None:
+            values[imask] = np.array([u('%s') % dt for dt in values[imask]])
+        else:
+            values[imask] = np.array([dt.strftime(date_format) for dt in values[imask]])
         return values
 
     def __array_finalize__(self, obj):