Skip to content

DOC: Expand reference doc for read_json #14284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

DOC: Expand reference doc for read_json #14284

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fdc69f3
DOC: Expand on reference docs for panda.read_json()
cswarth Sep 23, 2016
4689d3a
address comments from @jorisvandenbossche
cswarth Sep 26, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 63 additions & 20 deletions pandas/io/json.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,33 +122,42 @@ def read_json(path_or_buf=None, orient=None, typ='frame', dtype=True,
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 ``file://localhost/path/to/table.json``
meta_prefix : string, default None
Copy link
Member

@jorisvandenbossche jorisvandenbossche Sep 28, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

copy-pasta error - removed


orient
orient : string,
Indication of expected JSON input format.
The set of allowed orients changes depending on the value
of the `typ` parameter.

* `Series`
* when ``typ == 'series'``,

- allowed orients are ``{'split','records','index'}``
- default is ``'index'``
- allowed values are: ``{'split','records','index'}``
- The Series index must be unique for orient ``'index'``.

* `DataFrame`
* when ``typ == 'frame'``,

- allowed orients are ``{'split','records','index',
'columns','values'}``
- default is ``'columns'``
- allowed values are: {'split','records','index','columns','values'}
- The DataFrame index must be unique for orients 'index' and
'columns'.
- The DataFrame columns must be unique for orients 'index',
'columns', and 'records'.

* The format of the JSON string

- split : dict like
``{index -> [index], columns -> [columns], data -> [values]}``
- records : list like
``[{column -> value}, ... , {column -> value}]``
- index : dict like ``{index -> {column -> value}}``
- columns : dict like ``{column -> {index -> value}}``
- values : just the values array
- The DataFrame index must be unique for orients ``'index'`` and
``'columns'``.
- The DataFrame columns must be unique for orients ``'index'``,
``'columns'``, and ``'records'``.


The value of `orient` specifies the expected format of the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The two blank lines are not needed above this one (one blank line is OK).

But something else: would it make it more clear to first list the possibilities, and then which of those is the default/accepted value depending on the type? (just an idea)

JSON string. The expected JSON formats are compatible with the
strings produced by ``to_json()`` with a corresponding value
of `orient`.

- ``'split'`` : dict like
``{index -> [index], columns -> [columns], data -> [values]}``
- ``'records'`` : list like
``[{column -> value}, ... , {column -> value}]``
- ``'index'`` : dict like ``{index -> {column -> value}}``
- ``'columns'`` : dict like ``{column -> {index -> value}}``
- ``'values'`` : just the values array

typ : type of object to recover (series or frame), default 'frame'
dtype : boolean or dict, default True
Expand Down Expand Up @@ -197,7 +206,41 @@ def read_json(path_or_buf=None, orient=None, typ='frame', dtype=True,

Returns
-------
result : Series or DataFrame
result : Series or DataFrame, depending on the value of `typ`.

Examples
--------

>>> df = pd.DataFrame([['a', 'b'], ['c', 'd']],
... index=['row 1', 'row 2'],
... columns=['col 1', 'col 2'])

>>> df.to_json(orient='split')
'{"columns":["col 1","col 2"],
"index":["row 1","row 2"],
"data":[["a","b"],["c","d"]]}'
<BLANKLINE>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose this is to have a blank line in the resulting code block, but to keep it as one code block? (so it's clearer they belong together).
That's a good idea I think, only a pity for the plain text docstring ..

BTW, you can also put some 'introducing' text in between the code examples when this can make it clearer what you are showing. (and that can also help delineate the different examples)

>>> pd.read_json(_, orient='split')
col 1 col 2
row 1 a b
row 2 c d

>>> df.to_json(orient='records')
'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'
<BLANKLINE>
>>> pd.read_json(_, orient='records')
col 1 col 2
0 a b
1 c d

>>> df.to_json(orient='index')
'{"row 1":{"col 1":"a","col 2":"b"},"row 2":{"col 1":"c","col 2":"d"}}'
<BLANKLINE>
>>> pd.read_json(_, orient='index')
col 1 col 2
row 1 a b
row 2 c d

"""

filepath_or_buffer, _, _ = get_filepath_or_buffer(path_or_buf,
Expand Down