robust json
v.1.2.7
健壮的json包是一个轻量级但功能强大的库，用于在Python中处理JSON文件和对象。
您可以直接从 PyPI 安装此包：
pip install robust-json
该库仅在 python 3.x 上受支持。
如果您想改进这个项目，请首先通过打开一个新问题来讨论您的想法。之后分叉这个存储库并实现这个很棒的功能或修复这个恼人的错误。然后创建一个新的 PR 并等待批准。
注意：请先阅读contributing.md 文件。在那里您可以找到有关贡献流程的行为准则和有用信息。
该库包括 4 个模块：
该模块提供了通过JsonFileParser类处理 JSON 文件的各种方法。它会自动从指定文件解析并加载有效的 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 ，标记指定的文件不存在。如果一个或多个参数的类型不正确，则会引发 In CorrectFunctionParameterTypeError异常。
特性：
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
如果该函数的参数类型不正确，则会引发In CorrectFunctionParameterTypeError 。如果指定的 JSON 路径无效（不存在或无法访问），此函数还将引发JSONPathError 。
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，函数将尝试在数组末尾附加给定值。 （参见下面的示例）。此函数将返回带有更新的 JSON 的 Python 字典。
如果该函数的参数类型不正确，则该函数将引发In CorrectFunctionParameterTypeEroor异常。如果“append value”为空（等于空字符串、空数组、空字典等），此函数也会引发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: 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启用严格模式。默认情况下此模式处于关闭状态。如果打开，此方法将确保新值与旧值具有相同的类型（如果旧值是字符串，则新值也需要是字符串，等等）。如果类型不匹配，则会引发异常。
如果该函数的参数 (-s) 具有 (-ve) 类型不正确，则会引发In CorrectFunctionParameterTypeError异常。如果启用严格模式，此函数还会在类型不匹配的情况下引发JSONStrictModeError ；如果 JSON 路径无效（不存在或无法访问），则会引发JSONPathError异常。如果发生任何其他异常，此函数将引发。
示例：
更新对象根中的键：值对：
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 数组时使用属性名称，则会引发异常（请参阅下面的示例）。如果该函数的参数 (-s) 具有 (-ve) 类型不正确，则会引发In CorrectFunctionParameterTypeError异常。如果 JSON 路径无效（不存在或无法访问），此函数还将引发JSONPathError异常。如果发生的话，此函数将引发任何其他异常。
示例：
删除对象根中的键：值对：
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()完全相反
该函数不返回任何值。
如果该函数的参数类型不正确，则会引发In CorrectFunctionParameterTypeError 。
JsonFileParser.reset(discard_active_object: bool = False)此函数将重置活动 JSON 对象，删除对其所做的任何更改。 Discard_active_object:bool参数控制此函数关于活动 JSON 对象（JsonFileParser.active_json 属性）的行为。如果设置为 False，此方法将仅返回一个初始对象并保留对 actove JSON 的所有更改。如果设置为 True，此函数仍将返回初始对象，但也会重置活动对象，并且所有更改都将永久消失。
如果该函数的参数类型不正确，则会引发In CorrectFunctionParameterTypeError 。
示例：
获取初始对象并将其存储在变量中：
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 并且路径指向现有文件，则会引发异常。
如果最终文件不支持 JSON（具有不受支持的扩展名），此函数将引发JSONFileError 。如果create_file设置为 True 并且文件已存在于指定路径下，则此函数将引发FileExistsError 。如果create_file设置为 False 并且无法在指定路径下找到文件，则此函数将引发FileNotFoundError 。如果发生的话，此函数将引发任何其他异常。
示例：
将活动对象保存到源文件：
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.
该模块提供了直接通过JsonObjectParser类处理 JSON 对象的各种方法。此类专门设计用于处理从 API 调用接收到的 JSON 或在 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)
如果文件不存在，模块将创建一个。如果文件确实存在，它将被截断并用序列化的活动对象填充。
在初始化期间，可能会引发In CorrectFunctionParameterTypeError异常。这意味着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
如果该函数的参数类型不正确，则会引发In CorrectFunctionParameterTypeError 。如果指定的 JSON 路径无效（不存在或无法访问），此函数还将引发JSONPathError 。如果发生的话，此函数将引发任何其他异常。
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，函数将尝试在数组末尾附加给定值。 （参见下面的示例）。此函数将返回带有更新的 JSON 的 Python 字典。
如果该函数的参数类型不正确，则该函数将引发In CorrectFunctionParameterTypeEroor异常。如果“append value”为空（空字符串、空数组、空字典），此函数也会引发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启用严格模式。默认情况下此模式处于关闭状态。如果打开，此方法将确保新值与旧值具有相同的类型（如果旧值是字符串，则新值也需要是字符串，等等）。如果类型不匹配，则会引发异常。
如果该函数的参数 (-s) 具有 (-ve) 类型不正确，则会引发In CorrectFunctionParameterTypeError异常。如果启用严格模式，此函数还会在类型不匹配的情况下引发JSONStrictModeError ；如果 JSON 路径无效（不存在或无法访问），则会引发JSONPathError异常。如果发生的话，此函数将引发任何其他异常。
示例：
更新对象根中的键：值对：
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 数组时使用属性名称，则会引发异常（请参阅下面的示例）。如果该函数的参数 (-s) 具有 (-ve) 类型不正确，则会引发In CorrectFunctionParameterTypeError异常。如果 JSON 路径无效（不存在或无法访问），此函数还将引发JSONPathError异常。如果发生的话，此函数将引发任何其他异常。
示例：
删除对象根中的键：值对：
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 对象，删除对其所做的任何更改。 Discard_active_object:bool参数控制此函数关于活动 JSON 对象（JsonObjectParser.active_json 属性）的行为。如果设置为 False，此方法将仅返回一个初始对象并保留对 actove JSON 的所有更改。如果设置为 True，此函数仍将返回初始对象，但也会重置活动对象，并且所有更改都将永久消失。
如果该函数的参数类型不正确，则会引发In CorrectFunctionParameterTypeError 。如果发生的话，此函数将引发任何其他异常。
示例：
获取初始对象并将其存储在变量中：
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 并且路径指向现有文件，则会引发异常。
如果最终文件不支持 JSON（具有不受支持的扩展名），此函数将引发JSONFileError 。如果cheate_file设置为 True 并且文件已存在于指定路径下，则此函数将引发FileExistsError 。如果create_file设置为 False 并且无法在指定路径下找到文件，则此函数将引发FileNotFoundError 。如果发生的话，此函数将引发任何其他异常。
示例：
将活动对象保存到文件（现有）：
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 、 In CorrectFunctionParameterTypeError 。如果您需要导入它们，可以这样完成：
import robust_json.errors as json_err
filter_json_array(json_array: list, field: string, value: any)该函数将过滤给定的 JSON 对象数组并返回它。 json_array:list参数指定需要过滤的列表， field:str指定key， value:any指定值。最后两个参数形成一个键：值对，充当过滤器的角色。
该函数将返回一个包含过滤内容的列表。
如果该函数的一个或多个参数的类型不正确，则该函数将引发In CorrectFunctionParameterTypeError异常。如果json_arr不是对象数组 ([{}, {}, {}, ...])，则此函数将引发JSONObjectError 。如果发生的话，此函数将引发任何其他异常。
示例：通过特定的键：值对过滤对象数组
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）此函数将在给定数组中找到一个intem并返回其索引（-es）。 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: []
reverse_array(array: list)该函数将反转数组并返回它。
如果该函数的参数类型不正确，则会引发In CorrectFunctionParameterTypeError 。如果发生的话，此函数将引发任何其他异常。
例子：
from robust_json.ext import reverse_array
arr = ['a', 'b', 'c']
rev_arr = reverse_array(arr)
print(rev_arr)
# Output: ['c', 'b', 'a']
