pandas.read_json

pandas.read_json(path_or_buf, *, orient=None, typ='frame', dtype=None, convert_axes=None, convert_dates=True, keep_default_dates=True, precise_float=False, date_unit=None, encoding=None, encoding_errors='strict', lines=False, chunksize=None, compression='infer', nrows=None, storage_options=None, dtype_backend=_NoDefault.no_default, engine='ujson')

将 JSON 字符串转换为 pandas 对象。

Parameters:

path_or_buf有效的 JSON 字符串、路径对象或文件类对象

任何有效的字符串路径均可接受。字符串可以是一个 URL。有效的 URL 方案包括 http、ftp、s3 和 file。对于文件 URL，需要主机名。本地文件可以是：file://localhost/path/to/table.json。

如果要传入路径对象，pandas 接受任何 os.PathLike。

我们所说的“类文件对象”指的是具有 read() 方法的对象，例如文件句柄（例如通过内置 open 函数）或 StringIO。

自 2.1.0 版本弃用: 传递 JSON 字面量字符串已弃用。

orientbool, default False

指示预期的 JSON 字符串格式。兼容的 JSON 字符串可以由具有相应 orient 值的 to_json() 生成。可能的一组 orient 是：

• 'split'：字典形式，类似于 {index -> [index], columns -> [columns], data -> [values]}

• 'records'：列表形式，类似于 [{column -> value}, ... , {column -> value}]

• 'index'：字典形式，类似于 {index -> {column -> value}}

• 'columns'：字典形式，类似于 {column -> {index -> value}}

• 'values'：仅包含值数组

• 'table'：字典形式，类似于 {'schema': {schema}, 'data': {data}}

允许的 orient 值和默认值取决于 typ 参数的值。

• 当 typ == 'series' 时，

  • 允许的 orient 为 {'split','records','index'}

  • 默认值为 'index'

  • 对于 orient 'index'，Series 索引必须唯一。

• 当 typ == 'frame' 时，

  • 允许的 orient 为 {'split','records','index', 'columns','values', 'table'}

  • 默认值为 'columns'

  • 对于 orient 'index' 和 'columns'，DataFrame 索引必须唯一。

  • 对于 orient 'index'、'columns' 和 'records'，DataFrame 列必须唯一。

typ{‘frame’, ‘series’}, 默认 ‘frame’

要恢复的对象类型。

dtype布尔值或字典, 默认 None

如果为 True，则推断 dtypes；如果为字典（列到 dtype），则使用这些；如果为 False，则根本不推断 dtypes，仅适用于数据。

对于所有 orient 值（除了 'table'），默认值为 True。

convert_axes布尔值，默认为 None

尝试将轴转换为正确的 dtype。

对于所有 orient 值（除了 'table'），默认值为 True。

convert_datesbool or list of str, default True

如果为 True，则默认的日期类列可能会被转换（取决于 keep_default_dates）。如果为 False，则不会转换日期。如果为列名列表，则这些列将被转换，并且默认的日期类列也可能被转换（取决于 keep_default_dates）。

keep_default_datesbool, default True

如果正在解析日期（convert_dates 不为 False），则尝试解析默认的日期类列。当列标签具有以下特征时，被认为是日期类：

• 以 '_at' 结尾，

• 以 '_time' 结尾，

• 以 'timestamp' 开头，

• 是 'modified'，或者

• 是 'date'。

precise_floatbool，默认 False

设置为启用将字符串解码为双精度值时使用更高精度的 (strtod) 函数。默认值 (False) 使用快速但精度较低的内置功能。

date_unitstr，默认 None

用于检测日期转换时的时间戳单位。默认行为是尝试检测正确的精度，但如果不需要，则传递 ‘s’、’ms’、’us’ 或 ‘ns’ 中的一个，分别强制解析秒、毫秒、微秒或纳秒。

encodingstr，默认为 ‘utf-8’

用于解码 py3 字节串所使用的编码。

encoding_errorsstr，可选，默认为 “strict”

如何处理编码错误。List of possible values 。

在 1.3.0 版本加入.

linesbool，默认 False

将文件读取为每行一个 json 对象。

chunksizeint, optional

返回 JsonReader 对象用于迭代。有关 chunksize 的更多信息，请参阅 line-delimited json docs 。仅当 lines=True 时才能传递此参数。如果为 None，则将文件全部读入内存。

compressionstr or dict, default ‘infer’

