Работа с данными в формате JSON в Python

Перевод статьи Working With JSON Data in Python.
Начиная с момента своего создания JSON быстро стал стандартом де-факто для обмена данными между приложениями, а также их частями. И скорее всего вы читаете эту статью потому, что вам необходимо куда либо передать/принять данные или возможно вы через API своего приложения обрабатываете информацию в формате JSON, а затем сохраняете её. Так или иначе, но вы наконец добрались до этого непонятного JSON и теперь вам необходимо обработать данные в этом формате с помощью Python. К счастью это достаточно простая задача, и как в большинстве подобных случаев Python делает ее выполнение легким.

Итак, мы собираемся использовать JSON для хранения и обмена данными. JSON — это не что иное, как стандартизованный формат, который сообщество разработчиков уже достаточно давно использует для передачи и хранения данных. Имейте в виду, что JSON — не единственное решение, использующееся для подобного рода задач, но вероятно только XML и YAML являются единственными альтернативами о которых стоит упомянуть в первую очередь.

(Очень) Краткое введение в JSON

JavaScript Object Notation (JSON) создавался под влиянием парадигм языка JavaScript и связан с ним схожим синтаксисом описания объектного литерала. Существует отличный сайт, который введет вас в курс дела. Тем не менее JSON уже давно отделился от языка Javascript и существует как собственный стандарт, поэтому в этой статье мы можем с удовольствием избежать обсуждения особенностей программирования на JavaScript. В конечном итоге сообщество разработчиков в целом приняло JSON, так как его легко создавать, а также понимать как людям так и машинам.

Внимание, это JSON!

Файлы в формате JSON доступны для чтения и записи средствами всех языков программирования Cи-стиля, а Python как раз является таковым! Ниже приводится фрагмент кода, содержащий личные данные пользователя в виде литерала объекта и закодированного в формате JSON.

{
    "firstName": "Jane",
    "lastName": "Doe",
    "hobbies": ["running", "sky diving", "singing"],
    "age": 35,
    "children": [
        {
            "firstName": "Alice",
            "age": 6
        },
        {
            "firstName": "Bob",
            "age": 8
        }
    ]
}

Как не трудно заметить, JSON поддерживает примитивные типы данных, такие как строки и числа, а также сложные: списки и объекты с произвольной вложенностью. Синтаксис представленного выше кода схож с синтаксисом словаря Python, то есть является универсальной нотацией для описания объектов.

Python изначально поддерживает JSON!

Изначально Python поставляется со стандартным (встроенным) модулем json для кодирования и декодирования данных в формате JSON. Для этого просто вставьте в начале вашего файла с кодом программы следующие инструкции:

import json

Основные термины

Процесс кодирования JSON называется сериализацией (serialization). Этот термин обозначает преобразование данных в линейную последовательность байтов для хранения на диске или передачи по сети. Интересуясь материалами по этой тематике, вы также могли слышать термин «маршалинг» (marshaling), но это уже тема для отдельной статьи.

Соответственно, десериализация (deserialization) является обратным процессом, а технически декодированием данных из формата JSON в  структуру данных в памяти.

На самом деле проще думать об этих двух взаимообратимых процессах как об обыкновенном чтении и записи данных: кодирование предназначено для записи данных на диск (или передачи по сети), а декодирование — для чтения данных в память и последующей обработки.

Сериализация JSON

Модуль json предоставляет удобный метод dump() для записи данных в файл. Существует также метод dumps() для записи данных в обычную строку. Типы данных Python кодируются в формат JSON в соответствии с интуитивно понятными правилами преобразования, представленными в виде таблице ниже.

Python	JSON
dict	object
list,tuple	array
str	string
int, long, float	number
True	true
False	false
None	null

Пример простой процедуры сериализации данных

Теперь представим, что мы работаем в памяти с объектом следующего вида:

data = {
    "president": {
        "name": "Zaphod Beeblebrox",
        "species": "Betelgeusian"
    }
}

Нам необходимо сохранить эту информацию на диске, то есть записать ее в файл. Используя диспетчер контекстов Python сначала создадим файл, например, с именем data_file.json, а затем откроем его в режиме записи:

with open("data_file.json", "w") as write_file:
    json.dump(data, write_file)

Обратите внимание, на то что методdump() принимает два аргумента: объект данных, подлежащий сериализации и файлоподобный объект, в который они затем будут записаны после кодирования.

