update docs / tests

Author: jreback

doc/source/timeseries.rst

@@ -276,6 +276,24 @@ These *work*, but the results may be unexpected.
 
    Epoch times will be rounded to the nearest nanosecond.
 
+Using the Origin Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.20.0
+
+Using the ``origin`` parameter, one can specify an alternative starting point for creation
+of a ``DatetimeIndex``.
+
+.. ipython:: python
+
+   pd.to_datetime([1, 2, 3], unit='D', origin=pd.Timestamp('1960-01-01'))
+
+The default is set at ``origin='epoch'``, which defaults to ``1970-01-01 00:00:00``.
+
+.. ipython:: python
+
+   pd.to_datetime([1, 2, 3], unit='D')
+
 .. _timeseries.daterange:
 
 Generating Ranges of Timestamps

doc/source/whatsnew/v0.20.0.txt

@@ -56,16 +56,21 @@ fixed-width text files, and :func:`read_excel` for parsing Excel files.
 
 .. _whatsnew_0120.enhancements.datetime_origin:
 
-to_datetime can be used with Offset
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+to_datetime has gained an origin parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 ``pd.to_datetime`` has gained a new parameter, ``origin``, to define an offset
 from where to compute the resulting ``DatetimeIndex``. (:issue:`11276`, :issue:`11745`)
 
 .. ipython:: python
 
-   to_datetime([1,2,3], unit='D', origin=pd.Timestamp('1960-01-01'))
+   pd.to_datetime([1, 2, 3], unit='D', origin=pd.Timestamp('1960-01-01'))
+
+The default is set at ``origin='epoch'``, which defaults to ``1970-01-01 00:00:00``.
+
+.. ipython:: python
 
-The above code would return days with offset from origin as defined by timestamp set by origin.
+   pd.to_datetime([1, 2, 3], unit='D')
 
 .. _whatsnew_0200.enhancements.groupby_access:
 

pandas/tests/indexes/datetimes/test_tools.py

@@ -1517,45 +1517,68 @@ def test_normalize_date():
     assert (result == datetime(2012, 9, 7))
 
 
-def test_to_datetime_origin():
-    units = ['D', 's', 'ms', 'us', 'ns']
-    # gh-11276, gh-11745
-    # for origin as julian
-
-    julian_dates = pd.date_range(
-        '2014-1-1', periods=10).to_julian_date().values
-    result = Series(pd.to_datetime(
-        julian_dates, unit='D', origin='julian'))
-    expected = Series(pd.to_datetime(
-        julian_dates - pd.Timestamp(0).to_julian_date(), unit='D'))
-    assert_series_equal(result, expected)
-
-    # checking for invalid combination of origin='julian' and unit != D
-    for unit in units:
-        if unit == 'D':
-            continue
-        with pytest.raises(ValueError):
-            pd.to_datetime(julian_dates, unit=unit, origin='julian')
+@pytest.fixture(params=['D', 's', 'ms', 'us', 'ns'])
+def units(request):
+    return request.param
+
 
+@pytest.fixture
+def epoch_1960():
     # for origin as 1960-01-01
-    epoch_1960 = pd.Timestamp('1960-01-01')
-    epoch_timestamp_convertible = [epoch_1960, epoch_1960.to_datetime(),
-                                   epoch_1960.to_datetime64(),
-                                   str(epoch_1960)]
-    invalid_origins = ['random_string', '13-24-1990', '0001-01-01']
-    units_from_epoch = [0, 1, 2, 3, 4]
-
-    for unit in units:
-        for epoch in epoch_timestamp_convertible:
-            expected = Series(
-                [pd.Timedelta(x, unit=unit) +
-                 epoch_1960 for x in units_from_epoch])
-            result = Series(pd.to_datetime(
-                units_from_epoch, unit=unit, origin=epoch))
-            assert_series_equal(result, expected)
+    return Timestamp('1960-01-01')
+
+
+@pytest.fixture
+def units_from_epochs():
+    return list(range(5))
+
+
+@pytest.fixture(params=[epoch_1960(), epoch_1960().to_datetime(),
+                        epoch_1960().to_datetime64(),
+                        str(epoch_1960())])
+def epochs(request):
+    return request.param
+
+
+@pytest.fixture
+def julian_dates():
+    return pd.date_range('2014-1-1', periods=10).to_julian_date().values
+
+
+class TestOrigin(object):
 
-        # check for invalid origins
-        for origin in invalid_origins:
+    def test_to_basic(self, julian_dates):
+        # gh-11276, gh-11745
+        # for origin as julian
+
+        result = Series(pd.to_datetime(
+            julian_dates, unit='D', origin='julian'))
+        expected = Series(pd.to_datetime(
+            julian_dates - pd.Timestamp(0).to_julian_date(), unit='D'))
+        assert_series_equal(result, expected)
+
+    def test_invalid_unit(self, units, julian_dates):
+
+        # checking for invalid combination of origin='julian' and unit != D
+        if units != 'D':
             with pytest.raises(ValueError):
