Skip to content

DOC: update the to_json() docstring #20149

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

Merged
merged 4 commits into from
Mar 13, 2018
Merged

DOC: update the to_json() docstring #20149

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8e7b162
Fix validation errors on to_json()
robmarkcole Mar 10, 2018
5a5123c
Addresses reviewer comments
robmarkcole Mar 13, 2018
91f258c
fix some quoting
jorisvandenbossche Mar 13, 2018
579532a
remove incorrect return
jorisvandenbossche Mar 13, 2018
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
37 changes: 25 additions & 12 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1665,8 +1665,9 @@ def to_json(self, path_or_buf=None, orient=None, date_format=None,
Parameters
----------
path_or_buf : the path or buffer to write the result string
Copy link
Member

Choose a reason for hiding this comment

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

The "the path or buffer to write the result string" is actually the explanation, so should go on the next line. On this line comes the type description, you can take a look at eg DataFrame.to_csv how this is typically explained.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Cheers

if this is None, return the converted string
If this is None, return the converted string.
orient : string
Indication of expected JSON string format.

* Series

Expand All @@ -1692,16 +1693,18 @@ def to_json(self, path_or_buf=None, orient=None, date_format=None,
describing the data, and the data component is
like ``orient='records'``.

.. versionchanged:: 0.20.0
.. versionchanged:: 0.20.0.

date_format : {None, 'epoch', 'iso'}
Type of date conversion. `epoch` = epoch milliseconds,
`iso` = ISO8601. The default depends on the `orient`. For
`orient='table'`, the default is `'iso'`. For all other orients,
the default is `'epoch'`.
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.
double_precision : int, default 10
The number of decimal places to use when encoding
floating point values.
force_ascii : boolean, default True
Force encoded string to be ASCII.
date_unit : string, default 'ms' (milliseconds)
The time unit to encode to, governs timestamp and ISO8601
precision. One of 's', 'ms', 'us', 'ns' for second, millisecond,
Expand All @@ -1715,20 +1718,20 @@ def to_json(self, path_or_buf=None, orient=None, date_format=None,
throw ValueError if incorrect 'orient' since others are not list
like.

.. versionadded:: 0.19.0
.. versionadded:: 0.19.0.

compression : {None, 'gzip', 'bz2', 'xz'}
A string representing the compression to use in the output file,
only used when the first argument is a filename

.. versionadded:: 0.21.0
.. versionadded:: 0.21.0.

index : boolean, default True
Whether to include the index values in the JSON string. Not
including the index (``index=False``) is only supported when
orient is 'split' or 'table'.

.. versionadded:: 0.23.0
.. versionadded:: 0.23.0.

Returns
-------
Expand All @@ -1749,16 +1752,26 @@ def to_json(self, path_or_buf=None, orient=None, date_format=None,
"index":["row 1","row 2"],
"data":[["a","b"],["c","d"]]}'

Encoding/decoding a Dataframe using ``'records'`` formatted JSON.
Note that index labels are not preserved with this encoding.

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

Encoding/decoding a Dataframe using ``'index'`` formatted JSON:

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

Encoding/decoding a Dataframe using ``'records'`` formatted JSON.
Note that index labels are not preserved with this encoding.
Encoding/decoding a Dataframe using ``'columns'`` formatted JSON:

>>> df.to_json(orient='records')
'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'
>>> df.to_json(orient='columns')
'{"col 1":{"row 1":"a","row 2":"c"},"col 2":{"row 1":"b","row 2":"d"}}'

Encoding/decoding a Dataframe using ``'values'`` formatted JSON:

>>> df.to_json(orient='values')
'[["a","b"],["c","d"]]'

Encoding with Table Schema

Expand Down