robust json
v.1.2.7
O pacote robust-json é uma biblioteca leve, mas capaz de trabalhar com arquivos e objetos JSON em Python.
Você pode instalar este pacote diretamente do PyPI:
pip install robust-json
Esta biblioteca é compatível apenas com python 3.x.
Se você quiser melhorar este projeto, primeiro discuta sua ideia abrindo um novo fascículo. Depois disso, bifurque este repositório e implemente esse recurso incrível ou corrija esse bug irritante. Em seguida, crie um novo PR e aguarde a aprovação.
Nota: leia primeiro o arquivo contribuinte.md. Lá você pode encontrar código de conduta e informações úteis sobre o processo de contribuição.
Esta biblioteca inclui 4 módulos:
Este módulo fornece vários métodos para trabalhar com arquivos JSON por meio da classe JsonFileParser . Ele analisa e carrega automaticamente JSON válido do arquivo especificado e também verifica se o arquivo está pronto para processamento. Para acessá-lo, basta importar JsonFileParser do módulo de arquivo:
from robust_json.file import JsonFileParser
e inicialize-o:
op = JsonFileParser(path_to_json_file)
Nota: JsonFileParser agora oferece suporte ao salvamento automático. Se habilitado, o módulo salvará o objeto ativo após cada alteração feita nele e o gravará no arquivo especificado.
Para ativar o salvamento automático, basta inicializar este módulo com o parâmetro autosave definido como True :
op = JsonFileParser(path_to_json_file, autosave=True)
Nota: você também pode especificar o arquivo para salvamento automático. Basta passar o parâmetro autosave_path com o caminho para o seu arquivo durante a inicialização, assim:
op = JsonFileParser(path*to_json_file, autosave=True, autosave_path=path_to_autosave_file)
Se o arquivo não existir, o módulo criará um. Se o arquivo existir, ele será truncado e preenchido com objeto ativo serializado.
Durante a inicialização, uma exceção JSONFileError pode ser gerada. Isso significa que o analisador não conseguiu processar o conteúdo do arquivo especificado ou o arquivo tem uma extensão não suportada. Também durante esta fase, um FileNotFoundError pode ser gerado, marcando que o arquivo especificado não existe. Uma exceção IncorrectFunctionParameterTypeError será gerada se um ou mais parâmetros tiverem tipos incorretos.
Propriedades :
JsonFileParser.file_formats Esta propriedade lista todas as extensões de arquivo suportadas por este módulo na forma de uma matriz. No momento, apenas arquivos .json e .txt são suportados. Isso é usado durante a inicialização da classe para determinar se o arquivo pode ser processado.
JsonFileParser.path Esta propriedade retorna o caminho do arquivo de origem
JsonFileParser.active_json Esta propriedade retorna o objeto JSON com todas as alterações recentes.
JsonFileParser.backup Esta propriedade retorna o objeto JSON inicial, ignorando todas as alterações recentes. Essas duas últimas propriedades podem ser confusas, então aqui está um exemplo ( Nota: consulte a seção de documentação correspondente para a função 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.
Métodos :
JsonFileParser.get_json_from_file() Este método recupera todo o JSON do arquivo e o retorna como um dicionário Python. É chamado automaticamente quando o arquivo especificado é processado pela primeira vez.
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) Este método acessa um valor de um par chave:valor específico no objeto JSON e o retorna. O parâmetro json_path:str especifica um caminho para o par chave:valor (por exemplo, campo0.campo1.[...].campon). Exemplo:
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
Esta função gerará um IncorrectFunctionParameterTypeError se seu parâmetro tiver um tipo incorreto. Esta função também gerará um JSONPathError se o caminho JSON especificado não for válido (não existe ou não pôde ser acessado).
JsonFileParser.append(json_path: str,pend_value:any,append_at_end: bool = False) Este método acrescenta valor ao objeto JSON existente e retorna um dicionário Python com conteúdo atualizado. O parâmetro json_path:str especifica um caminho onde o novo valor será adicionado. Para acrescentar valor à raiz do objeto JSON, json_path precisa ser igual a '$'. append_value:any parâmetro especifica um valor que será anexado. append_at_end:bool controla o comportamento desta função em relação a matrizes JSON de objetos (estruturas como esta: [{}, {}, {}, ...]) e matrizes gerais (estruturas como esta: [a, b, c, . ..]). Não tem influência em outras estruturas. Se definida como False, a função tentará adicionar um determinado valor a cada objeto de um array. Se definida como True, a função tentará acrescentar o valor fornecido no final de um array. (veja exemplos abaixo). Esta função retornará um dicionário Python com JSON atualizado.
Esta função gerará uma exceção IncorrectFunctionParameterTypeEroor se seu(s) parâmetro(s) tiver(-ve) um tipo incorreto. Esta função também gerará uma exceção ValueError se 'append value' estiver vazio (é igual a string vazia, array vazio, dicionário vazio, etc.). Esta função gerará um _JSONPathError se o caminho fornecido não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Adicionando um par chave:valor simples à raiz de um objeto
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'}
Adicionando novo objeto ao array de objetos
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'}]}
Adicionando um par chave:valor a cada objeto de uma matriz
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'}]}
Adicionando novo elemento a uma matriz de elementos:
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)
Esta função atualizará o valor no par chave:valor e retornará um dicionário Python com conteúdo atualizado. O parâmetro json_path:str especifica um caminho para par chave:valor/matriz/etc. pai que precisa ser atualizado. (Para atualizar o valor na raiz do objeto JSON, json_path precisa ser igual a '$') enquanto o parâmetro key_or_index:Union[str, int] especifica a chave (se for um objeto) ou o índice do array (se for um array). Isso implica que se precisarmos atualizar a chave com o caminho 'field0.field1.upd key', então _json_path será igual a 'field0.field1' e o parâmetro key_or_index será igual a 'upd key'. _Nota: se você usar um índice de array enquanto o parâmetro 'json_path' estiver apontando para o objeto JSON, ou se você usar um nome de propriedade enquanto 'json_path' estiver apontando para o array JSON, uma exceção será gerada (veja exemplos abaixo). new_value:any especifica o valor que substituirá o antigo e strict_mode:bool ativa o modo estrito. Por padrão, este modo está desativado. Se ativado, este método garantirá que o novo valor tenha o mesmo tipo que o antigo (se o valor antigo for uma string, então o novo também precisará ser uma string, etc.). Se os tipos não corresponderem, uma exceção será gerada.
Esta função gerará uma exceção IncorrectFunctionParameterTypeError se seu (-s) parâmetro (-s) tiver (-ve) um tipo incorreto. Esta função também gerará um JSONStrictModeError no caso de tipos incompatíveis se o Modo Estrito estiver habilitado e uma exceção JSONPathError se o caminho JSON não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Atualizando o par chave:valor na raiz do objeto:
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'}
Atualizando item em um array:
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']}
Atualizando valor com Modo Estrito:
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]) Esta função excluirá um elemento do JSON e retornará um dicionário Python com conteúdo atualizado. O parâmetro json_path:str especifica um caminho para par chave:valor/matriz/etc. pai que precisa ser excluído. (Para excluir o valor na raiz do objeto JSON, json_path precisa ser igual a '$') enquanto o parâmetro key_or_index:Union[str, int] especifica a chave (se for um objeto) ou o índice do array (se for um array). Isso implica que se precisarmos excluir a chave com o caminho 'field0.field1.del key', então _json_path será igual a 'field0.field1' e o parâmetro key_or_index será igual a 'del key'. _Nota: se você usar um índice de array enquanto o parâmetro 'json_path' estiver apontando para o objeto JSON, ou se você usar um nome de propriedade enquanto 'json_path' estiver apontando para o array JSON, uma exceção será gerada (veja exemplos abaixo). Esta função gerará uma exceção IncorrectFunctionParameterTypeError se seu (-s) parâmetro (-s) tiver (-ve) um tipo incorreto. Esta função também gerará uma exceção JSONPathError se o caminho JSON não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Excluindo o par chave:valor na raiz do objeto:
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'}
Excluindo item em uma matriz:
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() Esta função removerá todos os recuos no arquivo JSON. Basicamente, ele compactará todo o JSON em uma linha.
Esta função não retorna nenhum valor.
JsonFileParser.prettify(indent: int = 4) Esta função adicionará recuos ao JSON no arquivo de origem para melhorar sua legibilidade. O parâmetro indent:int especifica o número de espaços. Por padrão, é igual a 4. Esta função é completamente oposta a JsonFileParser.minify()
Esta função não retorna nenhum valor.
Esta função gerará um IncorrectFunctionParameterTypeError se seu parâmetro tiver um tipo incorreto.
JsonFileParser.reset(discard_active_object: bool = False) Esta função irá redefinir o objeto JSON ativo, removendo quaisquer alterações feitas nele. O parâmetro descartar_active_object:bool controla o comportamento desta função em relação ao objeto JSON ativo (propriedade JsonFileParser.active_json). Se definido como False, este método simplesmente retornará um objeto inicial e manterá todas as alterações no JSON ativo. Se definida como True, esta função ainda retornará o objeto inicial, mas também redefinirá o ativo, e todas as alterações desaparecerão para sempre.
Esta função gerará um IncorrectFunctionParameterTypeError se seu parâmetro tiver um tipo incorreto.
Exemplos:
Obtendo um objeto inicial e armazenando-o em uma variável:
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.
Obtendo um objeto inicial e redefinindo um objeto ativo:
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) Esta função salvará o objeto JSON ativo no arquivo. O parâmetro path:str especifica o caminho para o arquivo. Se deixado em branco, o objeto ativo será salvo no arquivo de origem. O parâmetro prettify:bool permite recuos. Por padrão, está definido como True. Se definido como False, o JSON será compactado em uma linha. O parâmetro create_file:bool permite a criação de arquivos. Se definida como True, esta função criará um novo arquivo e salvará o objeto ativo nele, mas obedecerá se o parâmetro path estiver apontando para um arquivo inexistente. Nota: se create_file estiver definido como True e o caminho estiver apontando para um arquivo existente, uma exceção será gerada.
Esta função gerará um JSONFileError se o arquivo final não suportar JSON (tem uma extensão não suportada). Esta função gerará um FileExistsError se create_file estiver definido como True e o arquivo já existir no caminho especificado. Esta função gerará um FileNotFoundError se create_file estiver definido como False e o arquivo não puder ser localizado no caminho especificado. Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Salvando o objeto ativo no arquivo de origem:
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.
Salvando o objeto ativo em um arquivo diferente (existente):
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.
Salvando o objeto ativo em um arquivo diferente (não existente):
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.
Este módulo fornece vários métodos para trabalhar com objetos JSON diretamente por meio da classe JsonObjectParser . Esta classe foi projetada especificamente para funcionar com JSON recebido de chamadas de API ou para ser usado em APIs. Para acessá-lo, basta importar JsonObjectParser do módulo de arquivo:
from robust_json.object import JsonObjectParser
e inicialize-o:
op = JsonObjectParser(json_obj)
Nota: JsonObjectParser agora oferece suporte ao salvamento automático. Se habilitado, o módulo salvará o objeto ativo após cada alteração feita nele e o gravará no arquivo especificado.
Para ativar o salvamento automático, basta inicializar este módulo com o parâmetro autosave definido como True :
op = JsonObjectParser(json_object, autosave=True)
Nota: você também pode especificar o arquivo para salvamento automático. Basta passar o parâmetro autosave_path com o caminho para o seu arquivo durante a inicialização, assim:
op = JsonObjectParser(json_object, autosave=True, autosave_path=path_to_autosave_file)
Se o arquivo não existir, o módulo criará um. Se o arquivo existir, ele será truncado e preenchido com objeto ativo serializado.
Durante a inicialização, uma exceção IncorrectFunctionParameterTypeError pode ser gerada. Isso significa que o parâmetro JSON tem um tipo incorreto.
Propriedades :
JsonObjectParser.active_json Esta propriedade retorna o objeto JSON com todas as alterações recentes.
JsonObjectParser.backup Esta propriedade retorna o objeto JSON inicial, ignorando todas as alterações recentes. Essas duas últimas propriedades podem ser confusas, então aqui está um exemplo ( Nota: consulte a seção de documentação correspondente para a função 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.
Métodos :
JsonObjectParser.get_key_value(json_path: str) Este método acessa um valor de um par chave:valor específico no objeto JSON e o retorna. O parâmetro json_path:str especifica um caminho para o par chave:valor (por exemplo, campo0.campo1.[...].campon). Exemplo:
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
Esta função gerará um IncorrectFunctionParameterTypeError se seu parâmetro tiver um tipo incorreto. Esta função também gerará um JSONPathError se o caminho JSON especificado não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
JsonObjectParser.append(json_path: str,pend_value:any,append_at_end: bool = False) Este método acrescenta valor ao objeto JSON existente e retorna um dicionário Python com conteúdo atualizado. O parâmetro json_path:str especifica um caminho onde o novo valor será adicionado. Para acrescentar valor à raiz do objeto JSON, json_path precisa ser igual a '$'. append_value:any parâmetro especifica um valor que será anexado. append_at_end:bool controla o comportamento desta função em relação a matrizes JSON de objetos (estruturas como esta: [{}, {}, {}, ...]) e matrizes gerais (estruturas como esta: [a, b, c, . ..]). Não tem influência em outras estruturas. Se definida como False, a função tentará adicionar um determinado valor em cada objeto de um array. Se definida como True, a função tentará acrescentar o valor fornecido no final de um array. (veja exemplos abaixo). Esta função retornará um dicionário Python com JSON atualizado.
Esta função gerará uma exceção IncorrectFunctionParameterTypeEroor se seu(s) parâmetro(s) tiver(-ve) um tipo incorreto. Esta função também gerará uma exceção ValueError se 'append value' estiver vazio (string vazia, array vazio, dicionário vazio). Esta função gerará um _JSONPathError se o caminho fornecido não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Adicionando um par chave:valor simples à raiz de um objeto
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'}
Adicionando novo objeto ao array de objetos
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'}]}
Adicionando um par chave:valor a cada objeto de uma matriz
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'}]}
Adicionando novo elemento a uma matriz de elementos:
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)
Esta função atualizará o valor no par chave:valor e retornará um dicionário Python com conteúdo atualizado. O parâmetro json_path:str especifica um caminho para par chave:valor/matriz/etc. pai que precisa ser atualizado. (Para atualizar o valor na raiz do objeto JSON, json_path precisa ser igual a '$') enquanto o parâmetro key_or_index:Union[str, int] especifica a chave (se for um objeto) ou o índice do array (se for um array). Isso implica que se precisarmos atualizar a chave com o caminho 'field0.field1.upd key', então _json_path será igual a 'field0.field1' e o parâmetro key_or_index será igual a 'upd key'. _Nota: se você usar um índice de array enquanto o parâmetro 'json_path' estiver apontando para o objeto JSON, ou se você usar um nome de propriedade enquanto 'json_path' estiver apontando para o array JSON, uma exceção será gerada (veja exemplos abaixo). new_value:any especifica o valor que substituirá o antigo e strict_mode:bool ativa o modo estrito. Por padrão, este modo está desativado. Se ativado, este método garantirá que o novo valor tenha o mesmo tipo que o antigo (se o valor antigo for uma string, então o novo também precisará ser uma string, etc.). Se os tipos não corresponderem, uma exceção será gerada.
Esta função gerará uma exceção IncorrectFunctionParameterTypeError se seu (-s) parâmetro (-s) tiver (-ve) um tipo incorreto. Esta função também gerará um JSONStrictModeError no caso de tipos incompatíveis se o Modo Estrito estiver habilitado e uma exceção JSONPathError se o caminho JSON não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Atualizando o par chave:valor na raiz do objeto:
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'}
Atualizando item em um array:
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']}
Atualizando valor com Modo Estrito:
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]) Esta função excluirá um elemento do JSON e retornará um dicionário Python com conteúdo atualizado. O parâmetro json_path:str especifica um caminho para par chave:valor/matriz/etc. pai que precisa ser excluído. (Para excluir o valor na raiz do objeto JSON, json_path precisa ser igual a '$') enquanto o parâmetro key_or_index:Union[str, int] especifica a chave (se for um objeto) ou o índice do array (se for um array). Isso implica que se precisarmos excluir a chave com o caminho 'field0.field1.del key', então _json_path será igual a 'field0.field1' e o parâmetro key_or_index será igual a 'del key'. _Nota: se você usar um índice de array enquanto o parâmetro 'json_path' estiver apontando para o objeto JSON, ou se você usar um nome de propriedade enquanto 'json_path' estiver apontando para o array JSON, uma exceção será gerada (veja exemplos abaixo). Esta função gerará uma exceção IncorrectFunctionParameterTypeError se seu (-s) parâmetro (-s) tiver (-ve) um tipo incorreto. Esta função também gerará uma exceção JSONPathError se o caminho JSON não for válido (não existe ou não pôde ser acessado). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Excluindo o par chave:valor na raiz do objeto:
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'}
Excluindo item em uma matriz:
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) Esta função irá redefinir o objeto JSON ativo, removendo quaisquer alterações feitas nele. O parâmetro descartar_active_object:bool controla o comportamento desta função em relação ao objeto JSON ativo (propriedade JsonObjectParser.active_json). Se definido como False, este método simplesmente retornará um objeto inicial e manterá todas as alterações no JSON ativo. Se definida como True, esta função ainda retornará o objeto inicial, mas também redefinirá o objeto ativo e todas as alterações desaparecerão para sempre.
Esta função gerará um IncorrectFunctionParameterTypeError se seu parâmetro tiver um tipo incorreto. Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Obtendo um objeto inicial e armazenando-o em uma variável:
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
Obtendo um objeto inicial e redefinindo um objeto ativo:
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) Esta função salvará o objeto JSON ativo no arquivo. O parâmetro path:str especifica o caminho para o arquivo. O parâmetro prettify:bool permite recuos. Por padrão, está definido como True. Se definido como False, o JSON será compactado em uma linha. O parâmetro create_file:bool permite a criação de arquivos. Se definida como True, esta função criará um novo arquivo e salvará o objeto ativo nele, mas obedecerá se o parâmetro path estiver apontando para um arquivo inexistente. Nota: se create_file estiver definido como True e o caminho estiver apontando para um arquivo existente, uma exceção será gerada.
Esta função gerará um JSONFileError se o arquivo final não suportar JSON (tem uma extensão não suportada). Esta função irá gerar um FileExistsError se cheate_file estiver definido como True e o arquivo já existir no caminho especificado. Esta função gerará um FileNotFoundError se create_file estiver definido como False e o arquivo não puder ser localizado no caminho especificado. Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplos:
Salvando objeto ativo em um arquivo (existente):
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.
Salvando objeto ativo em um arquivo (não existente):
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.
Este módulo contém todas as exceções personalizadas que podem ser levantadas durante o tempo de execução do pacote. Há um total de 5: JSONFileError , JSONPathError , JSONStrictModeError , JSONObjectError , IncorrectFunctionParameterTypeError . Se precisar importá-los, isso pode ser feito assim:
import robust_json.errors as json_err
filter_json_array(json_array: list, field: string, value: any) Esta função irá filtrar determinado array de objetos JSON e retorná-lo. O parâmetro json_array:list especifica a lista que precisa ser filtrada, field:str especifica a chave e value:any especifica o valor. Os dois últimos parâmetros formam um par chave:valor que desempenha a função de filtro.
Esta função retornará uma lista com conteúdo filtrado.
Esta função gerará uma exceção IncorrectFunctionParameterTypeError se um ou mais de seus parâmetros tiverem um tipo incorreto. Esta função gerará um JSONObjectError se json_arr não for um array de objetos ([{}, {}, {}, ...]). Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplo: Filtrando uma matriz de objetos por um par chave:valor específico
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) Esta função encontrará um intem em determinado array e retornará seu índice (-es). item:any especifica o item cujo índice precisa ser encontrado. array:list especifica o array onde este item precisa estar presente e Always_array:bool controla o tipo de retorno desta função. Se definida como False, esta função retornará um array se houver várias correspondências, mas retornará um número inteiro se houver apenas uma correspondência. Se definida como True, esta função sempre retornará um array (veja os exemplos abaixo).
Exemplos:
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) Esta função irá reverter um array e retorná-lo.
Esta função gerará um IncorrectFunctionParameterTypeError se seu parâmetro tiver um tipo incorreto. Esta função irá gerar quaisquer exceções adicionais, se ocorrerem.
Exemplo:
from robust_json.ext import reverse_array
arr = ['a', 'b', 'c']
rev_arr = reverse_array(arr)
print(rev_arr)
# Output: ['c', 'b', 'a']
