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=<no_default>, engine='ujson')

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

参数:

path_or_buf一个字符串路径、路径对象或类文件对象

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

如果你想传递一个路径对象，pandas 接受任何 os.PathLike。

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

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

orientstr, 可选

预期JSON字符串格式的指示。兼容的JSON字符串可以通过 to_json() 生成，并带有相应的orient值。可能的orient集合是：

• 'split' : 类似字典 {index -> [index], columns -> [columns], data -> [values]}

• 'records' : 类似列表 [{列 -> 值}, ... , {列 -> 值}]

• 'index' : 类似字典 {index -> {column -> value}}

• 'columns' : 类似字典 {column -> {index -> value}}

• 'values' : 仅值数组

• 'table' : 类似字典 {'schema': {schema}, 'data': {data}}

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

• 当 typ == 'series' 时

  • 允许的方向是 {'split','records','index'}

  • 默认是 'index'

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

• 当 typ == 'frame' 时，

  • 允许的方向是 {'split','records','index', 'columns','values', 'table'}

  • 默认是 'columns'

  • DataFrame 索引对于 orients 'index' 和 'columns' 必须是唯一的。

  • 对于 orients 'index', 'columns', 和 'records'，DataFrame 的列必须是唯一的。

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

要恢复的对象类型。

dtype布尔值或字典，默认无

如果为True，则推断数据类型；如果是一个列到数据类型的字典，则使用这些数据类型；如果为False，则完全不推断数据类型，仅适用于数据。

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

convert_axes布尔值，默认为 None

尝试将轴转换为适当的dtypes。

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

convert_datesbool 或 str 列表, 默认 True

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

keep_default_dates布尔值, 默认为 True

如果解析日期（convert_dates 不是 False），则尝试解析默认的日期类列。列标签是日期类的，如果

• 它以 '_at' 结尾，

• 它以 '_time' 结尾，

• 它以 'timestamp' 开始。

• 它是 'modified'，或者

• 这是 'date'。

precise_floatbool, 默认 False

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

date_unitstr, 默认为 None

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

编码str, 默认是 ‘utf-8’

用于解码 py3 字节的编码。

encoding_errorsstr, 可选, 默认 “strict”

如何处理编码错误。 可能的值列表 。

Added in version 1.3.0.

行bool, 默认 False

逐行将文件读取为json对象。

chunksizeint, 可选

返回用于迭代的 JsonReader 对象。有关 chunksize 的更多信息，请参阅 行分隔的 json 文档。只有在 lines=True 时才能传递此参数。如果此参数为 None，文件将一次性全部读入内存。

压缩str 或 dict，默认 ‘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}。

Added in version 1.5.0: 增加了对 .tar 文件的支持。

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

nrowsint, 可选

需要读取的行分隔的 json 文件的行数。这只有在 lines=True 时才能传递。如果这是 None，将返回所有行。

storage_optionsdict, 可选

对于特定存储连接有意义的额外选项，例如主机、端口、用户名、密码等。对于HTTP(S) URL，键值对会作为头选项转发到 urllib.request.Request。对于其他URL（例如以“s3://”和“gcs://”开头），键值对会转发到 fsspec.open。请参阅 fsspec 和 urllib 获取更多详细信息，关于存储选项的更多示例请参考 这里。

dtype_backend{‘numpy_nullable’, ‘pyarrow’}

应用于结果 DataFrame 的后端数据类型（仍在实验中）。如果未指定，默认行为是不使用可空数据类型。如果指定，行为如下：

• "numpy_nullable": 返回支持可空数据类型的 DataFrame

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

Added in version 2.0.

引擎{“ujson”, “pyarrow”}，默认 “ujson”

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

Added in version 2.0.

返回:

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

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

参见

DataFrame.to_json

将 DataFrame 转换为 JSON 字符串。

Series.to_json

将一个 Series 转换为 JSON 字符串。

json_normalize

将半结构化的 JSON 数据规范化成一个扁平的表格。

备注

特定于 orient='table'，如果一个带有字面 Index 名称为 index 的 DataFrame 通过 to_json() 写入，随后的读取操作将错误地将 Index 名称设置为 None。这是因为 index 也被 DataFrame.to_json() 用来表示缺失的 Index 名称，随后的 read_json() 操作无法区分这两者。同样的限制也出现在 MultiIndex 和任何以 'level_' 开头的名称上。

示例

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

使用 'split' 格式化 JSON 编码/解码一个数据框：

>>> 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')  # noqa: F821
      col 1 col 2
row 1     a     b
row 2     c     d

使用 'index' 格式化的 JSON 编码/解码一个数据帧：

>>> 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')  # noqa: F821
      col 1 col 2
row 1     a     b
row 2     c     d

使用 'records' 格式化的 JSON 编码/解码一个数据帧。请注意，此编码不会保留索引标签。

>>> df.to_json(orient='records')
'[{"col 1":"a","col 2":"b"},{"col 1":"c","col 2":"d"}]'
>>> pd.read_json(StringIO(_), orient='records')  # noqa: F821
  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