robust json
v.1.2.7
Пакет Robust-json — это легкая, но функциональная библиотека для работы с файлами и объектами JSON в Python.
Вы можете установить этот пакет непосредственно из PyPI:
pip install robust-json
Эта библиотека поддерживается только в Python 3.x.
Если вы хотите улучшить этот проект, сначала обсудите свою идею, открыв новый выпуск. После этого создайте форк этого репозитория и реализуйте эту замечательную функцию или исправьте эту досадную ошибку. Затем создайте новый PR и дождитесь одобрения.
Примечание: пожалуйста, сначала прочитайте файл Conting.md. Там вы можете найти кодекс поведения и полезную информацию о процессе внесения взносов.
Эта библиотека включает в себя 4 модуля:
Этот модуль предоставляет различные методы для работы с файлами JSON через класс JsonFileParser . Он автоматически анализирует и загружает действительный JSON из указанного файла, а также проверяет, готов ли файл к обработке. Чтобы получить к нему доступ, просто импортируйте JsonFileParser из файлового модуля:
from robust_json.file import JsonFileParser
и инициализируем его:
op = JsonFileParser(path_to_json_file)
Примечание. JsonFileParser теперь поддерживает автосохранение. Если этот параметр включен, модуль будет сохранять активный объект после каждого внесенного в него изменения и записывать его в указанный файл.
Чтобы включить автосохранение, просто инициализируйте этот модуль, установив для параметра autosave значение True :
op = JsonFileParser(path_to_json_file, autosave=True)
Примечание: вы также можете указать файл для автосохранения. Просто передайте параметр autosave_path с путем к вашему файлу во время инициализации, например:
op = JsonFileParser(path*to_json_file, autosave=True, autosave_path=path_to_autosave_file)
Если файл не существует, модуль создаст его. Если файл существует, он будет обрезан и заполнен сериализованным активным объектом.
Во время инициализации может возникнуть исключение JSONFileError . Это означает, что парсер не смог обработать содержимое указанного файла или файл имеет неподдерживаемое расширение. Также на этом этапе может возникнуть сообщение FileNotFoundError , указывающее, что указанный файл не существует. Исключение IncorrectFunctionParameterTypeError будет вызвано, если один или несколько параметров имеют неправильные типы.
Характеристики :
JsonFileParser.file_formats В этом свойстве перечислены все расширения файлов, поддерживаемые этим модулем, в виде массива. На данный момент поддерживаются только файлы .json и .txt . Это используется во время инициализации класса, чтобы определить, можно ли обработать файл.
JsonFileParser.path Это свойство возвращает путь к исходному файлу.
JsonFileParser.active_json Это свойство возвращает объект JSON со всеми последними изменениями.
JsonFileParser.backup Это свойство возвращает исходный объект JSON, игнорируя все недавние изменения. Эти два последних свойства могут сбить с толку, поэтому вот пример ( Примечание: см. соответствующий раздел документации для функции JsonFileParser.append() ):
from robust_json.file import JsonFileParser
op = JsonFileParser('test1.json') #Class initialization
# Contents of 'test1.json' file: {'test_key': 'test_value'}
op.append('$', {'append_key': 'append_value'})
print(op.active_json)
# Output: {'test_key': 'test_value', 'append_key': 'append_value'}
print(op.backup)
# Output: {'test_key': 'test_value'}
# As you can see, JsonFileParser.backup property is equal to initial contents of 'test1.json' file.
# This is useful when there is a need to discard all changes to JSON object.
Методы :
JsonFileParser.get_json_from_file() Этот метод извлекает весь JSON из файла и возвращает его в виде словаря Python. Он вызывается автоматически при первой обработке указанного файла.
from robust_json.file import JsonFileParser
op = JsonFileParser('test1.json') # JsonFileParser.get_json_from_file() function is called here
JsonFileParser.get_key_value(json_path: str) Этот метод получает доступ к значению из определенной пары ключ:значение в объекте JSON и возвращает его. Параметр json_path:str указывает путь к паре ключ:значение (например, field0.field1.[...].fieldn). Пример:
from robust_json.file import JsonFileParser
op = JsonFileParser('test2.json')
# Contents of 'test2.json' file: {'test_key': 'test_value', 'test_arr': [1, 2, 3]}
val = op.get_key_value('test_key')
print(val)
# Output: 'test_value'
# You can use this method to retrieve an element from JSON array
val = op.get_key_value('test_arr[1]')
print(val)
# Output: 2
Эта функция вызовет ошибку IncorrectFunctionParameterTypeError , если ее параметр имеет неверный тип. Эта функция также вызовет ошибку JSONPathError , если указанный путь JSON недействителен (не существует или к нему невозможно получить доступ).
JsonFileParser.append(json_path: str, Append_value: Any, Append_at_end: bool = False) Этот метод добавляет значение к существующему объекту JSON и возвращает словарь Python с обновленным содержимым. Параметр json_path:str указывает путь, по которому будет добавлено новое значение. Чтобы добавить значение в корень объекта JSON, json_path должен быть равен '$'. append_value:любой параметр указывает значение, которое будет добавлено. append_at_end:bool управляет поведением этой функции в отношении массивов объектов JSON (такие структуры: [{}, {}, {}, ...]) и общих массивов (такие структуры: [a, b, c, . ..]). Никакого влияния на другие структуры он не оказывает. Если установлено значение False, функция попытается добавить заданное значение к каждому объекту массива. Если установлено значение True, функция попытается добавить заданное значение в конец массива. (см. примеры ниже). Эта функция вернет словарь Python с обновленным JSON.
Эта функция вызовет исключение IncorrectFunctionParameterTypeEroor , если ее параметр(-ы) имеет(-ve) неправильный тип. Эта функция также вызовет исключение ValueError , если «добавленное значение» пусто (равно пустой строке, пустому массиву, пустому словарю и т. д.). Эта функция вызовет _JSONPathError , если предоставленный путь недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Добавление простой пары ключ:значение в корень объекта
from robust_json.file import JsonFileParser
op = JsonFileParser('test3.json')
# Contents of 'test3.json' file: {'test_key': 'test_value'}
op.append('$', {'add_key': 'add_var'})
print(op.active_json)
# Output: {'test_key': 'test_value', 'add_key': 'add_var'}
Добавление нового объекта в массив объектов
from robust_json.file import JsonFileParser
op = JsonFileParser('users.json')
# Contents of 'users.json' file: {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}]}
op.append('users', {'id': 3, 'name': 'Liza'})
print(op.active_json)
# Output: {'users': [{'id': 3, 'name': 'Lisa'}, {'id': 3, 'name': 'Lisa'}]}
# This is not good!
# This happened because 'append_at_end' parameter is set to False.
# Function appended new object to each of the objects in the array and new values have overwritten the old
# ones.
# Note: we can discard these unwanted/malicious changes using JsonFileParser.reset() function with
# its parameter set to True. (please refer to corresponding section in docs)
op.reset(True)
print(op.active_json)
# Output: {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}]}
# We need to set 'append_at_end' parameter to True to avoid this.
op.append('users', {'id': 3, 'name': 'Liza'}, True)
print(op.active_json)
# Output: {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}, {'id': 3, 'name': 'Lisa'}]}
Добавление пары ключ:значение к каждому объекту массива
from robust_json.file import JsonFileParser
op = JsonFileParser('users.json')
# Contents of 'users.json' file: {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}]}
op.append('users', {'role': 'guest'})
print(op.active_json)
# Output: {'users':[{'id':1, 'name':'Ken', 'role':'guest'}, {'id':2, 'name':'Alec', 'role':'guest'}]}
Добавление нового элемента в массив элементов:
from robust_json.file import JsonFileParser
op = JsonFileParser('test4.json')
# Contents of 'test4.json' file: {'colors': ['cyan', 'magenta']}
op.append('colors', 'yellow')
print(op.active_json)
# Output: {'colors': ['cyan', 'magenta']}
# Nothing happened.
# That's because 'append_at_end' parameter is set to False.
# Function tried to append new string to each string and failed.
# To fix this, we need to set 'append_at_end' parameter to True.
op.append('colors', 'yellow', True)
print(op.active_json)
# Output: {'colors': ['cyan', 'magenta', 'yellow']}
JsonFileParser.update_value(json_path: str, key_or_index: Union[str, int], new_value: любой, strict_mode: bool = False)
Эта функция обновит значение в паре ключ:значение и вернет словарь Python с обновленным содержимым. Параметр json_path:str указывает путь к паре ключ:значение/массиву/и т. д. родительский элемент, который необходимо обновить. (Чтобы обновить значение в корне объекта JSON, json_path должен быть равен '$'), а параметр key_or_index:Union[str, int] указывает ключ (если это объект) или индекс массива (если это массив). Это означает, что если нам нужно обновить ключ с путем «field0.field1.upd key», то _json_path будет равен «field0.field1», а параметр key_or_index будет равен «upd key». _Примечание: если вы используете индекс массива, когда параметр «json_path» указывает на объект JSON, или если вы используете имя свойства, когда «json_path» указывает на массив JSON, будет возбуждено исключение (см. примеры ниже). new_value:any указывает значение, которое перезапишет старое, а strict_mode:bool включает строгий режим. По умолчанию этот режим отключен. Если этот метод включен, этот метод будет гарантировать, что новое значение имеет тот же тип, что и старое (если старое значение является строкой, то новое значение также должно быть строкой и т. д.). Если типы не совпадают, будет возбуждено исключение.
Эта функция вызовет исключение IncorrectFunctionParameterTypeError , если ее параметр(-ы) имеет(-ve) неправильный тип. Эта функция также вызовет JSONStrictModeError в случае несовпадения типов, если включен строгий режим, и исключение JSONPathError , если путь JSON недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Обновление пары ключ:значение в корне объекта:
from robust_json.file import JsonFileParser
op = JsonFileParser('test5.json')
# Contents of 'test5.json' file: {'app_name': 'HomeCare', 'version', '1.0.0'}
op.update_value('$', 'version': '1.0.5')
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'version': '1.0.5'}
Обновление элемента в массиве:
from robust_json.file import JsonFileParser
op = JsonFileParser('test6.json')
# Contents of 'test6.json' file: {'app_name': 'HomeCare', 'authors': ['Alec Hammer', 'Nick Rogers']}
op.update_value('authors', 1, 'Nick Rogerson')
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'authors': ['Alec Hammer', 'Nick Rogerson']}
# Note: if you don't know the index of an item, you can use
# 'get_item_index()' function from 'robust_json.ext' module to get it.
# (See corresponding section in the docs)
from robust_json.file import JsonFileParser
import robust_json.ext as ext
op = JsonFileParser('test6.json')
# Contents of 'test6.json' file: {'app_name': 'HomeCare', 'authors': ['Alec Hammer', 'Nick Rogers']}
# Getting an array for future use
authors_array = op.get_key_value('authors')
print(authors_array)
# Output: ['Alec Hammer', 'Nick Rogers']
# Finding the index
index = ext.get_item_index('Alec Hammer', authors_array, False)
print(index)
# Output: 0
#Updating value
op.update_value('authors', index, 'Alain Hammer')
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'authors': ['Alain Hammer', 'Nick Rogers']}
Обновление значения в строгом режиме:
from robust_json.file import JsonFileParser
op = JsonFileParser('test6.json')
# Contents of 'test6.json' file: {'app_name': 'HomeCare', 'app_id': 1077}
op.update_value('$', 'app_id', 'this is a string', True)
# A 'StrictModeError' exception was raised.
# This happened because new value has a different type.
# Let's try again, but with integer.
op.update_value('$', 'app_id', 1080, True)
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'app_id': 1080}
JsonFileParser.delete(json_path: str, key_or_index: Union[str, int]) Эта функция удалит элемент из JSON и вернет словарь Python с обновленным содержимым. Параметр json_path:str указывает путь к паре ключ:значение/массиву/и т.д. родительский элемент, который необходимо удалить. (Чтобы удалить значение в корне объекта JSON, json_path должен быть равен '$'), а параметр key_or_index:Union[str, int] указывает ключ (если это объект) или индекс массива (если это массив). Это означает, что если нам нужно удалить ключ с путем «field0.field1.del key», то _json_path будет равен «field0.field1», а параметр key_or_index будет равен «del key». _Примечание: если вы используете индекс массива, когда параметр «json_path» указывает на объект JSON, или если вы используете имя свойства, когда «json_path» указывает на массив JSON, будет возбуждено исключение (см. примеры ниже). Эта функция вызовет исключение IncorrectFunctionParameterTypeError , если ее параметр(-ы) имеет(-ve) неправильный тип. Эта функция также вызовет исключение JSONPathError , если путь JSON недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Удаление пары ключ:значение в корне объекта:
from robust_json.file import JsonFileParser
op = JsonFileParser('test7.json')
# Contents of 'test5.json' file: {'test_key': 'test_val', 'del_key': 'del_val'}
op.delete('$', 'del_key')
print(op.active_json)
# Output: {'test_key': 'test_val'}
Удаление элемента в массиве:
from robust_json.file import JsonFileParser
op = JsonFileParser('test8.json')
# Contents of 'test6.json' file: {'app_name': 'PetShopify', 'authors': ['Alec Hammer', 'Nick Rogers']}
op.delete('authors', 1)
print(op.active_json)
# Output: {'app_name': 'PetShopify', 'authors': ['Alec Hammer']}
# Note: if you don't know the index of an item, you can use 'get_item_index()'
# function from 'robust_json.ext' module to get it. (See corresponding section in the docs)
from robust_json.file import JsonFileParser
import robust_json.ext as ext
op = JsonFileParser('test9.json')
# Contents of 'test6.json' file: {'app_name': 'PetShopify', 'authors': ['Alec Hammer', 'Nick Rogers']}
# Getting an array for future use
authors_array = op.get_key_value('authors')
print(authors_array)
# Output: ['Alec Hammer', 'Nick Rogers']
# Finding the index
index = ext.get_item_index('Alec Hammer', authors_array, False)
print(index)
# Output: 0
#Updating value
op.delete('authors', index)
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'authors': ['Nick Rogers']}
JsonFileParser.minify() Эта функция удалит все отступы в файле JSON. По сути, он сжимает весь JSON в одну строку.
Эта функция не возвращает никакого значения.
JsonFileParser.prettify(indent: int = 4) Эта функция добавит отступы к JSON в исходном файле, чтобы улучшить его читаемость. Параметр indent:int указывает количество пробелов. По умолчанию оно равно 4. Эта функция является полной противоположностью JsonFileParser.minify().
Эта функция не возвращает никакого значения.
Эта функция вызовет ошибку IncorrectFunctionParameterTypeError , если ее параметр имеет неверный тип.
JsonFileParser.reset(discard_active_object: bool = False) Эта функция сбросит активный объект JSON, удалив все внесенные в него изменения. Параметр ignore_active_object:bool управляет поведением этой функции относительно активного объекта JSON (свойство JsonFileParser.active_json). Если установлено значение False, этот метод просто вернет исходный объект и сохранит все изменения в активном JSON. Если установлено значение True, эта функция все равно вернет исходный объект, но также сбросит активный, и все изменения исчезнут навсегда.
Эта функция вызовет ошибку IncorrectFunctionParameterTypeError , если ее параметр имеет неправильный тип.
Примеры:
Получение исходного объекта и сохранение его в переменной:
from robust_json.file import JsonFileParser
op = JsonFileParser('test10.json')
# Contents of `test10.json` file: { "simple_key": "simple_value" }
op.append('$', { "test_arr": [1, 2, 3] })
# We appended key:value pair to distinguish objects among each other.
initial = op.reset()
print(initial)
# initial = { "simple_key": "simple_value" }
print(op.active_json)
# Output: { "simple_key": "simple_value", "test_arr": [1, 2, 3] }
# Calling this method without parameters simply makes it return initial
# object, saving the active one for future use.
Получение исходного объекта и сброс активного:
from robust_json.file import JsonFileParser
op = JsonFileParser('test10.json')
# Contents of `test10.json` file: { "simple_key": "simple_value" }
op.append('$', { "test_arr": [1, 2, 3] })
# We appended key:value pair to distinguish objects among each other.
initial = op.reset(True)
print(initial)
# Output: { "simple_key": "simple_value" }
print(op.active_json)
# Output: { "simple_key": "simple_value" }
# Calling this method with 'discard_active_object' set to True.
# makes it completely revert all changes to active object, making it
# equal to the initial one.
# Warning!
# Note: if called with 'discard_active_object' set to True, there
# is no way of going back. All changes will be gone for good.
# Please use this with extreme caution!
JsonFileParser.save_to_file(path: str = None, prettify: bool = True, create_file: bool = False) Эта функция сохранит активный объект JSON в файл. Параметр path:str указывает путь к файлу. Если оставить пустым, активный объект будет сохранен в исходный файл. Параметр prettify:bool включает отступы. По умолчанию установлено значение True. Если установлено значение False, JSON будет сжат в одну строку. Параметр create_file:bool включает создание файла. Если установлено значение True, эта функция создаст новый файл и сохранит там активный объект, но только в том случае, если параметр пути указывает на несуществующий файл. Примечание. Если для параметра create_file установлено значение True и путь указывает на существующий файл, будет возбуждено исключение.
Эта функция вызовет JSONFileError , если конечный файл не поддерживает JSON (имеет неподдерживаемое расширение). Эта функция вызовет FileExistsError , если для параметра create_file установлено значение True и файл уже существует по указанному пути. Эта функция вызовет FileNotFoundError , если для параметра create_file установлено значение False и файл не может быть найден по указанному пути. Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Сохранение активного объекта в исходный файл:
from robust_json.file import JsonFileParser
op = JsonFileParser('data.json')
# Contents of 'data.json' file: {'name': 'Helen Anderson', 'employee_id': 107756}
op.update_value('$', 'employee_id', 107744)
print(op.active_json)
# Output: {'name': 'Helen Anderson', 'employee_id': 107744}
op.save_to_file()
# Contents of 'data.json' file: {'name': 'Helen Anderson', 'employee_id': 107744}
# Calling 'save_to_file' method without any arguments makes it
# overwrite an object in source file ('data.json' in this case)
# with the value of JsonFileParser.active_json property.
Сохранение активного объекта в другой файл (существующий):
from robust_json.file import JsonFileParser
op = JsonFileParser('data.json')
# Contents of 'data.json' file: {'name': 'Helen Anderson', 'employee_id': 107756}
op.update_value('$', 'employee_id', 107744)
print(op.active_json)
# Output: {'name': 'Helen Anderson', 'employee_id': 107744}
op.save_to_file(path='new_data.json')
# Contents of 'new_data.json' file: {'name': 'Helen Anderson', 'employee_id': 107744}
# Calling this function with different 'path' parameter will
# make this function save the value of JsonFileParser.active_json property into
# existing file ('new_data.json' in this case). But if file cannot be found, a 'FileNotFoundError'
# exception will be raised.
Сохранение активного объекта в другой файл (несуществующий):
from robust_json.file import JsonFileParser
op = JsonFileParser('data.json')
# Contents of 'data.json' file: {'name': 'Helen Anderson', 'employee_id': 107756}
op.update_value('$', 'employee_id', 107744)
print(op.active_json)
# Output: {'name': 'Helen Anderson', 'employee_id': 107744}
op.save_to_file(path='new_data.json')
# A 'FileNotFoundError' exception has been raised.
# It happened because this file does not exist.
# To fix this we need to set 'create_file' parameter to True.
op.save_to_file(path='new_data.json', create_file=True)
# Contents of 'new_data.json' file: {'name': 'Helen Anderson', 'employee_id': 107744}
# Calling the function with 'create_file' set to True and different path makes it create
# a new file and save the value of JsonFileParser.active_json property there.
# But if file already exists, a 'FileExistsError' will be raised.
Этот модуль предоставляет различные методы для работы с объектом JSON непосредственно через класс JsonObjectParser . Этот класс специально разработан для работы с JSON, полученным из вызовов API, или для использования в API. Чтобы получить к нему доступ, просто импортируйте JsonObjectParser из файлового модуля:
from robust_json.object import JsonObjectParser
и инициализируем его:
op = JsonObjectParser(json_obj)
Примечание. JsonObjectParser теперь поддерживает автосохранение. Если этот параметр включен, модуль будет сохранять активный объект после каждого внесенного в него изменения и записывать его в указанный файл.
Чтобы включить автосохранение, просто инициализируйте этот модуль, установив для параметра autosave значение True :
op = JsonObjectParser(json_object, autosave=True)
Примечание: вы также можете указать файл для автосохранения. Просто передайте параметр autosave_path с путем к вашему файлу во время инициализации, например:
op = JsonObjectParser(json_object, autosave=True, autosave_path=path_to_autosave_file)
Если файл не существует, модуль создаст его. Если файл существует, он будет обрезан и заполнен сериализованным активным объектом.
Во время инициализации может возникнуть исключение IncorrectFunctionParameterTypeError . Это означает, что параметр json имеет неверный тип.
Характеристики :
JsonObjectParser.active_json Это свойство возвращает объект JSON со всеми последними изменениями.
JsonObjectParser.backup Это свойство возвращает исходный объект JSON, игнорируя все недавние изменения. Эти два последних свойства могут сбить с толку, поэтому вот пример ( Примечание: см. соответствующий раздел документации для функции JsonObjectParser.append() ):
from robust_json.object import JsonObjectParser
obj = {'test_key': 'test_value'}
op = JsonObjectParser(obj) #Class initialization
op.append('$', {'append_key': 'append_value'})
print(op.active_json)
# Output: {'test_key': 'test_value', 'append_key': 'append_value'}
print(op.backup)
# Output: {'test_key': 'test_value'}
# As you can see, JsonObjectParser.backup property is equal to initial object.
# This is useful when there is a need to discard all changes to JSON object.
Методы :
JsonObjectParser.get_key_value(json_path: str) Этот метод получает доступ к значению из определенной пары ключ:значение в объекте JSON и возвращает его. Параметр json_path:str указывает путь к паре ключ:значение (например, field0.field1.[...].fieldn). Пример:
from robust_json.object import JsonObjectParser
obj = {'test_key': 'test_value', 'test_arr': [1, 2, 3]}
op = JsonObjectParser(obj)
val = op.get_key_value('test_key')
print(val)
# Output: 'test_value'
# You can use this method to retrieve an element from JSON array
val = op.get_key_value('test_arr[1]')
print(val)
# Output: 2
Эта функция вызовет ошибку IncorrectFunctionParameterTypeError , если ее параметр имеет неверный тип. Эта функция также вызовет ошибку JSONPathError , если указанный путь JSON недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
JsonObjectParser.append(json_path: str, Append_value: Any, Append_at_end: bool = False) Этот метод добавляет значение к существующему объекту JSON и возвращает словарь Python с обновленным содержимым. Параметр json_path:str указывает путь, по которому будет добавлено новое значение. Чтобы добавить значение в корень объекта JSON, json_path должен быть равен '$'. append_value:любой параметр указывает значение, которое будет добавлено. append_at_end:bool управляет поведением этой функции в отношении массивов объектов JSON (такие структуры: [{}, {}, {}, ...]) и общих массивов (такие структуры: [a, b, c, . ..]). Никакого влияния на другие структуры он не оказывает. Если установлено значение False, функция попытается добавить заданное значение в каждый объект массива. Если установлено значение True, функция попытается добавить заданное значение в конец массива. (см. примеры ниже). Эта функция вернет словарь Python с обновленным JSON.
Эта функция вызовет исключение IncorrectFunctionParameterTypeEroor , если ее параметр(-ы) имеет(-ve) неправильный тип. Эта функция также вызовет исключение ValueError , если «добавленное значение» пусто (пустая строка, пустой массив, пустой словарь). Эта функция вызовет _JSONPathError , если предоставленный путь недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Добавление простой пары ключ:значение в корень объекта
from robust_json.object import JsonObjectParser
obj = {'test_key': 'test_value'}
op = JsonObjectParser(obj)
op.append('$', {'add_key': 'add_var'})
print(op.active_json)
# Output: {'test_key': 'test_value', 'add_key': 'add_var'}
Добавление нового объекта в массив объектов
from robust_json.object import JsonObjectParser
obj = {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}]}
op = JsonObjectParser(obj)
op.append('users', {'id': 3, 'name': 'Liza'})
print(op.active_json)
# Output: {'users': [{'id': 3, 'name': 'Lisa'}, {'id': 3, 'name': 'Lisa'}]}
# This is not good!
# This happened because 'append_at_end' parameter is set to False.
# Function appended new object to each of the objects in the array and new values overwrote the old
# ones.
# Note: we can discard these unwanted/malicious changes using JsonObjectParser.reset() function with
# its parameter set to True. (please refer to corresponding section in docs)
op.reset(True)
print(op.active_json)
# Output: {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}]}
# We need to set 'append_at_end' parameter to True to avoid this.
op.append('users', {'id': 3, 'name': 'Liza'}, True)
print(op.active_json)
# Output: {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}, {'id': 3, 'name': 'Lisa'}]}
Добавление пары ключ:значение к каждому объекту массива
from robust_json.object import JsonObjectParser
obj = {'users': [{'id': 1, 'name': 'Ken'}, {'id': 2, 'name': 'Alec'}]}
op = JsonObjectParser(obj)
op.append('users', {'role': 'guest'})
print(op.active_json)
# Output: {'users':[{'id':1, 'name':'Ken', 'role':'guest'}, {'id':2, 'name':'Alec', 'role':'guest'}]}
Добавление нового элемента в массив элементов:
from robust_json.object import JsonObjectParser
obj = {'colors': ['cyan', 'magenta']}
op = JsonObjectParser(obj)
op.append('colors', 'yellow')
print(op.active_json)
# Output: {'colors': ['cyan', 'magenta']}
# Nothing happened
# That's because 'append_at_end' parameter is set to False
# Function tried to append new string to each string and failed
# To fix this, we need to set 'append_at_end' parameter to True
op.append('colors', 'yellow', True)
print(op.active_json)
# Output: {'colors': ['cyan', 'magenta', 'yellow']}
JsonObjectParser.update_value(json_path: str, key_or_index: Union[str, int], new_value: Any, strict_mode: bool = False)
Эта функция обновит значение в паре ключ:значение и вернет словарь Python с обновленным содержимым. Параметр json_path:str указывает путь к паре ключ:значение/массиву/и т. д. родительский элемент, который необходимо обновить. (Чтобы обновить значение в корне объекта JSON, json_path должен быть равен '$'), а параметр key_or_index:Union[str, int] указывает ключ (если это объект) или индекс массива (если это массив). Это означает, что если нам нужно обновить ключ с путем «field0.field1.upd key», то _json_path будет равен «field0.field1», а параметр key_or_index будет равен «upd key». _Примечание: если вы используете индекс массива, когда параметр «json_path» указывает на объект JSON, или если вы используете имя свойства, когда «json_path» указывает на массив JSON, будет возбуждено исключение (см. примеры ниже). new_value:any указывает значение, которое перезапишет старое, а strict_mode:bool включает строгий режим. По умолчанию этот режим отключен. Если этот метод включен, этот метод будет гарантировать, что новое значение имеет тот же тип, что и старое (если старое значение является строкой, то новое значение также должно быть строкой и т. д.). Если типы не совпадают, будет возбуждено исключение.
Эта функция вызовет исключение IncorrectFunctionParameterTypeError , если ее параметр(-ы) имеет(-ve) неверный тип. Эта функция также вызовет JSONStrictModeError в случае несовпадения типов, если включен строгий режим, и исключение JSONPathError , если путь JSON недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Обновление пары ключ:значение в корне объекта:
from robust_json.object import JsonObjectParser
op = JsonObjectParser({'app_name': 'HomeCare', 'version', '1.0.0'})
op.update_value('$', 'version': '1.0.5')
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'version': '1.0.5'}
Обновление элемента в массиве:
from robust_json.object import JsonObjectParser
op = JsonObjectParser({'app_name': 'HomeCare', 'authors': ['Alec Hammer', 'Nick Rogers']})
op.update_value('authors', 1, 'Nick Rogerson')
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'authors': ['Alec Hammer', 'Nick Rogerson']}
# Note: if you don't know the index of an item, you can use 'get_item_index()'
# function from 'robust_json.ext' module to get it. (See corresponding section in the docs)
from robust_json.object import JsonObjectParser
import robust_json.ext as ext
op = JsonObjectParser({'app_name': 'HomeCare', 'authors': ['Alec Hammer', 'Nick Rogers']})
# Getting an array for future use
authors_array = op.get_key_value('authors')
print(authors_array)
# Output: ['Alec Hammer', 'Nick Rogers']
# Finding the index
index = ext.get_item_index('Alec Hammer', authors_array, False)
print(index)
# Output: 0
#Updating value
op.update_value('authors', index, 'Alain Hammer')
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'authors': ['Alain Hammer', 'Nick Rogers']}
Обновление значения в строгом режиме:
from robust_json.object import JsonObjectParser
op = JsonObjectParser({'app_name': 'HomeCare', 'app_id': 1077})
op.update_value('$', 'app_id', 'this is a string', True)
# An 'StrictModeError' was raised
# This happened because new value has a different type
# Let's try again, but with integer
op.update_value('$', 'app_id', 1080, True)
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'app_id': 1080}
JsonObjectParser.delete(json_path: str, key_or_index: Union[str, int]) Эта функция удалит элемент из JSON и вернет словарь Python с обновленным содержимым. Параметр json_path:str указывает путь к паре ключ:значение/массиву/и т. д. родительский элемент, который необходимо удалить. (Чтобы удалить значение в корне объекта JSON, json_path должен быть равен '$'), а параметр key_or_index:Union[str, int] указывает ключ (если это объект) или индекс массива (если это массив). Это означает, что если нам нужно удалить ключ с путем «field0.field1.del key», то _json_path будет равен «field0.field1», а параметр key_or_index будет равен «del key». _Примечание: если вы используете индекс массива, когда параметр «json_path» указывает на объект JSON, или если вы используете имя свойства, когда «json_path» указывает на массив JSON, будет возбуждено исключение (см. примеры ниже). Эта функция вызовет исключение IncorrectFunctionParameterTypeError , если ее параметр(-ы) имеет(-ve) неверный тип. Эта функция также вызовет исключение JSONPathError , если путь JSON недействителен (не существует или к нему невозможно получить доступ). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Удаление пары ключ:значение в корне объекта:
from robust_json.object import JsonObjectParser
obj = {'test_key': 'test_val', 'del_key': 'del_val'}
op = JsonObjectParser(obj)
op.delete('$', 'del_key')
print(op.active_json)
# Output: {'test_key': 'test_val'}
Удаление элемента в массиве:
from robust_json.object import JsonObjectParser
op = JsonObjectParser('test8.json')
# Contents of 'test6.json' file: {'app_name': 'PetShopify', 'authors': ['Alec Hammer', 'Nick Rogers']}
op.delete('authors', 1)
print(op.active_json)
# Output: {'app_name': 'PetShopify', 'authors': ['Alec Hammer']}
# Note: if you don't know the index of an item, you can use 'get_item_index()'
# function from 'robust_json.ext' module to get it. (See corresponding section in the docs)
from robust_json.object import JsonObjectParser
import robust_json.ext as ext
obj = {'app_name': 'PetShopify', 'authors': ['Alec Hammer', 'Nick Rogers']}
op = JsonObjectParser(obj)
# Getting an array for future use
authors_array = op.get_key_value('authors')
print(authors_array)
# Output: ['Alec Hammer', 'Nick Rogers']
# Finding the index
index = ext.get_item_index('Alec Hammer', authors_array, False)
print(index)
# Output: 0
#Updating value
op.delete('authors', index)
print(op.active_json)
# Output: {'app_name': 'HomeCare', 'authors': ['Nick Rogers']}
JsonObjectParser.reset(discard_active_object: bool = False) Эта функция сбросит активный объект JSON, удалив все внесенные в него изменения. Параметр ignore_active_object:bool управляет поведением этой функции относительно активного объекта JSON (свойство JsonObjectParser.active_json). Если установлено значение False, этот метод просто вернет исходный объект и сохранит все изменения в активном JSON. Если установлено значение True, эта функция все равно вернет исходный объект, но также сбросит активный, и все изменения исчезнут навсегда.
Эта функция вызовет ошибку IncorrectFunctionParameterTypeError , если ее параметр имеет неверный тип. Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Получение исходного объекта и сохранение его в переменной:
from robust_json.object import JsonObjectParser
obj = { "simple_key": "simple_value" }
op = JsonObjectParser(obj)
op.append('$', { "test_arr": [1, 2, 3] })
# We appended key:value pair to distinguish objects among each other
initial = op.reset()
print(initial)
# initial = { "simple_key": "simple_value" }
print(op.active_json)
# Output: { "simple_key": "simple_value", "test_arr": [1, 2, 3] }
# Calling this method without parameters simply makes it return initial
# object, saving the active one for future use
Получение исходного объекта и сброс активного:
from robust_json.object import JsonObjectParser
obj = { "simple_key": "simple_value" }
op = JsonObjectParser(obj)
op.append('$', { "test_arr": [1, 2, 3] })
# We appended key:value pair to distinguish objects among each other
initial = op.reset(True)
print(initial)
# Output: { "simple_key": "simple_value" }
print(op.active_json)
# Output: { "simple_key": "simple_value" }
# Calling this method with 'discard_active_object' set to True
# makes it completely revert all changes to active object, making it
# equal to the initial one.
# Warning!
# Note: if called with 'discard_active_object' set to True, there
# is no way of going back. All changes will be gone for good.
# Please use this with extreme caution!
JsonObjectParser.save_to_file(path: str, prettify: bool = True, create_file: bool = False) Эта функция сохранит активный объект JSON в файл. Параметр path:str указывает путь к файлу. Параметр prettify:bool включает отступы. По умолчанию установлено значение True. Если установлено значение False, JSON будет сжат в одну строку. Параметр create_file:bool включает создание файла. Если установлено значение True, эта функция создаст новый файл и сохранит там активный объект, но только в том случае, если параметр пути указывает на несуществующий файл. Примечание. Если для параметра create_file установлено значение True и путь указывает на существующий файл, будет возбуждено исключение.
Эта функция вызовет JSONFileError , если конечный файл не поддерживает JSON (имеет неподдерживаемое расширение). Эта функция вызовет FileExistsError , если для параметра chate_file установлено значение True и файл уже существует по указанному пути. Эта функция вызовет FileNotFoundError , если для параметра create_file установлено значение False и файл не может быть найден по указанному пути. Эта функция вызовет любые дополнительные исключения, если они возникнут.
Примеры:
Сохранение активного объекта в файл (существующий):
from robust_json.object import JsonObjectParser
obj = {'name': 'Helen Anderson', 'employee_id': 107756}
op = JsonObjectParser(obj)
op.update_value('$', 'employee_id', 107744)
print(op.active_json)
# Output: {'name': 'Helen Anderson', 'employee_id': 107744}
op.save_to_file(path='new_data.json')
# Contents of 'new_data.json' file: {'name': 'Helen Anderson', 'employee_id': 107744}
# Calling this function with different 'path' parameter will
# make this function save the value of JsonObjectParser.active_json property into
# existing file ('new_data.json' in this case). But if file cannot be found, a 'FileNotFoundError'
# exception will be raised.
Сохранение активного объекта в файл (несуществующий):
from robust_json.object import JsonObjectParser
obj = {'name': 'Helen Anderson', 'employee_id': 107756}
op = JsonObjectParser(obj)
op.update_value('$', 'employee_id', 107744)
print(op.active_json)
# Output: {'name': 'Helen Anderson', 'employee_id': 107744}
op.save_to_file(path='new_data.json')
# A 'FileNotFoundError' exception has been raised.
# It happened because this file does not exist.
# To fix this we need to set 'create_file' parameter to True.
op.save_to_file(path='new_data.json', create_file=True)
# Contents of 'new_data.json' file: {'name': 'Helen Anderson', 'employee_id': 107744}
# Calling the function with 'create_file' set to True and different path makes it create
# a new file and save the value of JsonObjectParser.active_json property there.
# But if file already exists, a 'FileExistsError' will be raised.
Этот модуль содержит все пользовательские исключения, которые могут быть вызваны во время выполнения пакета. Всего их 5: JSONFileError , JSONPathError , JSONStrictModeError , JSONObjectError , IncorrectFunctionParameterTypeError . Если вам нужно их импортировать, это можно сделать так:
import robust_json.errors as json_err
filter_json_array(json_array: список, поле: строка, значение: любое) Эта функция будет фильтровать заданный массив объектов JSON и возвращать его. Параметр json_array:list указывает список, который необходимо отфильтровать, поле:str указывает ключ, а значение:любое указывает значение. Два последних параметра образуют пару ключ:значение, которая играет роль фильтра.
Эта функция вернет список с отфильтрованным содержимым.
Эта функция вызовет исключение IncorrectFunctionParameterTypeError , если один или несколько ее параметров имеют неправильный тип. Эта функция вызовет ошибку JSONObjectError , если json_arr не является массивом объектов ([{}, {}, {}, ...]). Эта функция вызовет любые дополнительные исключения, если они возникнут.
Пример. Фильтрация массива объектов по определенной паре ключ:значение.
from robust_json.ext import filter_json_array
orders = [{"order_id":1648,"country":"USA" },{"order_id":1830,"country":"Liberia"},
{"order_id":6703,"country":"USA"},{"order_id":2995,"country":"Russia"}]
usa_orders = filter_json_array(orders, 'country', 'USA')
print(usa_orders)
# Output: [{"order_id":1648,"country":"USA" }, {"order_id":6703,"country":"USA"}]
get_item_index(item: Any, array: list, Always_array: bool = False) Эта функция найдет целое число в заданном массиве и вернет его индекс(-ы). item:any указывает элемент, индекс которого необходимо найти. array:list указывает массив, в котором должен присутствовать этот элемент, а Always_array:bool управляет типом возвращаемого значения этой функции. Если установлено значение False, эта функция вернет массив, если совпадений несколько, но вернет целое число, если совпадение только одно. Если установлено значение True, эта функция всегда будет возвращать массив (см. примеры ниже).
Примеры:
from robust_json.ext import get_item_index
arr1 = [1, 2, 3, 4]
index = get_item_index(2, arr1, False)
print(index)
# Output: 1
# Note: we set 'always_array' parameter to False, therefore function returned an integer
arr2 = [5, 9, 10, 45, 555]
index = get_item_index(10, arr2, True)
print(index)
# Output: [2]
# Note: we set 'always_array' parameter to True, therefore function returned an array even if there
# is only one match. This is useful when this array will be iterated later on.
arr3 = [1, 6, 'string', 8, 5, 4, 'string', 0, 22]
index = get_item_index('string', arr3, False)
# Note: even if 'alway_array' parameter set to False, this function will return an array of
# integers because there are multiple matches
print(index)
# Output: [2, 6]
arr4 = [1, 2, 3]
index = get_item_index(6, arr4, False)
# Note: if item is not present in the array and 'always_array' parameter set to False,
# None will be returned.
print(index)
# Output: None
arr5 = [5, 6, 7]
index = get_item_index(10, arr5, True)
# Note: if item is not present in the array and 'always_array' parameter set to True,
# an empty array will be returned.
print(index)
# Output: []
verse_array(array: list) Эта функция переворачивает массив и возвращает его.
Эта функция вызовет ошибку IncorrectFunctionParameterTypeError , если ее параметр имеет неверный тип. Эта функция вызовет любые дополнительные исключения, если они возникнут.
Пример:
from robust_json.ext import reverse_array
arr = ['a', 'b', 'c']
rev_arr = reverse_array(arr)
print(rev_arr)
# Output: ['c', 'b', 'a']