-                pd.to_datetime(units_from_epoch, unit=unit,
-                               origin=origin)
+                pd.to_datetime(julian_dates, unit=units, origin='julian')
+
+    def test_epoch(self, units, epochs, epoch_1960, units_from_epochs):
+
+        expected = Series(
+            [pd.Timedelta(x, unit=units) +
+             epoch_1960 for x in units_from_epochs])
+        result = Series(pd.to_datetime(
+            units_from_epochs, unit=units, origin=epochs))
+        assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize("origin",
+                             ['random_string',
+                              '13-24-1990',
+                              '0001-01-01'])
+    def test_invalid_origins(self, origin, units, units_from_epochs):
+
+        with pytest.raises(ValueError):
+            pd.to_datetime(units_from_epochs, unit=units,
+                           origin=origin)

pandas/tseries/tools.py

@@ -176,7 +176,7 @@ def _guess_datetime_format_for_array(arr, **kwargs):
 
 
 def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
-                utc=None, box=True, format=None, exact=True, coerce=None,
+                utc=None, box=True, format=None, exact=True,
                 unit=None, infer_datetime_format=False, origin='epoch'):
     """
     Convert argument to datetime.
@@ -248,7 +248,7 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
         - If Timestamp convertible, origin is set to Timestamp identified by
           origin.
 
-        .. versionadded: 0.19.0
+        .. versionadded: 0.20.0
 
     Returns
     -------
@@ -311,7 +311,6 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     1 loop, best of 3: 471 ms per loop
 
     Using non-epoch origins to parse date
-
     >>> pd.to_datetime([1,2,3], unit='D', origin=pd.Timestamp('1960-01-01'))
     0    1960-01-02
     1    1960-01-03
@@ -428,42 +427,42 @@ def _convert_listlike(arg, box, format, name=None, tz=tz):
             except (ValueError, TypeError):
                 raise e
 
-    def intermediate_result(arg):
-        if origin == 'julian':
-            if unit != 'D':
-                raise ValueError("unit must be 'D' for origin='julian'")
-            try:
-                arg = arg - tslib.Timestamp(0).to_julian_date()
-            except:
-                raise ValueError("incompatible 'arg' type for given "
-                                 "'origin'='julian'")
-        if arg is None:
-            return arg
-        elif isinstance(arg, tslib.Timestamp):
-            return arg
-        elif isinstance(arg, ABCSeries):
-            from pandas import Series
-            values = _convert_listlike(arg._values, False, format)
-            return Series(values, index=arg.index, name=arg.name)
-        elif isinstance(arg, (ABCDataFrame, MutableMapping)):
-            return _assemble_from_unit_mappings(arg, errors=errors)
-        elif isinstance(arg, ABCIndexClass):
-            return _convert_listlike(arg, box, format, name=arg.name)
-        elif is_list_like(arg):
-            return _convert_listlike(arg, box, format)
-        return _convert_listlike(np.array([arg]), box, format)[0]
-
-    result = intermediate_result(arg)
-
-    offset = None
+    # perform the conversion
+    if origin == 'julian':
+        if unit != 'D':
+            raise ValueError("unit must be 'D' for origin='julian'")
+        try:
+            arg = arg - tslib.Timestamp(0).to_julian_date()
+        except:
+            raise ValueError("incompatible 'arg' type for given "
+                             "'origin'='julian'")
+    if arg is None:
+        result = arg
+    elif isinstance(arg, tslib.Timestamp):
+        result = arg
+    elif isinstance(arg, ABCSeries):
+        from pandas import Series
+        values = _convert_listlike(arg._values, False, format)
+        result = Series(values, index=arg.index, name=arg.name)
+    elif isinstance(arg, (ABCDataFrame, MutableMapping)):
+        result = _assemble_from_unit_mappings(arg, errors=errors)
+    elif isinstance(arg, ABCIndexClass):
+        result = _convert_listlike(arg, box, format, name=arg.name)
+    elif is_list_like(arg):
+        result =  _convert_listlike(arg, box, format)
+    else:
+        result = _convert_listlike(np.array([arg]), box, format)[0]
+
+    # handle origin
     if origin not in ['epoch', 'julian']:
         try:
             offset = tslib.Timestamp(origin) - tslib.Timestamp(0)
         except ValueError:
-            raise ValueError("Invalid 'origin' or 'origin' Out of Bound")
+            raise ValueError("Invalid 'origin' or 'origin' Out of Bounds")
+
+        if offset is not None:
+            result = result + offset
 
-    if offset is not None:
-        result = result + offset
     return result