Если вы захотите далее использовать сериализованные данные в своем приложении, вы можете записать их в обычную строку типа  str. Для этого используйте следующий код:

json_string = json.dumps(data)

Обратите внимание, второй аргумент который содержит ссылку на файлоподобный объект для записи в коде выше отсутствует, так данные не записываются на диск, а сохраняются в переменной json_string. Кроме этой особенности, во всем остальном методdumps() аналогичен dump().

Некоторые полезные именованные аргументы

Напомним JSON должен быть легко читаем для людей. Но что если наши данные будут упакованы в одну строку без отступов и разделения по отдельным строкам. Кроме всего этого, у вас вероятно имеется свой стиль форматирования (styleguide) или же вам проще читать код отформатированный по вашим правилам.

ПРИМЕЧАНИЕ. Оба метода dump() и dumps() используют одни и те же именованные аргументы.

Первая опция, которую большинство людей хочет изменить — это количество пробельных символов в отступе. Вы можете использовать именованный аргумент indent, для того чтобы указать размер отступа во вложенных структурах. Используя данные, которые мы передали переменной data, выполните следующие команды в консоли, а затем сравните результат выполнения обеих инструкций:

>>> json.dumps(data)
>>> json.dumps(data, indent=4)

Другая популярная опция для изменения стиля форматирования — использование именованного аргумента separators. По умолчанию в качестве разделителей в файлах JSON используется строка, состоящая из двух символов: «, » или «: » (символ + символ пробел). Альтернативным способом  придания файлу более компактного вида является использование разделителей в виде строк вида: «,» и «:» (без пробела в конце). Выполнив в качестве примера в консоли команды, приведенные выше, и задав новое значение аргумента separators, можно заметить, как вид разделителей изменит форматирование ваших данных.

Десериализация JSON

В модуле json определены методы load() и loads(), предназначенные для преобразования кодированных в формате JSON данных в объекты Python. Подобно операции сериализации, также существует таблица преобразования типов, определяющая правила для обратного декодирования данных. Хотя вероятно вы уже наверное догадались, как она будет выглядеть:

JSON	Python
object	dict
array	list
string	str
number (int)	int
number (real)	float
true	True
false	False
null	None

Технически это преобразование не является в точности обратным к таблице для сериализации данных, рассмотренной нами выше. Это означает, что если вы кодируете объект в формат JSON, а затем декодируете его обратно, то вы можете получить уже не тот объект, каким он был изначально. Простым иллюстрирующим этот факт примером будет кодирование данных с типа кортеж tuple и получение после декодирования данных с типа список list:

>>> blackjack_hand = (8, "Q")
>>> encoded_hand = json.dumps(blackjack_hand)
>>> decoded_hand = json.loads(encoded_hand)

>>> blackjack_hand == decoded_hand
False
>>> type(blackjack_hand)

>>> type(decoded_hand)

>>> blackjack_hand == tuple(decoded_hand)
True

Простой пример десериализации данных

Представим теперь, что у вас есть данные, хранящиеся на диске в виде файла, которые вы хотели бы обрабатывать в памяти. Как в задаче выше вы также можете использовать диспетчер контекста, но на этот раз для того, чтобы открыть существующий файл data_file.json в режиме чтения:

with open("data_file.json", "r") as read_file:
    data = json.load(read_file)

Здесь все довольно просто, но имейте в виду, что результат выполнения этого кода будет возвращать результат декодирования, в соответствии с нашей таблицей преобразования типов данных. Об этом важно помнить если вы загружаете из файла данные, состав которых вам заранее неизвестен.

В большинстве случаев корневой объект будет представлять собой объект типа словарь dictили список list. Допустим, что вы получаете данные в формате JSON из другой программы или ваш код Python должен обработать строку данных типа str в формате JSON. В этом случае вы можете легко десериализовать их с помощью методаloads(). В приведенном ниже коде, данные просто загружаются из строки и затем декодируются:

json_string = """
{
    "researcher": {
        "name": "Ford Prefect",
        "species": "Betelgeusian",
        "relatives": [
            {
                "name": "Zaphod Beeblebrox",
                "species": "Betelgeusian"
            }
        ]
    }
}
"""
data = json.loads(json_string)

Пример (как бы) из реальной жизни