用于对磁盘数据进行即时解压缩。如果为 ‘infer’ 且 ‘path_or_buf’ 是路径状，则从以下扩展名检测压缩：’.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ 或 ‘.tar.bz2’ (否则不压缩)。如果使用 ‘zip’ 或 ‘tar’，ZIP 文件必须只包含一个数据文件才能读取。设置为 None 表示不进行解压缩。也可以是一个字典，其中 ‘method’ 键设置为 {'zip', 'gzip', 'bz2', 'zstd', 'xz', 'tar'} 中的一个，并且其他键值对将转发给 zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor, lzma.LZMAFile 或 tarfile.TarFile，分别。例如，可以传递以下内容来使用自定义压缩字典进行 Zstandard 解压缩：compression={'method': 'zstd', 'dict_data': my_compression_dict}。

在 1.5.0 版本加入: 增加了对 .tar 文件的支持。

在 1.4.0 版本发生变更: Zstandard 支持。

nrowsint, optional

需要读取的逐行 JSON 文件中的行数。仅当 lines=True 时才能传递此参数。如果为 None，则返回所有行。

storage_optionsdict, 可选

适用于特定存储连接的额外选项，例如主机、端口、用户名、密码等。对于 HTTP(S) URL，键值对将作为标头选项转发给 urllib.request.Request。对于其他 URL（例如，以 “s3://”, 和 “gcs://” 开头的 URL），键值对将转发给 fsspec.open。更多详情请参阅 fsspec 和 urllib，有关存储选项的更多示例，请参阅 here 。

dtype_backend{‘numpy_nullable’, ‘pyarrow’}, 默认 ‘numpy_nullable’

应用于结果 DataFrame 的后端数据类型（仍处于实验阶段）。行为如下：

• "numpy_nullable"：返回支持可空 dtype 的 DataFrame （默认）。

• "pyarrow"：返回 pyarrow 支持的可空 ArrowDtype DataFrame。

在 2.0 版本加入.

engine{“ujson”, “pyarrow”}，默认为 “ujson”

要使用的解析引擎。仅当 lines=True 时才可使用 "pyarrow" 引擎。

在 2.0 版本加入.

Returns:

Series, DataFrame, 或 pandas.api.typing.JsonReader

当 chunksize 不为 0 或 None 时，返回 JsonReader。否则，返回的类型取决于 typ 的值。

参见

DataFrame.to_json

将 DataFrame 转换为 JSON 字符串。

Series.to_json

将 Series 转换为 JSON 字符串。

json_normalize

将半结构化的 JSON 数据规范化为扁平表。

Notes

Specific to orient='table', if a DataFrame with a literal Index name of index gets written with to_json(), the subsequent read operation will incorrectly set the Index name to None. This is because index is also used by DataFrame.to_json() to denote a missing Index name, and the subsequent read_json() operation cannot distinguish between the two. The same limitation is encountered with a MultiIndex and any names beginning with 'level_'.

Examples

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

使用 'split' 格式的 JSON 进行 DataFrame 的编码/解码：

>>> df.to_json(orient='split')
    '{"columns":["col 1","col 2"],"index":["row 1","row 2"],"data":[["a","b"],["c","d"]]}'
>>> pd.read_json(StringIO(_), orient='split')
      col 1 col 2
row 1     a     b
row 2     c     d

使用 'index' 格式的 JSON 进行 Dataframe 的编码/解码：

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

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

使用 'records' 格式的 JSON 进行 Dataframe 的编码/解码。请注意，使用此编码时，索引标签不会被保留。

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

使用表模式进行编码

>>> df.to_json(orient='table')
    '{"schema":{"fields":[{"name":"index","type":"string"},{"name":"col 1","type":"string"},{"name":"col 2","type":"string"}],"primaryKey":["index"],"pandas_version":"1.4.0"},"data":[{"index":"row 1","col 1":"a","col 2":"b"},{"index":"row 2","col 1":"c","col 2":"d"}]}'

以下示例使用 dtype_backend="numpy_nullable"

>>> data = '''{"index": {"0": 0, "1": 1},
...        "a": {"0": 1, "1": null},
...        "b": {"0": 2.5, "1": 4.5},
...        "c": {"0": true, "1": false},
...        "d": {"0": "a", "1": "b"},
...        "e": {"0": 1577.2, "1": 1577.1}}'''
>>> pd.read_json(StringIO(data), dtype_backend="numpy_nullable")
   index     a    b      c  d       e
0      0     1  2.5   True  a  1577.2
1      1  <NA>  4.5  False  b  1577.1