DOC: Expand reference doc for read_json
State: closed

- [ ] closes #xxxx
- [ ] tests added / passed
- [x] passes `git diff upstream/master | flake8 --diff`
- [x] expanded reference document for `pandas.read_json()`, especially concentrating on the `orient` parameter.  Also added some example usage code and explicitly mention `to_json()` as a source of valid JSON strings.

<div class="section" id="pandas-read-json">
<h1>pandas.read_json<a class="headerlink" href="#pandas-read-json" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="pandas.read_json">
<code class="descclassname">pandas.</code><code class="descname">read_json</code><span class="sig-paren">(</span><em>path_or_buf=None</em>, <em>orient=None</em>, <em>typ='frame'</em>, <em>dtype=True</em>, <em>convert_axes=True</em>, <em>convert_dates=True</em>, <em>keep_default_dates=True</em>, <em>numpy=False</em>, <em>precise_float=False</em>, <em>date_unit=None</em>, <em>encoding=None</em>, <em>lines=False</em><span class="sig-paren">)</span><a class="reference external" href="http://github.com/pydata/pandas/blob/master/pandas/io/json.py#L112-L272"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#pandas.read_json" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a JSON string to pandas object</p>
<table class="docutils field-list" frame="void" rules="none">
<colgroup><col class="field-name">
<col class="field-body">
</colgroup><tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>path_or_buf</strong> : a valid JSON string or file-like, default: None</p>
<blockquote>
<div><p>The string could be a URL. Valid URL schemes include http, ftp, s3, and
file. For file URLs, a host is expected. For instance, a local file
could be <code class="docutils literal"><span class="pre">file://localhost/path/to/table.json</span></code></p>
</div></blockquote>
<p><strong>orient</strong> : string, indicating the expected format of the JSON input.</p>
<blockquote>
<div><p>The set of allowed orients changes depending on the value
of the <code class="docutils literal"><span class="pre">typ</span></code> parameter.</p>
<ul class="simple">
<li>when <code class="docutils literal"><span class="pre">typ</span> <span class="pre">==</span> <span class="pre">'series'</span></code>,<ul>
<li>allowed orients are <code class="docutils literal"><span class="pre">{'split','records','index'}</span></code></li>
<li>default is <code class="docutils literal"><span class="pre">'index'</span></code></li>
<li>The Series index must be unique for orient <code class="docutils literal"><span class="pre">'index'</span></code>.</li>
</ul>
</li>
<li>when <code class="docutils literal"><span class="pre">typ</span> <span class="pre">==</span> <span class="pre">'frame'</span></code>,<ul>
<li>allowed orients are <code class="docutils literal"><span class="pre">{'split','records','index',</span>
<span class="pre">'columns','values'}</span></code></li>
<li>default is <code class="docutils literal"><span class="pre">'columns'</span></code></li>
<li>The DataFrame index must be unique for orients ‘index’ and
‘columns’.</li>
<li>The DataFrame columns must be unique for orients ‘index’,
‘columns’, and ‘records’.</li>
</ul>
</li>
</ul>
<p>The value of <code class="docutils literal"><span class="pre">orient</span></code> specifies the expected format of the
JSON string. The expected JSON formats are compatible with the
strings produced by <code class="docutils literal"><span class="pre">to_json()</span></code> with a corresponding value
of <code class="docutils literal"><span class="pre">orient</span></code>.</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">'split'</span></code> : dict like
<code class="docutils literal"><span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">[index],</span> <span class="pre">columns</span> <span class="pre">-&gt;</span> <span class="pre">[columns],</span> <span class="pre">data</span> <span class="pre">-&gt;</span> <span class="pre">[values]}</span></code></li>
<li><code class="docutils literal"><span class="pre">'records'</span></code> : list like
<code class="docutils literal"><span class="pre">[{column</span> <span class="pre">-&gt;</span> <span class="pre">value},</span> <span class="pre">...</span> <span class="pre">,</span> <span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">value}]</span></code></li>
<li><code class="docutils literal"><span class="pre">'index'</span></code> : dict like <code class="docutils literal"><span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">value}}</span></code></li>
<li><code class="docutils literal"><span class="pre">'columns'</span></code> : dict like <code class="docutils literal"><span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">value}}</span></code></li>
<li><code class="docutils literal"><span class="pre">'values'</span></code> : just the values array</li>
</ul>
</div></blockquote>
</div></blockquote>
<p><strong>typ</strong> : type of object to recover (series or frame), default ‘frame’</p>
<p><strong>dtype</strong> : boolean or dict, default True</p>
<blockquote>
<div><p>If True, infer dtypes, if a dict of column to dtype, then use those,
if False, then don’t infer dtypes at all, applies only to the data.</p>
</div></blockquote>
<p><strong>convert_axes</strong> : boolean, default True</p>
<blockquote>
<div><p>Try to convert the axes to the proper dtypes.</p>
</div></blockquote>
<p><strong>convert_dates</strong> : boolean, default True</p>
<blockquote>
<div><p>List of columns to parse for dates; If True, then try to parse
datelike columns default is True; a column label is datelike if</p>
<ul class="simple">
<li>it ends with <code class="docutils literal"><span class="pre">'_at'</span></code>,</li>
<li>it ends with <code class="docutils literal"><span class="pre">'_time'</span></code>,</li>
<li>it begins with <code class="docutils literal"><span class="pre">'timestamp'</span></code>,</li>
<li>it is <code class="docutils literal"><span class="pre">'modified'</span></code>, or</li>
<li>it is <code class="docutils literal"><span class="pre">'date'</span></code></li>
</ul>
</div></blockquote>
<p><strong>keep_default_dates</strong> : boolean, default True</p>
<blockquote>
<div><p>If parsing dates, then parse the default datelike columns</p>
</div></blockquote>
<p><strong>numpy</strong> : boolean, default False</p>
<blockquote>
<div><p>Direct decoding to numpy arrays. Supports numeric data only, but
non-numeric column and index labels are supported. Note also that the
JSON ordering MUST be the same for each term if numpy=True.</p>
</div></blockquote>
<p><strong>precise_float</strong> : boolean, default False</p>
<blockquote>
<div><p>Set to enable usage of higher precision (strtod) function when
decoding string to double values. Default (False) is to use fast but
less precise builtin functionality</p>
</div></blockquote>
<p><strong>date_unit</strong> : string, default None</p>
<blockquote>
<div><p>The timestamp unit to detect if converting dates. The default behaviour
is to try and detect the correct precision, but if this is not desired
then pass one of ‘s’, ‘ms’, ‘us’ or ‘ns’ to force parsing only seconds,
milliseconds, microseconds or nanoseconds respectively.</p>
</div></blockquote>
<p><strong>lines</strong> : boolean, default False</p>
<blockquote>
<div><p>Read the file as a json object per line.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.19.0.</span></p>
</div>

</div></blockquote>

<p><strong>encoding</strong> : str, default is ‘utf-8’</p>

<blockquote>
<div><p>The encoding to use to decode py3 bytes.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.19.0.</span></p>
</div>
</div></blockquote>

</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><strong>result</strong> : Series or DataFrame, depending on the value of <code class="docutils literal"><span class="pre">typ</span></code>.</p>
</td>
</tr>
</tbody>
</table>

<p class="rubric">Examples</p>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">([[</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">],</span> <span class="p">[</span><span class="s1">'c'</span><span class="p">,</span> <span class="s1">'d'</span><span class="p">]],</span>
<span class="go">                          index=['row 1', 'row 2'],</span>
<span class="go">                          columns=['col 1', 'col 2'])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span> <span class="n">df</span>
<span class="go">      col 1 col 2</span>
<span class="go">row 1     a     b</span>
<span class="go">row 2     c     d</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">orient</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">'split'</span><span class="p">,</span> <span class="s1">'records'</span><span class="p">,</span> <span class="s1">'index'</span><span class="p">]:</span>
<span class="go">        str = df.to_json(orient=orient)</span>
<span class="go">        print "'{}': '{}'".format(orient, str)</span>
<span class="go">        pd.read_json(str, orient=orient)</span>
<span class="go">'split':</span>
<span class="go">'{"columns":["col 1","col 2"],"index":["row 1","row 2"],"data":[["a","b"],</span>
<span class="go">["c","d"]]}'</span>
<span class="go">'records':</span>
<span class="go">'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'</span>
<span class="go">'index':</span>
<span class="go">'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'</span>
</pre></div>
</div>