Для демонстрации нашего «реального» примера мы будем использовать online-сервис JSONPlaceholder. Он представляет собой удаленный источник данных в формате JSON, получаемых по сети по запросу, и могут использоваться для отладки приложений. Вначале создадим файл сценария с именем scratch.py или под любым другим именем. Нам необходимо будет сформировать запрос request к служебному API JSONPlaceholder, для этого мы будем использовать модуль requests. Просто добавьте инструкции импорта в начало файла:

import json
import requests

Запросим у  JSONPlaceholder список задач TODO, обращаясь через интерфейс его API, относительно входной точки /todos. Если вы не знакомы с модулем requests, вы можете использовать другой удобный метод json(), который выполнит эту же задачу. В нашем же примере мы будем использовать модуль json для десериализации атрибута text объекта ответа response, полученного с помощью модуля requests. Код нашего примера будет выглядеть следующим образом:

response = requests.get("https://jsonplaceholder.typicode.com/todos")
todos = json.loads(response.text)

Запустите файл в интерактивном режиме с помощью командной строки. Сделав это, проверьте тип объекта todos, а также содержимое элементов списка значений.

>>> todos == response.json()
True
>>> type(todos)

>>> todos[:10]

Вы также можете просмотреть содержимое входных данных с помощью браузера, перейдя во входную точку сервиса по следующей ссылке — TODO:

{
    "userId": 1,
    "id": 1,
    "title": "delectus aut autem",
    "completed": false
}

JSONPlaceholder генерирует набор данных содержащий: список пользователей, каждый из которых имеет уникальный идентификатор userId, а также  поле completed (статус задачи) с типом Boolean. Как определить какие пользователи выполнили наибольшее количество задач? Представленный ниже код поможет определить это:

# таблица userId пользователей полностью выполнивших все задачи из TODO
todos_by_user = {}

# Подсчет количества задач из списка TODO выполненных каждым пользователем
for todo in todos:
    if todo["completed"]:
        try:
            # Суммируем количество выполненных пользователем задач.
            todos_by_user[todo["userId"]] += 1
        except KeyError:
            # Этот пользователь ничего не сделал. Зададим количество выполненных задач равным 1.
            todos_by_user[todo["userId"]] = 1

# Создадим сортированный список пар значений (userId, num_complete)
top_users = sorted(todos_by_user.items(), 
                   key=lambda x: x[1], reverse=True)

# Зададим максимальное количество выполненных задач TODO в списке
max_complete = top_users[0][1]

# Создадим список list всех пользователей, которые имеют максимальное количество выполненных задач из списка TODO 
users = []
for user, num_complete in top_users:
    if num_complete 
                
Теперь мы можем манипулировать данными прочитанными из файла в формате JSON и декодированными как с обыкновенным объектом Python. Если мы запустим следующие инструкции в консоли, то получим:
                
>>> s = "s" if len(users) > 1 else ""
>>> print(f"user{s} {max_users} completed {max_complete} TODOs")
users 5 and 10 completed 12 TODOs
# пользователи 5 и 10 выполнили 12 задач из TODO
                
Далее создадим файл JSON, который будет содержать заполненные списки задач TODO для каждого из пользователей, которые завершили максимальное количество задач из списка. Все, что теперь нужно сделать отфильтровать задачи todos и записать полученный список в файл. Назовём файл с результатами обработки данных filter_data_file.json. Существует несколько способов, которыми можно это сделать. Ниже приведен код одного из них:
                
# Определим функцию для фильтрации списка пользователей,
# выполнивших максимальное количество заданий из TODO
def keep(todo):
    is_complete = todo["completed"]
    has_max_count = todo["userId"] in users
    return is_complete and has_max_count

# Запишем отфильтрованные данные в файл
with open("filtered_data_file.json", "w") as data_file:
    filtered_todos = list(filter(keep, todos))
    json.dump(filtered_todos, data_file, indent=2)
                
Отлично, мы сохранили нужные нам данные в файл, отфильтровав все лишнее. Запустите сценарий еще раз и проверьте файл filter_data_file.json, чтобы убедиться, что все работает так как нужно. Он будет создан в том же каталоге, что и файл scratch.py.
                

                
                
Кодирование и декодирование пользовательских объектов Python
                
Рассмотрим следующий пример и затем ответим на вопрос. Что произойдёт если мы попытаемся сериализовать класс Elf из приложения Dungeons & Dragons, фрагмент кода которого представлен ниже?
                
