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:допустимая строка 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:str, необязательный

Указание ожидаемого формата строки 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, определять типы данных; если передан словарь «столбец — тип данных», использовать указанные типы; если False, не определять типы данных. Применяется только к данным.

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

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

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

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

convert_dates:bool или список str, по умолчанию 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

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

date_unit:str, по умолчанию None

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

encoding:str, по умолчанию ‘utf-8’

Кодировка для декодирования байтов py3.

encoding_errors:str, необязательный, по умолчанию “strict”

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

Добавлено в версии 1.3.0.

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

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

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

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

compression: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}.

Добавлено в версии 1.5.0: Добавлена поддержка файлов .tar.

Изменено в версии 1.4.0: Добавлена поддержка Zstandard.

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

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

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

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

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

Тип данных серверной части для результирующего объекта DataFrame (функциональность пока экспериментальная). Поведение следующее:

• "numpy_nullable": возвращает DataFrame с типами данных, поддерживающими пропущенные значения (по умолчанию).

• "pyarrow": возвращает DataFrame с nullable-типами ArrowDtype на основе pyarrow.

Добавлено в версии 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 с использованием JSON в формате 'split':

>>> 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 с использованием JSON в формате 'index':

>>> 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 с использованием JSON в формате 'records'. Обратите внимание, что при таком кодировании метки индекса не сохраняются.

>>> 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