</dd></dl>

</div>


Labels:
name: Docs
name: IO JSON
description: read_json, to_json, json_normalize

Comments:
I don't think the failing CI checks are a consequence of the changes I propose in this PR, which are literally only changing python comments.

Is there anything I can do to get the PR a clean bill of health?

## [Current coverage](https://codecov.io/gh/pydata/pandas/pull/14284?src=pr) is 85.25% (diff: 100%)

> Merging [#14284](https://codecov.io/gh/pydata/pandas/pull/14284?src=pr) into [master](https://codecov.io/gh/pydata/pandas/branch/master?src=pr) will decrease coverage by **<.01%**

``` diff
@@             master     #14284   diff @@
==========================================
  Files           140        140          
  Lines         50579      50579          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
- Hits          43123      43122     -1   
- Misses         7456       7457     +1   
  Partials          0          0          
```

> Powered by [Codecov](https://codecov.io?src=pr). Last update [99b5876...4689d3a](https://codecov.io/gh/pydata/pandas/compare/99b587606c51b448a4542d01f396a5ea63684b56...4689d3ab63012098afcd1adb3391c0b496cdc00c?src=pr)

Preview of how the documentation looks after incorporating review comments.

<div class="body">
  <div class="section" id="pandas-read-json">
<table class="docutils field-list" frame="void" rules="none">
<colgroup><col class="field-name">
<col class="field-body">
</colgroup><tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>path_or_buf</strong> : a valid JSON string or file-like, default: None</p>
<blockquote>
<div><p>The string could be a URL. Valid URL schemes include http, ftp, s3, and
file. For file URLs, a host is expected. For instance, a local file
could be <code class="docutils literal"><span class="pre">file://localhost/path/to/table.json</span></code></p>
</div></blockquote>
<p><strong>meta_prefix</strong> : string, default None</p>
<p><strong>orient</strong> : string,</p>
<blockquote>
<div><p>Indication of expected JSON input format.
The set of allowed orients changes depending on the value
of the <cite>typ</cite> parameter.</p>
<ul class="simple">
<li>when <code class="docutils literal"><span class="pre">typ</span> <span class="pre">==</span> <span class="pre">'series'</span></code>,<ul>
<li>allowed orients are <code class="docutils literal"><span class="pre">{'split','records','index'}</span></code></li>
<li>default is <code class="docutils literal"><span class="pre">'index'</span></code></li>
<li>The Series index must be unique for orient <code class="docutils literal"><span class="pre">'index'</span></code>.</li>
</ul>
</li>
<li>when <code class="docutils literal"><span class="pre">typ</span> <span class="pre">==</span> <span class="pre">'frame'</span></code>,<ul>
<li>allowed orients are <code class="docutils literal"><span class="pre">{'split','records','index',</span>
<span class="pre">'columns','values'}</span></code></li>
<li>default is <code class="docutils literal"><span class="pre">'columns'</span></code></li>
<li>The DataFrame index must be unique for orients <code class="docutils literal"><span class="pre">'index'</span></code> and
<code class="docutils literal"><span class="pre">'columns'</span></code>.</li>
<li>The DataFrame columns must be unique for orients <code class="docutils literal"><span class="pre">'index'</span></code>,
<code class="docutils literal"><span class="pre">'columns'</span></code>, and <code class="docutils literal"><span class="pre">'records'</span></code>.</li>
</ul>
</li>
</ul>
<p>The value of <cite>orient</cite> specifies the expected format of the
JSON string. The expected JSON formats are compatible with the
strings produced by <code class="docutils literal"><span class="pre">to_json()</span></code> with a corresponding value
of <cite>orient</cite>.</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">'split'</span></code> : dict like
<code class="docutils literal"><span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">[index],</span> <span class="pre">columns</span> <span class="pre">-&gt;</span> <span class="pre">[columns],</span> <span class="pre">data</span> <span class="pre">-&gt;</span> <span class="pre">[values]}</span></code></li>
<li><code class="docutils literal"><span class="pre">'records'</span></code> : list like
<code class="docutils literal"><span class="pre">[{column</span> <span class="pre">-&gt;</span> <span class="pre">value},</span> <span class="pre">...</span> <span class="pre">,</span> <span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">value}]</span></code></li>
<li><code class="docutils literal"><span class="pre">'index'</span></code> : dict like <code class="docutils literal"><span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">value}}</span></code></li>
<li><code class="docutils literal"><span class="pre">'columns'</span></code> : dict like <code class="docutils literal"><span class="pre">{column</span> <span class="pre">-&gt;</span> <span class="pre">{index</span> <span class="pre">-&gt;</span> <span class="pre">value}}</span></code></li>
<li><code class="docutils literal"><span class="pre">'values'</span></code> : just the values array</li>
</ul>
</div></blockquote>
<p><strong>typ</strong> : type of object to recover (series or frame), default ‘frame’</p>
<p><strong>dtype</strong> : boolean or dict, default True</p>
<blockquote>
<div><p>If True, infer dtypes, if a dict of column to dtype, then use those,
if False, then don’t infer dtypes at all, applies only to the data.</p>
</div></blockquote>
<p><strong>convert_axes</strong> : boolean, default True</p>
<blockquote>
<div><p>Try to convert the axes to the proper dtypes.</p>
</div></blockquote>
<p><strong>convert_dates</strong> : boolean, default True</p>
<blockquote>
<div><p>List of columns to parse for dates; If True, then try to parse
datelike columns default is True; a column label is datelike if</p>
<ul class="simple">
<li>it ends with <code class="docutils literal"><span class="pre">'_at'</span></code>,</li>
<li>it ends with <code class="docutils literal"><span class="pre">'_time'</span></code>,</li>
<li>it begins with <code class="docutils literal"><span class="pre">'timestamp'</span></code>,</li>
<li>it is <code class="docutils literal"><span class="pre">'modified'</span></code>, or</li>
<li>it is <code class="docutils literal"><span class="pre">'date'</span></code></li>
</ul>
</div></blockquote>
<p><strong>keep_default_dates</strong> : boolean, default True</p>
<blockquote>
<div><p>If parsing dates, then parse the default datelike columns</p>
</div></blockquote>
<p><strong>numpy</strong> : boolean, default False</p>
<blockquote>
<div><p>Direct decoding to numpy arrays. Supports numeric data only, but
non-numeric column and index labels are supported. Note also that the
JSON ordering MUST be the same for each term if numpy=True.</p>
</div></blockquote>
<p><strong>precise_float</strong> : boolean, default False</p>
<blockquote>
<div><p>Set to enable usage of higher precision (strtod) function when
decoding string to double values. Default (False) is to use fast but
less precise builtin functionality</p>
</div></blockquote>
<p><strong>date_unit</strong> : string, default None</p>
<blockquote>
<div><p>The timestamp unit to detect if converting dates. The default behaviour
is to try and detect the correct precision, but if this is not desired
then pass one of ‘s’, ‘ms’, ‘us’ or ‘ns’ to force parsing only seconds,
milliseconds, microseconds or nanoseconds respectively.</p>
</div></blockquote>
<p><strong>lines</strong> : boolean, default False</p>
<blockquote>
<div><p>Read the file as a json object per line.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.19.0.</span></p>
</div>

</div></blockquote>

<p><strong>encoding</strong> : str, default is ‘utf-8’</p>

<blockquote>
<div><p>The encoding to use to decode py3 bytes.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.19.0.</span></p>
</div>
</div></blockquote>

</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><strong>result</strong> : Series or DataFrame, depending on the value of <cite>typ</cite>.</p>
</td>
</tr>
</tbody>
</table>

<p class="rubric">Examples</p>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">([[</span><span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">],</span> <span class="p">[</span><span class="s1">'c'</span><span class="p">,</span> <span class="s1">'d'</span><span class="p">]],</span>
<span class="gp">... </span>                  <span class="n">index</span><span class="o">=</span><span class="p">[</span><span class="s1">'row 1'</span><span class="p">,</span> <span class="s1">'row 2'</span><span class="p">],</span>
<span class="gp">... </span>                  <span class="n">columns</span><span class="o">=</span><span class="p">[</span><span class="s1">'col 1'</span><span class="p">,</span> <span class="s1">'col 2'</span><span class="p">])</span>
</pre></div>
</div>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span><span class="o">.</span><span class="n">to_json</span><span class="p">(</span><span class="n">orient</span><span class="o">=</span><span class="s1">'split'</span><span class="p">)</span>
<span class="go">'{"columns":["col 1","col 2"],</span>
<span class="go">  "index":["row 1","row 2"],</span>
<span class="go">  "data":[["a","b"],["c","d"]]}'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">read_json</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">orient</span><span class="o">=</span><span class="s1">'split'</span><span class="p">)</span>
<span class="go">      col 1 col 2</span>
<span class="go">row 1     a     b</span>
<span class="go">row 2     c     d</span>
</pre></div>
</div>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span><span class="o">.</span><span class="n">to_json</span><span class="p">(</span><span class="n">orient</span><span class="o">=</span><span class="s1">'records'</span><span class="p">)</span>
<span class="go">'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">read_json</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">orient</span><span class="o">=</span><span class="s1">'records'</span><span class="p">)</span>
<span class="go">  col 1 col 2</span>
<span class="go">0     a     b</span>
<span class="go">1     c     d</span>
</pre></div>
</div>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span><span class="o">.</span><span class="n">to_json</span><span class="p">(</span><span class="n">orient</span><span class="o">=</span><span class="s1">'index'</span><span class="p">)</span>
<span class="go">'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">read_json</span><span class="p">(</span><span class="n">_</span><span class="p">,</span> <span class="n">orient</span><span class="o">=</span><span class="s1">'index'</span><span class="p">)</span>
<span class="go">      col 1 col 2</span>
<span class="go">row 1     a     b</span>
<span class="go">row 2     c     d</span>
</pre></div>
</div>

</dd></dl>

</div>

@cswarth Do you have time to update this? It's a really nice improvement of the docstring!

I'm mystified and could use some help to figure out what's going on.  I pushed a commit to my branch to address your review, but this PR is not picking up the changes.   

I can [see the commit](https://github.com/cswarth/pandas/commit/94484fe7270d28d57b974b5d540f0549908f97b1) on the branch, but the [commits](https://github.com/pandas-dev/pandas/pull/14284/commits) link at the top of this page insists there are only two commits for this PR.

I can't figure out what I've screwed up here.

@cswarth yeah we changed the base github domain to pandas-dev and it seems can push existing PR's. So close this, one and open a new PR.

Closing to move PR to new github domain