Skip to content

Commit 070341c

Browse files
ShaharNavehShaharNaveh
authored
DOC: Fix docs for io/json/* (#41284)
1 parent a997bab commit 070341c

File tree

4 files changed

+128
-82
lines changed

4 files changed

+128
-82
lines changed

‎ci/code_checks.sh

+1
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
140140
pandas/core/window/ \
141141
pandas/errors/ \
142142
pandas/io/clipboard/ \
143+
pandas/io/json/ \
143144
pandas/io/excel/ \
144145
pandas/io/parsers/ \
145146
pandas/io/sas/ \

‎pandas/io/json/_json.py

+20-10
Original file line numberDiff line numberDiff line change
@@ -526,9 +526,13 @@ def read_json(
526526
Encoding/decoding a Dataframe using ``'split'`` formatted JSON:
527527
528528
>>> df.to_json(orient='split')
529-
'{{"columns":["col 1","col 2"],
530-
"index":["row 1","row 2"],
531-
"data":[["a","b"],["c","d"]]}}'
529+
'\
530+
{{\
531+
"columns":["col 1","col 2"],\
532+
"index":["row 1","row 2"],\
533+
"data":[["a","b"],["c","d"]]\
534+
}}\
535+
'
532536
>>> pd.read_json(_, orient='split')
533537
col 1 col 2
534538
row 1 a b
@@ -538,6 +542,7 @@ def read_json(
538542
539543
>>> df.to_json(orient='index')
540544
'{{"row 1":{{"col 1":"a","col 2":"b"}},"row 2":{{"col 1":"c","col 2":"d"}}}}'
545+
541546
>>> pd.read_json(_, orient='index')
542547
col 1 col 2
543548
row 1 a b
@@ -556,13 +561,18 @@ def read_json(
556561
Encoding with Table Schema
557562
558563
>>> df.to_json(orient='table')
559-
'{{"schema": {{"fields": [{{"name": "index", "type": "string"}},
560-
{{"name": "col 1", "type": "string"}},
561-
{{"name": "col 2", "type": "string"}}],
562-
"primaryKey": "index",
563-
"pandas_version": "0.20.0"}},
564-
"data": [{{"index": "row 1", "col 1": "a", "col 2": "b"}},
565-
{{"index": "row 2", "col 1": "c", "col 2": "d"}}]}}'
564+
'\
565+
{{"schema":{{"fields":[\
566+
{{"name":"index","type":"string"}},\
567+
{{"name":"col 1","type":"string"}},\
568+
{{"name":"col 2","type":"string"}}],\
569+
"primaryKey":["index"],\
570+
"pandas_version":"0.20.0"}},\
571+
"data":[\
572+
{{"index":"row 1","col 1":"a","col 2":"b"}},\
573+
{{"index":"row 2","col 1":"c","col 2":"d"}}]\
574+
}}\
575+
'
566576
"""
567577
if orient == "table" and dtype:
568578
raise ValueError("cannot pass both dtype and orient='table'")

‎pandas/io/json/_normalize.py

+83-53
Original file line numberDiff line numberDiff line change
@@ -70,15 +70,17 @@ def nested_to_record(
7070
7171
Examples
7272
--------
73-
IN[52]: nested_to_record(dict(flat1=1,dict1=dict(c=1,d=2),
74-
nested=dict(e=dict(c=1,d=2),d=2)))
75-
Out[52]:
76-
{'dict1.c': 1,
77-
'dict1.d': 2,
78-
'flat1': 1,
79-
'nested.d': 2,
80-
'nested.e.c': 1,
81-
'nested.e.d': 2}
73+
>>> nested_to_record(
74+
... dict(flat1=1, dict1=dict(c=1, d=2), nested=dict(e=dict(c=1, d=2), d=2))
75+
... )
76+
{\
77+
'flat1': 1, \
78+
'dict1.c': 1, \
79+
'dict1.d': 2, \
80+
'nested.e.c': 1, \
81+
'nested.e.d': 2, \
82+
'nested.d': 2\
83+
}
8284
"""
8385
singleton = False
8486
if isinstance(ds, dict):
@@ -208,18 +210,21 @@ def _simple_json_normalize(
208210
209211
Examples
210212
--------
211-
IN[52]: _simple_json_normalize({
212-
'flat1': 1,
213-
'dict1': {'c': 1, 'd': 2},
214-
'nested': {'e': {'c': 1, 'd': 2}, 'd': 2}
215-
})
216-
Out[52]:
217-
{'dict1.c': 1,
218-
'dict1.d': 2,
219-
'flat1': 1,
220-
'nested.d': 2,
221-
'nested.e.c': 1,
222-
'nested.e.d': 2}
213+
>>> _simple_json_normalize(
214+
... {
215+
... "flat1": 1,
216+
... "dict1": {"c": 1, "d": 2},
217+
... "nested": {"e": {"c": 1, "d": 2}, "d": 2},
218+
... }
219+
... )
220+
{\
221+
'flat1': 1, \
222+
'dict1.c': 1, \
223+
'dict1.d': 2, \
224+
'nested.e.c': 1, \
225+
'nested.e.d': 2, \
226+
'nested.d': 2\
227+
}
223228
224229
"""
225230
normalised_json_object = {}
@@ -283,22 +288,30 @@ def _json_normalize(
283288
284289
Examples
285290
--------
286-
>>> data = [{'id': 1, 'name': {'first': 'Coleen', 'last': 'Volk'}},
287-
... {'name': {'given': 'Mark', 'family': 'Regner'}},
288-
... {'id': 2, 'name': 'Faye Raker'}]
291+
>>> data = [
292+
... {"id": 1, "name": {"first": "Coleen", "last": "Volk"}},
293+
... {"name": {"given": "Mark", "family": "Regner"}},
294+
... {"id": 2, "name": "Faye Raker"},
295+
... ]
289296
>>> pd.json_normalize(data)
290297
id name.first name.last name.given name.family name
291298
0 1.0 Coleen Volk NaN NaN NaN
292299
1 NaN NaN NaN Mark Regner NaN
293300
2 2.0 NaN NaN NaN NaN Faye Raker
294301
295-
>>> data = [{'id': 1,
296-
... 'name': "Cole Volk",
297-
... 'fitness': {'height': 130, 'weight': 60}},
298-
... {'name': "Mark Reg",
299-
... 'fitness': {'height': 130, 'weight': 60}},
300-
... {'id': 2, 'name': 'Faye Raker',
301-
... 'fitness': {'height': 130, 'weight': 60}}]
302+
>>> data = [
303+
... {
304+
... "id": 1,
305+
... "name": "Cole Volk",
306+
... "fitness": {"height": 130, "weight": 60},
307+
... },
308+
... {"name": "Mark Reg", "fitness": {"height": 130, "weight": 60}},
309+
... {
310+
... "id": 2,
311+
... "name": "Faye Raker",
312+
... "fitness": {"height": 130, "weight": 60},
313+
... },
314+
... ]
302315
>>> pd.json_normalize(data, max_level=0)
303316
id name fitness
304317
0 1.0 Cole Volk {'height': 130, 'weight': 60}
@@ -307,32 +320,49 @@ def _json_normalize(
307320
308321
Normalizes nested data up to level 1.
309322
310-
>>> data = [{'id': 1,
311-
... 'name': "Cole Volk",
312-
... 'fitness': {'height': 130, 'weight': 60}},
313-
... {'name': "Mark Reg",
314-
... 'fitness': {'height': 130, 'weight': 60}},
315-
... {'id': 2, 'name': 'Faye Raker',
316-
... 'fitness': {'height': 130, 'weight': 60}}]
323+
>>> data = [
324+
... {
325+
... "id": 1,
326+
... "name": "Cole Volk",
327+
... "fitness": {"height": 130, "weight": 60},
328+
... },
329+
... {"name": "Mark Reg", "fitness": {"height": 130, "weight": 60}},
330+
... {
331+
... "id": 2,
332+
... "name": "Faye Raker",
333+
... "fitness": {"height": 130, "weight": 60},
334+
... },
335+
... ]
317336
>>> pd.json_normalize(data, max_level=1)
318337
id name fitness.height fitness.weight
319338
0 1.0 Cole Volk 130 60
320339
1 NaN Mark Reg 130 60
321340
2 2.0 Faye Raker 130 60
322341
323-
>>> data = [{'state': 'Florida',
324-
... 'shortname': 'FL',
325-
... 'info': {'governor': 'Rick Scott'},
326-
... 'counties': [{'name': 'Dade', 'population': 12345},
327-
... {'name': 'Broward', 'population': 40000},
328-
... {'name': 'Palm Beach', 'population': 60000}]},
329-
... {'state': 'Ohio',
330-
... 'shortname': 'OH',
331-
... 'info': {'governor': 'John Kasich'},
332-
... 'counties': [{'name': 'Summit', 'population': 1234},
333-
... {'name': 'Cuyahoga', 'population': 1337}]}]
334-
>>> result = pd.json_normalize(data, 'counties', ['state', 'shortname',
335-
... ['info', 'governor']])
342+
>>> data = [
343+
... {
344+
... "state": "Florida",
345+
... "shortname": "FL",
346+
... "info": {"governor": "Rick Scott"},
347+
... "counties": [
348+
... {"name": "Dade", "population": 12345},
349+
... {"name": "Broward", "population": 40000},
350+
... {"name": "Palm Beach", "population": 60000},
351+
... ],
352+
... },
353+
... {
354+
... "state": "Ohio",
355+
... "shortname": "OH",
356+
... "info": {"governor": "John Kasich"},
357+
... "counties": [
358+
... {"name": "Summit", "population": 1234},
359+
... {"name": "Cuyahoga", "population": 1337},
360+
... ],
361+
... },
362+
... ]
363+
>>> result = pd.json_normalize(
364+
... data, "counties", ["state", "shortname", ["info", "governor"]]
365+
... )
336366
>>> result
337367
name population state shortname info.governor
338368
0 Dade 12345 Florida FL Rick Scott
@@ -341,8 +371,8 @@ def _json_normalize(
341371
3 Summit 1234 Ohio OH John Kasich
342372
4 Cuyahoga 1337 Ohio OH John Kasich
343373
344-
>>> data = {'A': [1, 2]}
345-
>>> pd.json_normalize(data, 'A', record_prefix='Prefix.')
374+
>>> data = {"A": [1, 2]}
375+
>>> pd.json_normalize(data, "A", record_prefix="Prefix.")
346376
Prefix.0
347377
0 1
348378
1 2

‎pandas/io/json/_table_schema.py

+24-19
Original file line numberDiff line numberDiff line change
@@ -155,21 +155,25 @@ def convert_json_field_to_pandas_type(field):
155155
156156
Examples
157157
--------
158-
>>> convert_json_field_to_pandas_type({'name': 'an_int',
159-
'type': 'integer'})
158+
>>> convert_json_field_to_pandas_type({"name": "an_int", "type": "integer"})
160159
'int64'
161-
>>> convert_json_field_to_pandas_type({'name': 'a_categorical',
162-
'type': 'any',
163-
'constraints': {'enum': [
164-
'a', 'b', 'c']},
165-
'ordered': True})
166-
'CategoricalDtype(categories=['a', 'b', 'c'], ordered=True)'
167-
>>> convert_json_field_to_pandas_type({'name': 'a_datetime',
168-
'type': 'datetime'})
160+
161+
>>> convert_json_field_to_pandas_type(
162+
... {
163+
... "name": "a_categorical",
164+
... "type": "any",
165+
... "constraints": {"enum": ["a", "b", "c"]},
166+
... "ordered": True,
167+
... }
168+
... )
169+
CategoricalDtype(categories=['a', 'b', 'c'], ordered=True)
170+
171+
>>> convert_json_field_to_pandas_type({"name": "a_datetime", "type": "datetime"})
169172
'datetime64[ns]'
170-
>>> convert_json_field_to_pandas_type({'name': 'a_datetime_with_tz',
171-
'type': 'datetime',
172-
'tz': 'US/Central'})
173+
174+
>>> convert_json_field_to_pandas_type(
175+
... {"name": "a_datetime_with_tz", "type": "datetime", "tz": "US/Central"}
176+
... )
173177
'datetime64[ns, US/Central]'
174178
"""
175179
typ = field["type"]
@@ -245,12 +249,13 @@ def build_table_schema(
245249
... 'C': pd.date_range('2016-01-01', freq='d', periods=3),
246250
... }, index=pd.Index(range(3), name='idx'))
247251
>>> build_table_schema(df)
248-
{'fields': [{'name': 'idx', 'type': 'integer'},
249-
{'name': 'A', 'type': 'integer'},
250-
{'name': 'B', 'type': 'string'},
251-
{'name': 'C', 'type': 'datetime'}],
252-
'pandas_version': '0.20.0',
253-
'primaryKey': ['idx']}
252+
{'fields': \
253+
[{'name': 'idx', 'type': 'integer'}, \
254+
{'name': 'A', 'type': 'integer'}, \
255+
{'name': 'B', 'type': 'string'}, \
256+
{'name': 'C', 'type': 'datetime'}], \
257+
'primaryKey': ['idx'], \
258+
'pandas_version': '0.20.0'}
254259
"""
255260
if index is True:
256261
data = set_default_names(data)

0 commit comments

Comments
 (0)