robust json
v.1.2.7
堅牢な json パッケージは軽量ですが、Python で JSON ファイルとオブジェクトを操作するための有能なライブラリです。
このパッケージは PyPI から直接インストールできます。
pip install robust-json
このライブラリは Python 3.x でのみサポートされます。
このプロジェクトを改善したい場合は、まず新しい問題を開いてアイデアについて話し合ってください。その後、このリポジトリをフォークして、この素晴らしい機能を実装するか、この迷惑なバグを修正します。次に、新しい PR を作成し、承認を待ちます。
注: まず、contributor.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 が発生する場合があります。 1 つ以上のパラメータの型が正しくない場合、 IncorrectFunctionParameterTypeErrorエラーが発生します。
プロパティ:
JsonFileParser.file_formatsこのプロパティは、このモジュールでサポートされているすべてのファイル拡張子を配列形式でリストします。現時点では、 .jsonファイルと.txtファイルのみがサポートされています。これは、ファイルが処理できるかどうかを判断するためにクラスの初期化中に使用されます。
JsonFileParser.pathこのプロパティはソース ファイルのパスを返します
JsonFileParser.active_jsonこのプロパティは、最近のすべての変更を含む JSON オブジェクトを返します。
JsonFileParser.backupこのプロパティは、最近の変更をすべて無視して、初期の JSON オブジェクトを返します。これら最後の 2 つのプロパティは混乱を招く可能性があるため、ここに例を示します (注: 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 オブジェクト内の特定の key:value ペアの値にアクセスし、それを返します。 json_path:strパラメータは、key:value ペアへのパス (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を発生させます。この関数は、指定された 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 辞書を返します。
この関数は、パラメーター (-s) の型が間違っている (-ve) 場合、 IncorrectFunctionParameterTypeEroor例外を発生させます。この関数は、「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パラメータは、key:value ペア/配列などへのパスを指定します。更新する必要がある親。 (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) 場合、 IncorrectFunctionParameterTypeError例外を発生させます。また、この関数は、Strict モードが有効な場合に型が一致しない場合に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パラメータは、key:value ペア/配列などへのパスを指定します。削除する必要がある親。 (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) 場合、 IncorrectFunctionParameterTypeError例外を発生させます。この関数は、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 を 1 行に圧縮します。
この関数は値を返しません。
JsonFileParser.prettify(indent: int = 4)この関数は、ソース ファイルの JSON にインデントを追加して、可読性を向上させます。 indent:intパラメータはスペースの数を指定します。デフォルトでは、これは 4 に等しくなります。この関数は、 JsonFileParser.minify()とはまったく逆です。
この関数は値を返しません。
この関数は、パラメータの型が正しくない場合、 IncorrectFunctionParameterTypeErrorを発生させます。
JsonFileParser.reset(discard_active_object: bool = False)この関数は、アクティブな JSON オブジェクトをリセットし、それに加えられた変更をすべて削除します。 Discard_active_object:boolパラメーターは、アクティブな JSON オブジェクト (JsonFileParser.active_json プロパティ) に関するこの関数の動作を制御します。 False に設定すると、このメソッドは単に初期オブジェクトを返し、すべての変更を actove 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 は 1 行に圧縮されます。 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)
ファイルが存在しない場合、モジュールはファイルを作成します。ファイルが存在する場合、ファイルは切り詰められ、シリアル化されたアクティブ オブジェクトで埋められます。
初期化中に、 IncorrectFunctionParameterTypeError例外が発生する場合があります。これは、 jsonパラメーターの型が正しくないことを意味します。
プロパティ:
JsonObjectParser.active_jsonこのプロパティは、最近のすべての変更を含む JSON オブジェクトを返します。
JsonObjectParser.backupこのプロパティは、最近の変更をすべて無視して、初期の JSON オブジェクトを返します。最後の 2 つのプロパティは混乱を招く可能性があるため、ここに例を示します (注: 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 オブジェクト内の特定の key:value ペアの値にアクセスし、それを返します。 json_path:strパラメータは、key:value ペアへのパス (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を発生させます。この関数は、指定された 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 辞書を返します。
この関数は、パラメーター (-s) の型が間違っている (-ve) 場合、 IncorrectFunctionParameterTypeEroor例外を発生させます。この関数は、「値の追加」が空 (空の文字列、空の配列、空の辞書)の場合にも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)
この関数は、key:value ペアの値を更新し、更新された内容を含む Python 辞書を返します。 json_path:strパラメータは、key:value ペア/配列などへのパスを指定します。更新する必要がある親。 (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) 場合、 IncorrectFunctionParameterTypeError例外を発生させます。また、この関数は、Strict モードが有効な場合に型が一致しない場合に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パラメータは、key:value ペア/配列などへのパスを指定します。削除する必要がある親。 (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) 場合、 IncorrectFunctionParameterTypeError例外を発生させます。この関数は、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 に設定すると、この関数は初期オブジェクトを返しますが、アクティブなオブジェクトもリセットし、すべての変更は永久に失われます。
この関数は、パラメータの型が正しくない場合、 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 は 1 行に圧縮されます。 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 、 IncorrectFunctionParameterTypeError 。それらをインポートする必要がある場合は、次のように実行できます。
import robust_json.errors as json_err
filter_json_array(json_array: list, field: string, value: any)この関数は、指定された JSON オブジェクトの配列をフィルターして返します。 json_array:listパラメータはフィルタリングする必要があるリストを指定し、 field:str はキーを指定し、 value:any は値を指定します。最後の 2 つのパラメーターは、フィルターの役割を果たすキー:値のペアを形成します。
この関数は、フィルタリングされたコンテンツを含むリストを返します。
1 つ以上のパラメーターの型が正しくない場合、この関数はIncorrectFunctionParameterTypeError例外を発生させます。 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 に設定すると、この関数は一致が複数ある場合は配列を返しますが、一致が 1 つだけの場合は整数を返します。 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)この関数は配列を反転して返します。
この関数は、パラメータの型が正しくない場合、 IncorrectFunctionParameterTypeErrorを発生させます。この関数は、追加の例外が発生した場合に発生させます。
例：
from robust_json.ext import reverse_array
arr = ['a', 'b', 'c']
rev_arr = reverse_array(arr)
print(rev_arr)
# Output: ['c', 'b', 'a']
