DOC: timeseries.rst floating point precision (pandas-dev#15817)

Author: mchwalisz

doc/source/timeseries.rst

@@ -265,17 +265,34 @@ Typical epoch stored units
    pd.to_datetime([1349720105100, 1349720105200, 1349720105300,
                    1349720105400, 1349720105500 ], unit='ms')
 
-These *work*, but the results may be unexpected.
+.. note::
 
-.. ipython:: python
+   Epoch times will be rounded to the nearest nanosecond.
+
+.. warning::
+
+   Conversion of float epoch times can lead to inaccurate and unexpected results.
+   Python floats are unbounded precision, with about 15 significant digits (depends on
+   operating system). Rounding in conversion from to high precision ``Timestamp`` is
+   unavoidable. The only way to have exact precision is to use a fixed-width exact type
+   (e.g. an int64).
 
-   pd.to_datetime([1])
+   .. ipython:: python
 
-   pd.to_datetime([1, 3.14], unit='s')
+      1490195805.433502912
+      pd.to_datetime([1490195805.433, 1490195805.433502912], unit='s')
+      1490195805433502912
+      pd.to_datetime(1490195805433502912, unit='ns')
 
 .. note::
 
-   Epoch times will be rounded to the nearest nanosecond.
+   These *work*, but the results may be unexpected.
+
+   .. ipython:: python
+
+      pd.to_datetime([1])
+      pd.to_datetime([1, 3.14], unit='s')
+
 
 .. _timeseries.origin:
 

pandas/tseries/tools.py

@@ -315,6 +315,16 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False,
     >>> %timeit pd.to_datetime(s,infer_datetime_format=False)
     1 loop, best of 3: 471 ms per loop
 
+    Using a unix epoch time
+
+    >>> pd.to_datetime(1490195805, unit='s')
+    Timestamp('2017-03-22 15:16:45')
+    >>> pd.to_datetime(1490195805433502912, unit='ns')
+    Timestamp('2017-03-22 15:16:45.433502912')
+
+    .. warning:: For float arg, precision rounding might happen. To prevent
+        unexpected behavior use a fixed-width exact type.
+
     Using a non-unix epoch origin
 
     >>> pd.to_datetime([1, 2, 3], unit='D',