[Backport pandas-dev#14452] DOC: updated docstring in .to_datetime() for out-of-bounds timestamps

with errors='ignore'

closes pandas-dev#14448

Author: Keshav Ramaswamy <[email protected]>
Author: Keshav Ramaswamy <[email protected]>

Closes pandas-dev#14452 from keshavramaswamy/master and squashes the following commits:

5468fc5 [Keshav Ramaswamy] added link to timestamp limitations in docstring
3aa78cf [Keshav Ramaswamy] edit docstring to fit python standards
8bfa58e [Keshav Ramaswamy] edited docstring to fit python standards
5ed8ef5 [Keshav Ramaswamy] edut docstring to fit Python Standards
7402de4 [Keshav Ramaswamy] edited docstring to fit python standards
c16ad6b [Keshav Ramaswamy] added timestamp limitations and default behavior to docstring
0db07b5 [Keshav Ramaswamy] updated docstring in .to_datetime()

(cherry picked from commit 18fba53)

Author: keshavramaswamy

pandas/tseries/tools.py

@@ -43,6 +43,7 @@ def _infer(a, b):
                 raise AssertionError('Inputs must both have the same timezone,'
                                      ' {0} != {1}'.format(tz, b.tzinfo))
         return tz
+
     tz = None
     if start is not None:
         tz = _infer(start, end)
@@ -267,10 +268,15 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     1   2016-03-05
     dtype: datetime64[ns]
 
-    If a date that does not meet timestamp limitations, passing errors='coerce'
-    will force to NaT. Furthermore this will force non-dates to NaT as well.
+    If a date does not meet the `timestamp limitations
+    <http://pandas.pydata.org/pandas-docs/stable/timeseries.html
+    #timeseries-timestamp-limits>`_, passing errors='ignore'
+    will return the original input instead of raising any exception.
+
+    Passing errors='coerce' will force an out-of-bounds date to NaT,
+    in addition to forcing non-dates (or non-parseable dates) to NaT.
 
-    >>> pd.to_datetime('13000101', format='%Y%m%d')
+    >>> pd.to_datetime('13000101', format='%Y%m%d', errors='ignore')
     datetime.datetime(1300, 1, 1, 0, 0)
     >>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
     NaT
@@ -423,6 +429,7 @@ def _convert_listlike(arg, box, format, name=None, tz=tz):
 
     return _convert_listlike(np.array([arg]), box, format)[0]
 
+
 # mappings for assembling units
 _unit_map = {'year': 'year',
              'years': 'year',
@@ -555,7 +562,7 @@ def calc_with_mask(carg, mask):
         result = np.empty(carg.shape, dtype='M8[ns]')
         iresult = result.view('i8')
         iresult[~mask] = tslib.iNaT
-        result[mask] = calc(carg[mask].astype(np.float64).astype(np.int64)).\
+        result[mask] = calc(carg[mask].astype(np.float64).astype(np.int64)). \
             astype('M8[ns]')
         return result
 
@@ -640,7 +647,6 @@ def parse_time_string(arg, freq=None, dayfirst=None, yearfirst=None):
 DateParseError = tslib.DateParseError
 normalize_date = tslib.normalize_date
 
-
 # Fixed time formats for time parsing
 _time_formats = ["%H:%M", "%H%M", "%I:%M%p", "%I%M%p",
                  "%H:%M:%S", "%H%M%S", "%I:%M:%S%p", "%I%M%S%p"]
@@ -766,6 +772,7 @@ def format(dt):
     """Returns date in YYYYMMDD format."""
     return dt.strftime('%Y%m%d')
 
+
 OLE_TIME_ZERO = datetime(1899, 12, 30, 0, 0, 0)