ENH: TimedeltaIndex and Timedelta scalar support (GH3009)

BUG: coercion of timedeltas in assignment (GH8209)

COMPAT: provide conversion for passing in non-ns datetime64/timedelta64

BUG: diff on Dataframe with timedelta64 broken (GH4533)

ENH: support for alternate Timedelta format constructors in natural language (GH8190)

BUG: handle empty timedelta64[ns] Series with ops (GH7869)

Author: jreback

doc/source/api.rst

@@ -146,8 +146,8 @@ Top-level missing data
    isnull
    notnull
 
-Top-level dealing with datetimes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Top-level dealing with datetimelike
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autosummary::
    :toctree: generated/
@@ -157,6 +157,7 @@ Top-level dealing with datetimes
    date_range
    bdate_range
    period_range
+   timedelta_range
 
 Top-level evaluation
 ~~~~~~~~~~~~~~~~~~~~
@@ -440,13 +441,16 @@ Time series-related
 
 Datetimelike Properties
 ~~~~~~~~~~~~~~~~~~~~~~~
+
 ``Series.dt`` can be used to access the values of the series as
 datetimelike and return several properties.
 Due to implementation details the methods show up here as methods of the
-``DatetimeProperties/PeriodProperties`` classes. These can be accessed like ``Series.dt.<property>``.
+``DatetimeProperties/PeriodProperties/TimedeltaProperties`` classes. These can be accessed like ``Series.dt.<property>``.
 
 .. currentmodule:: pandas.tseries.common
 
+**Datetime Properties**
+
 .. autosummary::
    :toctree: generated/
 
@@ -473,6 +477,37 @@ Due to implementation details the methods show up here as methods of the
    DatetimeProperties.is_year_start
    DatetimeProperties.is_year_end
 
+**Datetime Methods**
+
+.. autosummary::
+   :toctree: generated/
+
+   DatetimeProperties.to_period
+   DatetimeProperties.to_pydatetime
+   DatetimeProperties.tz_localize
+   DatetimeProperties.tz_convert
+
+**Timedelta Properties**
+
+.. autosummary::
+   :toctree: generated/
+
+   TimedeltaProperties.days
+   TimedeltaProperties.hours
+   TimedeltaProperties.minutes
+   TimedeltaProperties.seconds
+   TimedeltaProperties.milliseconds
+   TimedeltaProperties.microseconds
+   TimedeltaProperties.nanoseconds
+   TimedeltaProperties.components
+
+**Timedelta Methods**
+
+.. autosummary::
+   :toctree: generated/
+
+   TimedeltaProperties.to_pytimedelta
+
 String handling
 ~~~~~~~~~~~~~~~
 ``Series.str`` can be used to access the values of the series as
@@ -1289,6 +1324,37 @@ Conversion
    DatetimeIndex.to_pydatetime
    DatetimeIndex.to_series
 
+TimedeltaIndex
+--------------
+
+.. autosummary::
+   :toctree: generated/
+
+   TimedeltaIndex
+
+Components
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   TimedeltaIndex.days
+   TimedeltaIndex.hours
+   TimedeltaIndex.minutes
+   TimedeltaIndex.seconds
+   TimedeltaIndex.milliseconds
+   TimedeltaIndex.microseconds
+   TimedeltaIndex.nanoseconds
+   TimedeltaIndex.components
+
+Conversion
+~~~~~~~~~~
+.. autosummary::
+   :toctree: generated/
+
+   TimedeltaIndex.to_pytimedelta
+   TimedeltaIndex.to_series
+
 GroupBy
 -------
 .. currentmodule:: pandas.core.groupby

doc/source/basics.rst

@@ -1122,6 +1122,16 @@ This enables nice expressions like this:
 
    s[s.dt.day==2]
 
+You can easily produces tz aware transformations:
+
+.. ipython:: python
+
+   stz = s.dt.tz_localize('US/Eastern')
+   stz
+   stz.dt.tz
+
+The ``.dt`` accessor works for period and timedelta dtypes.
+
 .. ipython:: python
 
    # period
@@ -1130,6 +1140,15 @@ This enables nice expressions like this:
    s.dt.year
    s.dt.day
 
+.. ipython:: python
+
+   # timedelta
+   s = Series(timedelta_range('1 day 00:00:05',periods=4,freq='s'))
+   s
+   s.dt.days
+   s.dt.seconds
+   s.dt.components
+
 .. note::
 
    ``Series.dt`` will raise a ``TypeError`` if you access with a non-datetimelike values

doc/source/cookbook.rst

@@ -636,7 +636,7 @@ Computation
 Miscellaneous
 -------------
 
-The :ref:`Timedeltas <timeseries.timedeltas>` docs.
+The :ref:`Timedeltas <timedeltas.timedeltas>` docs.
 
 `Operating with timedeltas
 <http://github.com/pydata/pandas/pull/2899>`__

doc/source/index.rst.template

@@ -131,6 +131,7 @@ See the package overview for more detail about what's in the library.
     merging
     reshaping
     timeseries
+    timedeltas
     categorical
     visualization
     rplot

doc/source/internals.rst

@@ -36,7 +36,8 @@ containers for the axis labels:
   data, such as time stamps
 - ``Float64Index``: a version of ``Index`` highly optimized for 64-bit float data
 - ``MultiIndex``: the standard hierarchical index object
-- ``DatetimeIndex``: An Index object with Timestamp elements
+- ``DatetimeIndex``: An Index object with ``Timestamp`` boxed elements (impl are the int64 values)
+- ``TimedeltaIndex``: An Index object with ``Timedelta`` boxed elements (impl are the in64 values)
 - ``PeriodIndex``: An Index object with Period elements
 
 These are range generates to make the creation of a regular index easy: