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 。
該函數不傳回任何值。
如果函數的參數類型不正確，則會引發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']
