ENH: allow construction of datetimes from columns in a DataFrame

closes #8158

Author: Jeff Reback <[email protected]>

Closes #12967 from jreback/dates and squashes the following commits:

e18c9cc [Jeff Reback] TST: move .to_datetime() tests to new testing class
7dc9406 [Jeff Reback] ENH: allow construction of datetimes from columns in a DataFrame

Author: jreback

doc/source/timeseries.rst

@@ -189,9 +189,28 @@ or ``format``, use ``to_datetime`` if these are required.
 
 .. ipython:: python
 
-    to_datetime('2010/11/12')
+    pd.to_datetime('2010/11/12')
 
-    Timestamp('2010/11/12')
+    pd.Timestamp('2010/11/12')
+
+.. versionadded:: 0.18.1
+
+You can also pass a ``DataFrame`` of integer or string columns to assemble into a ``Series`` of ``Timestamps``.
+
+.. ipython:: python
+
+   df = pd.pd.DataFrame({'year': [2015, 2016],
+                         'month': [2, 3],
+                         'day': [4, 5],
+                         'hour': [2, 3]})
+   pd.to_datetime(df)
+
+
+You can pass only the columns that you need to assemble.
+
+.. ipython:: python
+
+   pd.to_datetime(df[['year', 'month', 'day']])
 
 
 Invalid Data

doc/source/whatsnew/v0.18.1.txt

@@ -120,6 +120,24 @@ Partial string indexing now matches on ``DateTimeIndex`` when part of a ``MultiI
    dft2 = dft2.swaplevel(0, 1).sort_index()
    dft2.loc[idx[:, '2013-01-05'], :]
 
+.. _whatsnew_0181.enhancements.assembling:
+
+Assembling Datetimes
+^^^^^^^^^^^^^^^^^^^^
+
+``pd.to_datetime()`` has gained the ability to assemble datetimes from a passed in ``DataFrame`` or a dict. (:issue:`8158`).
+
+.. ipython:: python
+
+   df = pd.DataFrame({'year': [2015, 2016],
+                      'month': [2, 3],
+                      'day': [4, 5],
+                      'hour': [2, 3]})
+   pd.to_datetime(df)
+
+   # pass only the columns that you need to assemble
+   pd.to_datetime(df[['year', 'month', 'day']])
+
 .. _whatsnew_0181.other:
 
 Other Enhancements

pandas/tseries/tests/test_period.py

@@ -3144,16 +3144,6 @@ def test_to_datetime_1703(self):
         result = index.to_datetime()
         self.assertEqual(result[0], Timestamp('1/1/2012'))
 
-    def test_to_datetime_dimensions(self):
-        # GH 11776
-        df = DataFrame({'a': ['1/1/2012', '1/2/2012'],
-                        'b': ['12/30/2012', '12/31/2012']})
-        with tm.assertRaisesRegexp(TypeError, "1-d array"):
-            to_datetime(df)
-        for errors in ['ignore', 'raise', 'coerce']:
-            with tm.assertRaisesRegexp(TypeError, "1-d array"):
-                to_datetime(df, errors=errors)
-
     def test_get_loc_msg(self):
         idx = period_range('2000-1-1', freq='A', periods=10)
         bad_period = Period('2012', 'A')