Merge pull request #9189 from vfilimonov/doc_to_datetime

Docstring: pd.to_datetime (issue #9107)

Author: shoyer

pandas/tseries/tools.py

@@ -200,6 +200,8 @@ def to_datetime(arg, errors='ignore', dayfirst=False, utc=None, box=True,
         If True, require an exact format match.
         If False, allow the format to match anywhere in the target string.
     coerce : force errors to NaT (False by default)
+        Timestamps outside the interval between Timestamp.min and Timestamp.max
+        (approximately 1677-09-22 to 2262-04-11) will be also forced to NaT.
     unit : unit of the arg (D,s,ms,us,ns) denote the unit in epoch
         (e.g. a unix timestamp), which is an integer/float number
     infer_datetime_format : boolean, default False
@@ -212,6 +214,9 @@ def to_datetime(arg, errors='ignore', dayfirst=False, utc=None, box=True,
         - list-like: DatetimeIndex
         - Series: Series of datetime64 dtype
         - scalar: Timestamp
+        In case when it is not possible to return designated types (e.g. when
+        any element of input is before Timestamp.min or after Timestamp.max)
+        return will have datetime.datetime type (or correspoding array/Series).
 
     Examples
     --------
@@ -221,11 +226,30 @@ def to_datetime(arg, errors='ignore', dayfirst=False, utc=None, box=True,
     >>> i = pd.date_range('20000101',periods=100)
     >>> df = pd.DataFrame(dict(year = i.year, month = i.month, day = i.day))
     >>> pd.to_datetime(df.year*10000 + df.month*100 + df.day, format='%Y%m%d')
+    0    2000-01-01
+    1    2000-01-02
+    ...
+    98   2000-04-08
+    99   2000-04-09
+    Length: 100, dtype: datetime64[ns]
 
     Or from strings
 
     >>> df = df.astype(str)
     >>> pd.to_datetime(df.day + df.month + df.year, format="%d%m%Y")
+    0    2000-01-01
+    1    2000-01-02
+    ...
+    98   2000-04-08
+    99   2000-04-09
+    Length: 100, dtype: datetime64[ns]
+
+    Date that does not meet timestamp limitations:
+
+    >>> pd.to_datetime('13000101', format='%Y%m%d')
+    datetime.datetime(1300, 1, 1, 0, 0)
+    >>> pd.to_datetime('13000101', format='%Y%m%d', coerce=True)
+    NaT
     """
     from pandas import Timestamp
     from pandas.core.series import Series