API/COMPAT: add pydatetime-style positional args to Timestamp constructor

Author: thejohnfreeman

doc/source/timeseries.rst

@@ -98,6 +98,7 @@ time.
 
    pd.Timestamp(datetime(2012, 5, 1))
    pd.Timestamp('2012-05-01')
+   pd.Timestamp(2012, 5, 1)
 
 However, in many cases it is more natural to associate things like change
 variables with a time span instead. The span represented by ``Period`` can be

doc/source/whatsnew/v0.18.2.txt

@@ -38,6 +38,14 @@ Other enhancements
      idx = pd.Index(["a1a2", "b1", "c1"])
      idx.str.extractall("[ab](?P<digit>\d)")
 
+- ``Timestamp``s can now accept positional parameters like :func:`datetime.datetime`:
+
+  .. ipython:: python
+
+    Timestamp(2012, 1, 1)
+
+    Timestamp(2012, 1, 1, 8, 30)
+
 .. _whatsnew_0182.api:
 
 API changes

pandas/tseries/tests/test_tslib.py

@@ -180,6 +180,36 @@ def test_constructor_invalid(self):
         with tm.assertRaisesRegexp(ValueError, 'Cannot convert Period'):
             Timestamp(Period('1000-01-01'))
 
+    def test_constructor_positional(self):
+        # GH 10758
+        with tm.assertRaises(TypeError):
+            Timestamp(2000, 1)
+        with tm.assertRaises(ValueError):
+            Timestamp(2000, 0, 1)
+        with tm.assertRaises(ValueError):
+            Timestamp(2000, 13, 1)
+        with tm.assertRaises(ValueError):
+            Timestamp(2000, 1, 0)
+        with tm.assertRaises(ValueError):
+            Timestamp(2000, 1, 32)
+        with tm.assertRaises(TypeError):
+            Timestamp(2000, 1, 1, None)
+        with tm.assertRaises(TypeError):
+            Timestamp(2000, 1, 1, None, None)
+        with tm.assertRaises(TypeError):
+            Timestamp(2000, 1, 1, None, None, None)
+
+        ts = Timestamp(2000, 1, 2)
+
+        actual = ts.to_pydatetime()
+        expected = datetime.datetime(2000, 1, 2)
+        self.assertEqual(actual, expected)
+        self.assertEqual(type(actual), type(expected))
+
+        pos_args = [2000, 1, 2, 3, 4, 5, 999999]
+        self.assertEqual(Timestamp(*pos_args).to_pydatetime(),
+                         datetime.datetime(*pos_args))
+
     def test_conversion(self):
         # GH 9255
         ts = Timestamp('2000-01-01')

pandas/tslib.pyx

@@ -216,6 +216,7 @@ cdef inline bint _is_fixed_offset(object tz):
 
 
 _zero_time = datetime_time(0, 0)
+_no_unit = object()
 
 # Python front end to C extension type _Timestamp
 # This serves as the box for datetime64
@@ -288,10 +289,36 @@ class Timestamp(_Timestamp):
     def combine(cls, date, time):
         return cls(datetime.combine(date, time))
 
-    def __new__(cls, object ts_input, object offset=None, tz=None, unit=None):
+    def __new__(cls,
+            object ts_input, object offset=None, tz=None, unit=_no_unit,
+            minute=0, second=0, microsecond=0, tzinfo=None):
+        # The parameter list folds together legacy parameter names (the first
+        # four) and positional parameter names from pydatetime (starting with
+        # `minute`).
+        #
+        # When using the pydatetime form, the first three parameters are
+        # required, but the fourth (called `unit` but standing in for `hour`)
+        # is optional. However, when using the legacy form, only the first
+        # parameter is required and the fourth parameter defaults to `None`.
+        # We use a special non-`None` constant to distinguish when callers
+        # pass `None` as the fourth pydatetime parameter.
+
         cdef _TSObject ts
         cdef _Timestamp ts_base
 
+        if offset is not None and is_integer_object(offset):
+            # User passed positional arguments:
+            #   Timestamp(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
+            # When using the positional form, the first three parameters are
+            # required. Assign defaults to the rest.
+            if unit is _no_unit:
+                unit = 0
+            # Forward positional arguments to datetime constructor.
+            return Timestamp(datetime(ts_input, offset, tz, unit, minute, second, microsecond, tzinfo),
+                             tz=tzinfo)
+        elif unit is _no_unit:
+            unit = None
+
         ts = convert_to_tsobject(ts_input, tz, unit, 0, 0)
 
         if ts.value == NPY_NAT: