From d544f7b61f8d806d7c4aaaef0518aa7a5069655c Mon Sep 17 00:00:00 2001 From: "Michael P. Moran" Date: Sun, 7 Jul 2019 13:28:48 -0500 Subject: [PATCH 1/4] DOC: cleanup docstring for read_json and fix error in contribution guide --- doc/source/development/contributing.rst | 8 ++--- pandas/io/json/json.py | 39 ++++++++++++++----------- 2 files changed, 26 insertions(+), 21 deletions(-) diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst index dde1db7e693de..e33996f2081aa 100644 --- a/doc/source/development/contributing.rst +++ b/doc/source/development/contributing.rst @@ -288,7 +288,7 @@ complex changes to the documentation as well. Some other important things to know about the docs: * The *pandas* documentation consists of two parts: the docstrings in the code - itself and the docs in this folder ``pandas/doc/``. + itself and the docs in this folder ``doc/``. The docstrings provide a clear explanation of the usage of the individual functions, while the documentation in this folder consists of tutorial-like @@ -404,11 +404,11 @@ Building the documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~ So how do you build the docs? Navigate to your local -``pandas/doc/`` directory in the console and run:: +``doc/`` directory in the console and run:: python make.py html -Then you can find the HTML output in the folder ``pandas/doc/build/html/``. +Then you can find the HTML output in the folder ``doc/build/html/``. The first time you build the docs, it will take quite a while because it has to run all the code examples and build all the generated docstring pages. In subsequent @@ -448,7 +448,7 @@ You can also specify to use multiple cores to speed up the documentation build:: Open the following file in a web browser to see the full documentation you just built:: - pandas/docs/build/html/index.html + doc/build/html/index.html And you'll have the satisfaction of seeing your new and improved documentation! diff --git a/pandas/io/json/json.py b/pandas/io/json/json.py index f3f0f417acaab..1795cc7b91051 100644 --- a/pandas/io/json/json.py +++ b/pandas/io/json/json.py @@ -355,9 +355,9 @@ def read_json( path_or_buf : a valid JSON string or file-like, default: None The string could be a URL. Valid URL schemes include http, ftp, s3, gcs, and file. For file URLs, a host is expected. For instance, a local - file could be ``file://localhost/path/to/table.json`` + file could be ``file://localhost/path/to/table.json``. - orient : string, + orient : str, Indication of expected JSON string format. Compatible JSON strings can be produced by ``to_json()`` with a corresponding orient value. @@ -394,7 +394,8 @@ def read_json( 'table' as an allowed value for the ``orient`` argument typ : type of object to recover (series or frame), default 'frame' - dtype : boolean or dict, default None + + dtype : bool or dict, default None 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. @@ -404,7 +405,7 @@ def read_json( Not applicable for ``orient='table'``. - convert_axes : boolean, default None + convert_axes : bool, default None Try to convert the axes to the proper dtypes. For all ``orient`` values except ``'table'``, default is True. @@ -413,9 +414,9 @@ def read_json( Not applicable for ``orient='table'``. - convert_dates : boolean, default True - List of columns to parse for dates; If True, then try to parse - datelike columns default is True; a column label is datelike if + convert_dates : bool or list, default True + List of columns to parse for dates. If True, then try to parse + datelike columns. A column label is datelike if * it ends with ``'_at'``, @@ -425,34 +426,38 @@ def read_json( * it is ``'modified'``, or - * it is ``'date'`` + * it is ``'date'``. + + keep_default_dates : bool, default True + If parsing dates, then parse the default datelike columns. - keep_default_dates : boolean, default True - If parsing dates, then parse the default datelike columns - numpy : boolean, default False + numpy : bool, default False 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. - precise_float : boolean, default False + + precise_float : bool, default False 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 - date_unit : string, default None + less precise builtin functionality. + + date_unit : str, default None 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. + encoding : str, default is 'utf-8' The encoding to use to decode py3 bytes. .. versionadded:: 0.19.0 - lines : boolean, default False + lines : bool, default False Read the file as a json object per line. .. versionadded:: 0.19.0 - chunksize : integer, default None + chunksize : int, default None Return JsonReader object for iteration. See the `line-delimited json docs `_ @@ -473,7 +478,7 @@ def read_json( Returns ------- - result : Series or DataFrame, depending on the value of `typ`. + Series or DataFrame, depending on the value of `typ`. See Also -------- From a92642db6a9bb6f9cf61c08ba2d6c6f8bb6779da Mon Sep 17 00:00:00 2001 From: "Michael P. Moran" Date: Mon, 8 Jul 2019 15:54:19 -0500 Subject: [PATCH 2/4] DOC: conforming changes to docstring for read_json function --- pandas/io/json/_json.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/pandas/io/json/_json.py b/pandas/io/json/_json.py index 0853c3692d8de..e49b4aeea78c4 100644 --- a/pandas/io/json/_json.py +++ b/pandas/io/json/_json.py @@ -352,12 +352,12 @@ def read_json( Parameters ---------- - path_or_buf : a valid JSON string or file-like, default: None + path_or_buf : a valid JSON string or file-like, default None The string could be a URL. Valid URL schemes include http, ftp, s3, gcs, and file. For file URLs, a host is expected. For instance, a local file could be ``file://localhost/path/to/table.json``. - orient : str, + orient : str, default None Indication of expected JSON string format. Compatible JSON strings can be produced by ``to_json()`` with a corresponding orient value. @@ -393,7 +393,8 @@ def read_json( .. versionadded:: 0.23.0 'table' as an allowed value for the ``orient`` argument - typ : type of object to recover (series or frame), default 'frame' + typ : {'frame', 'series'}, default 'frame' + The type of object to recover. dtype : bool or dict, default None If True, infer dtypes; if a dict of column to dtype, then use those; @@ -478,11 +479,13 @@ def read_json( Returns ------- - Series or DataFrame, depending on the value of `typ`. + Series or DataFrame + The type returned depends on the value of `typ`. See Also -------- - DataFrame.to_json + DataFrame.to_json : Convert a DataFrame to a JSON string. + Series.to_json : Convert a Series to a JSON string. Notes ----- From aa0c36ed12c0d2df063d67ecba0bf76023b67277 Mon Sep 17 00:00:00 2001 From: "Michael P. Moran" Date: Tue, 9 Jul 2019 10:51:33 -0500 Subject: [PATCH 3/4] fix type hints --- pandas/io/json/_json.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/io/json/_json.py b/pandas/io/json/_json.py index e49b4aeea78c4..5895207572984 100644 --- a/pandas/io/json/_json.py +++ b/pandas/io/json/_json.py @@ -415,7 +415,7 @@ def read_json( Not applicable for ``orient='table'``. - convert_dates : bool or list, default True + convert_dates : bool or list of str, default True List of columns to parse for dates. If True, then try to parse datelike columns. A column label is datelike if @@ -458,7 +458,7 @@ def read_json( .. versionadded:: 0.19.0 - chunksize : int, default None + chunksize : int, optional Return JsonReader object for iteration. See the `line-delimited json docs `_ From 5c8ed1877680f616d178e6d83276a236b6b52730 Mon Sep 17 00:00:00 2001 From: "Michael P. Moran" Date: Tue, 9 Jul 2019 16:18:23 -0500 Subject: [PATCH 4/4] correct explanation of default value in type hint --- pandas/io/json/_json.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/io/json/_json.py b/pandas/io/json/_json.py index 5895207572984..15f12db281251 100644 --- a/pandas/io/json/_json.py +++ b/pandas/io/json/_json.py @@ -357,7 +357,7 @@ def read_json( gcs, and file. For file URLs, a host is expected. For instance, a local file could be ``file://localhost/path/to/table.json``. - orient : str, default None + orient : str, optional Indication of expected JSON string format. Compatible JSON strings can be produced by ``to_json()`` with a corresponding orient value.