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')[source]

Преобразовать строку JSON в объект pandas.

Параметры:

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 устарела.

orient:строка, необязательно

Указание ожидаемого формата строки JSON. Совместимые строки JSON могут быть созданы с помощью to_json() со соответствующим значением orient. Набор возможных значений 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}}

Допустимые и значения по умолчанию зависят от значения параметра typ.

• когда typ == 'series',

  • допустимые значения orient — {'split','records','index'}

  • значение по умолчанию — 'index'

  • Индекс Series должен быть уникальным для orient 'index'.

• когда typ == 'frame',

  • допустимые значения orient — {'split','records','index', 'columns','values', 'table'}

  • значение по умолчанию — 'columns'

  • Индекс DataFrame должен быть уникальным для значений orient 'index' и 'columns'.

  • Столбцы DataFrame должны быть уникальными для значений orient 'index', 'columns' и 'records'.

typ:{‘frame’, ‘series’}, по умолчанию ‘frame’

Тип объекта для восстановления.

dtype:bool или dict, по умолчанию None

Если True, то типы данных будут выведены; если dict со столбцом и типом данных, то будут использованы эти типы данных; если False, то типы данных не будут выводиться, это относится только к данным.

Для всех orient значений, кроме 'table', значение по умолчанию — True.

convert_axes:bool, по умолчанию None

Попытка преобразовать оси к соответствующим типам данных.

Для всех orient значений, кроме 'table', значение по умолчанию — True.

convert_dates:bool или список строк, по умолчанию True

Если True, то стандартные столбцы типа дата могут быть преобразованы (в зависимости от keep_default_dates). Если False, даты не будут преобразованы. Если список имен столбцов, то эти столбцы будут преобразованы, и стандартные столбцы типа дата также могут быть преобразованы (в зависимости от keep_default_dates).

keep_default_dates:bool, по умолчанию True

Если происходит парсинг дат (convert_dates не False), то попробуйте разобрать стандартные столбцы типа дата. Столбец является столбцом типа дата, если:

• он заканчивается на '_at',

• он заканчивается на '_time',

• он начинается с 'timestamp',

• он является 'modified', или

• он является 'date'.

precise_float:bool, по умолчанию False

Установите в значение True, чтобы использовать функцию большей точности (strtod) при декодировании строки в значения double. Значение по умолчанию (False) — использовать быструю, но менее точную встроенную функциональность.

date_unit:строка, по умолчанию None

Единица измерения временной метки для определения преобразования дат. По умолчанию, поведение заключается в попытке определить правильную точность, но если это нежелательно, то передайте одно из ‘s’, ‘ms’, ‘us’ или ‘ns’ для принудительного преобразования только секунд, миллисекунд, микросекунд или наносекунд соответственно.

encoding:строка, по умолчанию ‘utf-8’

Кодировка для декодирования py3 bytes.

encoding_errors:строка, необязательно, по умолчанию “strict”

Как обрабатываются ошибки кодирования. Список возможных значений.

Введено в версии 1.3.0.

lines:bool, по умолчанию False

Считать файл как объект JSON в строке.

chunksize:int, необязательно

Возвращает объект JsonReader для итерации. См. документацию по строковым JSON для получения дополнительной информации о chunksize. Это можно передать только если lines=True. Если это None, весь файл будет считан в память сразу.

compression:строка или dict, по умолчанию ‘infer’

Для сжатия данных на диске на лету. Если ‘infer’, а ‘path_or_buf’ является объектом пути, то обнаружить сжатие из следующих расширений: ‘.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ или ‘.tar.bz2’ (иначе нет сжатия). Если используется ‘zip’ или ‘tar’, то ZIP-файл должен содержать только один файл данных для чтения. Установите в None для отключения сжатия. Также может быть dict со значением ключа '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.

nrows:int, необязательно

Количество строк из файла line-delimited json, которые должны быть прочитаны. Это можно передать только если lines=True. Если это None, будут возвращены все строки.

storage_options:dict, необязательно

Дополнительные параметры, имеющие смысл для конкретного подключения к хранилищу, например, хост, порт, имя пользователя, пароль и т. д. Для HTTP(S) URL-адресов пары ключ-значение передаются в urllib.request.Request в качестве параметров заголовка. Для других URL-адресов (например, начинающихся с «s3://» и «gcs://») пары ключ-значение передаются в fsspec.open. Дополнительные сведения см. в fsspec и urllib. Для получения более подробных примеров параметров хранилища см. здесь.

dtype_backend:{‘numpy_nullable’, ‘pyarrow’}, по умолчанию ‘numpy_nullable’

Обработчик типа данных, применяемый к результирующему DataFrame (по-прежнему экспериментально). Поведение следующее:

• "numpy_nullable": возвращает DataFrame с поддержкой nullable-dtype (по умолчанию).

• "pyarrow": возвращает DataFrame с поддержкой pyarrow и nullable ArrowDtype.

Введено в версии 2.0.

engine:{“ujson”, “pyarrow”}, по умолчанию “ujson”

Двигатель парсера для использования. Двигатель "pyarrow" доступен только при lines=True.

Введено в версии 2.0.

Возвращает:

Series, DataFrame или pandas.api.typing.JsonReader

JsonReader возвращается, когда chunksize не 0 или None. В противном случае возвращаемый тип зависит от значения typ.

См. также

DataFrame.to_json

Преобразовать DataFrame в строку JSON.

Series.to_json

Преобразовать Series в строку JSON.

json_normalize

Нормализовать полуструктурированные данные JSON в плоскую таблицу.

Примечания

Специфично для orient='table', если DataFrame с буквальным именем Index index записывается с 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'])

Кодирование/декодирование DataFrame с использованием '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')
      col 1 col 2
row 1     a     b
row 2     c     d

Кодирование/декодирование DataFrame с использованием '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')
      col 1 col 2
row 1     a     b
row 2     c     d

Кодирование/декодирование DataFrame с использованием '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')
  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