Fix docstring; add tests for kwargs

Author: thejohnfreeman

pandas/tseries/tests/test_tslib.py

@@ -204,6 +204,39 @@ def test_constructor_positional(self):
         self.assertEqual(Timestamp(*pos_args).to_pydatetime(),
                          datetime.datetime(*pos_args))
 
+    def test_constructor_keyword(self):
+        # GH 10758
+        with tm.assertRaises(TypeError):
+            Timestamp(year=2000, month=1)
+        with tm.assertRaises(ValueError):
+            Timestamp(year=2000, month=0, day=1)
+        with tm.assertRaises(ValueError):
+            Timestamp(year=2000, month=13, day=1)
+        with tm.assertRaises(ValueError):
+            Timestamp(year=2000, month=1, day=0)
+        with tm.assertRaises(ValueError):
+            Timestamp(year=2000, month=1, day=32)
+
+        ts = Timestamp(year=2000, month=1, day=2)
+
+        actual = ts.to_pydatetime()
+        expected = datetime.datetime(year=2000, month=1, day=2)
+        self.assertEqual(actual, expected)
+        self.assertEqual(type(actual), type(expected))
+
+        pos_args = [2000, 1, 2, 3, 4, 5, 999999]
+        kw_args = {
+                'year': 2000,
+                'month': 1,
+                'day': 2,
+                'hour': 3,
+                'minute': 4,
+                'second': 5,
+                'microsecond': 999999,
+                }
+        self.assertEqual(Timestamp(**kw_args).to_pydatetime(),
+                         datetime.datetime(**kw_args))
+
     def test_conversion(self):
         # GH 9255
         ts = Timestamp('2000-01-01')

pandas/tslib.pyx

@@ -225,8 +225,12 @@ class Timestamp(_Timestamp):
     for the entries that make up a DatetimeIndex, and other timeseries
     oriented data structures in pandas.
 
-    Parameters
-    ----------
+    There are essentially three calling conventions for the constructor. The
+    first, legacy form accepts four parameters. They can be passed by
+    position or keyword.
+
+    Legacy Parameters
+    -----------------
     ts_input : datetime-like, str, int, float
         Value to be converted to Timestamp
     offset : str, DateOffset
@@ -235,6 +239,20 @@ class Timestamp(_Timestamp):
         Time zone for time which Timestamp will have.
     unit : string
         numpy unit used for conversion, if ts_input is int or float
+
+    The other two forms copy the parameters from datetime.datetime. They can
+    be passed by either position or keyword, but not both mixed together.
+
+    datetime.datetime Parameters
+    ------------------------------
+    year : int
+    month : int
+    day : int
+    hour : int [optional]
+    minute : int [optional]
+    second : int [optional]
+    microsecond : int [optional]
+    tzinfo : datetime.tzinfo [optional]
     """
 
     @classmethod
@@ -319,7 +337,7 @@ class Timestamp(_Timestamp):
             return Timestamp(datetime(year, month, day, hour or 0,
                 minute or 0, second or 0, microsecond or 0, tzinfo),
                 tz=tzinfo)
-        if is_integer_object(offset):
+        elif is_integer_object(offset):
             # User passed positional arguments:
             #   Timestamp(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
             return Timestamp(datetime(ts_input, offset, tz, unit or 0,