Code review - I

- json_normalize --> _json_normalize
- json_normalize inside io.json._normalize is a deprecated method
- update whatsnew docs
- update io docs
- fix broken test_api

Author: vishwakftw

doc/source/user_guide/io.rst

@@ -2150,7 +2150,7 @@ into a flat table.
 
 .. ipython:: python
 
-   from pandas.io.json import json_normalize
+   from pandas import json_normalize
    data = [{'id': 1, 'name': {'first': 'Coleen', 'last': 'Volk'}},
            {'name': {'given': 'Mose', 'family': 'Regner'}},
            {'id': 2, 'name': 'Faye Raker'}]

doc/source/whatsnew/v1.0.0.rst

@@ -52,7 +52,7 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
-- Moved :func:`pandas.io.json.json_normalize` to the top-level namespace as :func:`pandas.json_normalize`.
+- :func:`pandas.json_normalize` is now exposed in the top-level namespace. Usage of :func:`json_normalize` as :func:`pandas.io.json.json_normalize` is now deprecated and it is recommended to use :func:`json_normalize` as :func:`pandas.json_normalize` instead. (:issue:`27586`)
 -
 -
 

pandas/__init__.py

@@ -179,7 +179,7 @@
 )
 
 from pandas.io.json import (
-    json_normalize
+    _json_normalize as json_normalize
 )
 
 from pandas.util._tester import test

pandas/io/json/__init__.py

@@ -1,12 +1,13 @@
 from pandas.io.json._json import dumps, loads, read_json, to_json
-from pandas.io.json._normalize import json_normalize
+from pandas.io.json._normalize import _json_normalize, json_normalize
 from pandas.io.json._table_schema import build_table_schema
 
 __all__ = [
     "dumps",
     "loads",
     "read_json",
     "to_json",
+    "_json_normalize",
     "json_normalize",
     "build_table_schema",
 ]

pandas/io/json/_normalize.py

@@ -10,6 +10,7 @@
 from pandas._libs.writers import convert_json_to_lines
 
 from pandas import DataFrame
+from pandas.util._decorators import deprecate
 
 
 def convert_to_line_delimits(s):
@@ -111,7 +112,7 @@ def nested_to_record(
     return new_ds
 
 
-def json_normalize(
+def _json_normalize(
     data: Union[Dict, List[Dict]],
     record_path: Optional[Union[str, List]] = None,
     meta: Optional[Union[str, List]] = None,
@@ -341,3 +342,11 @@ def _recursive_extract(data, path, seen_meta, level=0):
             )
         result[k] = np.array(v, dtype=object).repeat(lengths)
     return result
+
+
+json_normalize = deprecate(
+            "pandas.io.json.json_normalize",
+            _json_normalize,
+            "1.0.0",
+            "pandas.json_normalize",
+            )

pandas/tests/api/test_api.py

@@ -168,6 +168,9 @@ class TestPDApi(Base):
         "read_spss",
     ]
 
+    # top-level json funcs
+    funcs_json = ["json_normalize"]
+
     # top-level to_* funcs
     funcs_to = ["to_datetime", "to_msgpack", "to_numeric", "to_pickle", "to_timedelta"]