class Elf:
    def __init__(self, level, ability_scores=None):
        self.level = level
        self.ability_scores = {
            "str": 11, "dex": 12, "con": 10,
            "int": 16, "wis": 14, "cha": 13
        } if ability_scores is None else ability_scores
        self.hp = 10 + self.ability_scores["con"]
                
Не удивительно, но Python пожалуется, что Elf не может быть сериализован (not serializable):
                
>>> elf = Elf(level=4)
>>> json.dumps(elf)
TypeError: Object of type 'Elf' is not JSON serializable
                
И хотя модуль json может обрабатывать большинство встроенных типов данных Python, но по умолчанию он не понимает, как кодировать сложные пользовательские типы данных. Со стороны наш код похож на попытку поместить квадратный штифт в круглое отверстие. Как решать подобные задачи рассмотрим ниже.
                
Упрощение структур данных
                
Как работать со сложными структурами данных? Вы можете попытаться кодировать и декодировать JSON вручную контролируя весь процесс, но есть более изящное решение, которое сэкономит ваше время. Вместо того, чтобы попытаться напрямую перейти от пользовательского типа данных к формату JSON с неизвестным результатом, вы можете сделать это через следующий промежуточный шаг.
                
Все, что вам нужно сделать, это представить ваши данные с точки зрения встроенных в Python (нативных) типов данных, которые модуль json отлично понимает. По сути, вы должны перевести сложный объект в более простое представление, которое затем модуль json трансформирует в JSON. Это похоже на транзитивное свойство отношений элементов в математике: если A = B и B = C, то A = C.
                
Чтобы опробовать этот прием, нам понадобится любой сложный объект для кодирования. Для примера вы можете использовать любой пользовательский класс, который вам нравится. Но мы используем для этого встроенный в Python тип complex, который применяется для представления комплексных чисел. И по умолчанию он в принципе не сериализуем.
                
>>> z = 3 + 8j
>>> type(z)

>>> json.dumps(z)
TypeError: Object of type 'complex' is not JSON serializable
                
Теперь необходимо задать себе очень важный вопрос. Каков минимальный объем информации, нам необходим для воссоздания объекта? В случае комплексных чисел вам нужно знать значения реальных и мнимых частей числа, которые вы можете получить как атрибуты объекта типа complex:
                
>>> z.real
3.0
>>> z.imag
8.0
                
После передачи полученных значений в конструктор complex() оператор сравнения __eq__ вернёт нам значение True:
                
>>> complex(3, 8) == z
True
                
Разбиение пользовательских типов данных до отдельных составляющих, состоящих из значений простых базовых типов, имеет решающее значение для успешного результата работы процессов сериализации и десериализации.
                
Кодирование пользовательских типов данных
                
Для преобразования данных пользовательского типа в формат JSON нам необходимо предусмотреть отдельную функцию для их кодирования. Далее ее имя передается через именованный параметр default в метод dump(). Модуль json будет вызывать эту функцию для любых объектов, которые не могут быть сериализованы способом по умолчанию. Вот, например, простая функция кодирования, которую вы можете использовать на практике:
                
def encode_complex(z):
    if isinstance(z, complex):
        return (z.real, z.imag)
    else:
        type_name = z.__class__.__name__
        raise TypeError(f"Object of type '{type_name}' is not JSON serializable")
                
Обратите внимание, на то что вы должны генерировать исключение TypeError, если вдруг не получите объект ожидаемого типа. Посмотрим, что получится при использовании нашей функции кодирования encode_complex().
                
>>> json.dumps(9 + 5j, default=encode_complex)
'[9.0, 5.0]'
>>> json.dumps(elf, default=encode_complex)
TypeError: Object of type 'Elf' is not JSON serializable
                
Почему же мы кодировали комплексное число как кортеж (tuple)? Хороший вопрос. Это, безусловно, не единственный и не лучший выбор. На самом деле, это не очень хорошее представление данных, в особенности если захотите позже декодировать полученный результат. И вы вскоре убедитесь в этом. Другой общий подход заключается в применении подкласса стандартного класса JSONEncoder и переопределении его метода default():
                
class ComplexEncoder(json.JSONEncoder):
    def default(self, z):
        if isinstance(z, complex):
            return (z.real, z.imag)
        else:
            super().default(self, z)
                
