DOC: update json docs for new date behaviour

Author: Komnomnomnom

doc/source/io.rst

@@ -1034,11 +1034,12 @@ with optional parameters:
      ``columns``; dict like {column -> {index -> value}}
      ``values``; just the values array
 
-- ``date_format`` : type of date conversion (epoch = epoch milliseconds, iso = ISO8601), default is epoch
+- ``date_format`` : string, type of date conversion, 'epoch' for timestamp, 'iso' for ISO8601.
 - ``double_precision`` : The number of decimal places to use when encoding floating point values, default 10.
 - ``force_ascii`` : force encoded string to be ASCII, default True.
+- ``date_unit`` : The time unit to encode to, governs timestamp and ISO8601 precision. One of 's', 'ms', 'us' or 'ns' for seconds, milliseconds, microseconds and nanoseconds respectively. Default 'ms'.
 
-Note NaN's and None will be converted to null and datetime objects will be converted based on the date_format parameter
+Note NaN's, NaT's and None will be converted to null and datetime objects will be converted based on the date_format and date_unit parameters.
 
 .. ipython:: python
 
@@ -1055,6 +1056,20 @@ Writing in iso date format
    json = dfd.to_json(date_format='iso')
    json
 
+Writing in iso date format, with microseconds
+
+.. ipython:: python
+
+   json = dfd.to_json(date_format='iso', date_unit='us')
+   json
+
+Actually I prefer epoch timestamps, in seconds
+
+.. ipython:: python
+
+   json = dfd.to_json(date_format='epoch', date_unit='s')
+   json
+
 Writing to a file, with a date index and a date column
 
 .. ipython:: python
@@ -1063,7 +1078,7 @@ Writing to a file, with a date index and a date column
    dfj2['date'] = Timestamp('20130101')
    dfj2['ints'] = list(range(5))
    dfj2['bools'] = True
-   dfj2.index = date_range('20130101',periods=5)
+   dfj2.index = date_range('20130101', periods=5)
    dfj2.to_json('test.json')
    open('test.json').read()
 
@@ -1113,13 +1128,16 @@ is ``None``. To explicity force ``Series`` parsing, pass ``typ=series``
   then pass one of 's', 'ms', 'us' or 'ns' to force timestamp precision to
   seconds, milliseconds, microseconds or nanoseconds respectively.
 
-The parser will raise one of ``ValueError/TypeError/AssertionError`` if the JSON is
-not parsable.
+The parser will raise one of ``ValueError/TypeError/AssertionError`` if the JSON is not parsable.
 
 The default of ``convert_axes=True``, ``dtype=True``, and ``convert_dates=True`` will try to parse the axes, and all of the data
 into appropriate types, including dates. If you need to override specific dtypes, pass a dict to ``dtype``. ``convert_axes`` should only
 be set to ``False`` if you need to preserve string-like numbers (e.g. '1', '2') in an axes.
 
+.. note::
+
+  Large integer values may be converted to dates if ``convert_dates=True`` and the data and / or column labels appear 'date-like'. The exact threshold depends on the ``date_unit`` specified.
+
 .. warning::
 
    When reading JSON data, automatic coercing into dtypes has some quirks:
@@ -1146,13 +1164,13 @@ Don't convert any data (but still convert axes and dates)
 
 .. ipython:: python
 
-   pd.read_json('test.json',dtype=object).dtypes
+   pd.read_json('test.json', dtype=object).dtypes
 
 Specify how I want to convert data
 
 .. ipython:: python
 
-   pd.read_json('test.json',dtype={'A' : 'float32', 'bools' : 'int8'}).dtypes
+   pd.read_json('test.json', dtype={'A' : 'float32', 'bools' : 'int8'}).dtypes
 
 I like my string indicies
 
@@ -1166,7 +1184,7 @@ I like my string indicies
    si.columns
    json = si.to_json()
 
-   sij = pd.read_json(json,convert_axes=False)
+   sij = pd.read_json(json, convert_axes=False)
    sij
    sij.index
    sij.columns

doc/source/release.rst

@@ -47,6 +47,7 @@ pandas 0.13
   - Added a more informative error message when plot arguments contain
     overlapping color and style arguments (:issue:`4402`)
   - Significant table writing performance improvements in ``HDFStore``
+  - JSON date serialisation now performed in low-level C code.
   - ``Index.copy()`` and ``MultiIndex.copy()`` now accept keyword arguments to
     change attributes (i.e., ``names``, ``levels``, ``labels``)
     (:issue:`4039`)
@@ -94,6 +95,10 @@ pandas 0.13
     - removed the ``warn`` argument from ``open``. Instead a ``PossibleDataLossError`` exception will
       be raised if you try to use ``mode='w'`` with an OPEN file handle (:issue:`4367`)
     - allow a passed locations array or mask as a ``where`` condition (:issue:`4467`)
+  - ``JSON``
+
+    - added ``date_unit`` parameter to specify resolution of timestamps. Options
+      are seconds, milliseconds, microseconds and nanoseconds. (:issue:`4362`, :issue:`4498`).
 
   - ``Index`` and ``MultiIndex`` changes (:issue:`4039`):