Вместо того, чтобы генерировать исключения типа TypeError, вы можете позволить базовому классу обработать его. Используйте этот прием либо непосредственно при вызове метода dumps() через именованный параметр cls, либо путем создания экземпляра encoder (кодера) и вызова его метода encode():
                
>>> json.dumps(2 + 5j, cls=ComplexEncoder)
'[2.0, 5.0]'

>>> encoder = ComplexEncoder()
>>> encoder.encode(3 + 6j)
'[3.0, 6.0]'
                
Декодирование пользовательских типов данных
                
Хотя знать значения реальных и мнимых частей комплексного числа необходимо для воссоздания объекта типа complex , но на практике этого может оказаться недостаточно. Например, попытаемся кодировать в формате JSON комплексное число с помощью класса ComplexEncoder , а затем декодировать результат в виде объекта Python:
                
>>> complex_json = json.dumps(4 + 17j, cls=ComplexEncoder)
>>> json.loads(complex_json)
[4.0, 17.0]
                
Из этого кода видно, что если вы захотите получить объект с типом complex, то полученный список значений list необходимо затем передать в соответствующий конструктор complex(). Таким образом для достоверного декодирования JSON нам необходимо заранее знать структуру типа данных пользовательского объекта.
                
Что же нам неизвестно ещё? В рассмотренном нами случае отсутствуют метаданные или информация о типе декодируемых данных. Теперь еще раз зададим себе вопрос: Каков минимальный объем информации, который необходим и достаточен для восстановления этого объекта?
                
Модуль json ожидает, что все пользовательские типы данных будут отображаться как обычные объекты. Создадим файл JSON  complex_data.json и добавим туда объект, представляющий собой комплексное число:
                
{
    "__complex__": true,
    "real": 42,
    "imag": 36
}
                
Ключ __complex__— это метаданные, о которых мы говорили выше. На самом деле не важно с каким значением он ассоциирован. Чтобы этот маленький хак работал, все, что вам нужно это проверить существует ли этот ключ:
                
def decode_complex(dct):
    if "__complex__" in dct:
        return complex(dct["real"], dct["imag"])
    return dct
                
Если ключа __complex__ нет в словаре, вы можете просто вернуть объект или осуществить преобразование декодером по умолчанию. Каждый раз когда метод loads() пытается проанализировать объект object, вам предоставляется возможность изменить его поведение перед тем как декодер по умолчанию начнет работать с данными. Вы можете сделать это, передав вашу собственную функцию декодирования через именованный параметр object_hook. Запустим на выполнение следующий код:
                
>>> with open("complex_data.json") as complex_data:
...     data = complex_data.read()
...     z = json.loads(data, object_hook=decode_complex)
... 
>>> type(z)

                
И хотя параметр object_hook по результатам работы может показаться аналогичным параметру default метода dump(), однако это не так. Этот код работает не только с одним объектом. Попробуйте поместить список (list) объектов комплексных чисел в complex_data.json и снова запустить скрипт:
                
[
  {
    "__complex__":true,
    "real":42,
    "imag":36
  },
  {
    "__complex__":true,
    "real":64,
    "imag":11
  }
]
                
Если ваш код не содержит ошибок, то вы получите список объектов типа complex:
                
>>> with open("complex_data.json") as complex_data:
...     data = complex_data.read()
...     numbers = json.loads(data, object_hook=decode_complex)
... 
>>> numbers
[(42+36j), (64+11j)]
                
Вы также можете использовать подкласс класса JSONDecoder и переопределить его метод object_hook, но лучше всего придерживаться самого простого решения.
                

                
                
Все готово
                
Поздравляю теперь вы можете использовать всю мощь формата JSON для реализации ваших приложений на языке Python.
                
Хотя примеры которыми мы рассмотрели, безусловно, чрезмерно упрощены, но иллюстрируют основы процесса работы с форматом данных JSON. Информация изложенная в этой статье поможет вам решить следующие задачи:
                

                  
Импорт модуля json.
                  
Чтение данных с использованием методов load() или loads().
                  
Обработка данных.
                  
Запись измененных данных с помощью методов dump() или dumps().
                
                
Рассмотрение особенностей использования стандартного модуля json упростит вам изучение других модулей Python, использующихся для сериализации данных: pickle и marshal.
                
Удачи вам в дальнейшем изучении языка Python!