robust json
v.1.2.7
El paquete robust-json es una biblioteca liviana pero capaz de trabajar con archivos y objetos JSON en Python.
Puede instalar este paquete directamente desde PyPI:
pip install robust-json
Esta biblioteca solo es compatible con Python 3.x.
Si desea mejorar este proyecto, primero discuta su idea abriendo una nueva edición. Después de eso, bifurque este repositorio e implemente esta increíble característica o corrija este molesto error. Luego cree un nuevo PR y espere la aprobación.
Nota: lea primero el archivo contribuir.md. Allí podrá encontrar un código de conducta e información útil sobre el proceso de contribución.
Esta biblioteca incluye 4 módulos:
Este módulo proporciona varios métodos para trabajar con archivos JSON a través de la clase JsonFileParser . Analiza y carga automáticamente JSON válido del archivo especificado y también verifica si el archivo está listo para su procesamiento. Para acceder a él, simplemente importe JsonFileParser desde el módulo de archivos:
from robust_json.file import JsonFileParser
e inicializarlo:
op = JsonFileParser(path_to_json_file)
Nota: JsonFileParser ahora admite el guardado automático. Si está habilitado, el módulo guardará el objeto activo después de cada cambio realizado y lo escribirá en el archivo especificado.
Para habilitar el guardado automático, simplemente inicialice este módulo con el parámetro autosave establecido en True :
op = JsonFileParser(path_to_json_file, autosave=True)
Nota: también puede especificar un archivo para el guardado automático. Simplemente pase el parámetro autosave_path con la ruta a su archivo durante la inicialización, así:
op = JsonFileParser(path*to_json_file, autosave=True, autosave_path=path_to_autosave_file)
Si el archivo no existe, el módulo creará uno. Si el archivo existe, se truncará y se completará con el objeto activo serializado.
Durante la inicialización se puede generar una excepción JSONFileError . Esto significa que el analizador no pudo procesar el contenido del archivo especificado o que el archivo tiene una extensión no compatible. Además, durante esta fase se puede generar un FileNotFoundError que indica que el archivo especificado no existe. Se generará una excepción IncorrectFunctionParameterTypeError si uno o más parámetros tienen tipos incorrectos.
Propiedades :
JsonFileParser.file_formats Esta propiedad enumera todas las extensiones de archivo admitidas por este módulo en forma de matriz. Por el momento sólo se admiten archivos .json y .txt . Esto se utiliza durante la inicialización de la clase para determinar si el archivo se puede procesar.
JsonFileParser.path Esta propiedad devuelve la ruta del archivo fuente.
JsonFileParser.active_json Esta propiedad devuelve un objeto JSON con todos los cambios recientes.
JsonFileParser.backup Esta propiedad devuelve el objeto JSON inicial, ignorando todos los cambios recientes. Estas dos últimas propiedades pueden resultar confusas, así que aquí hay un ejemplo ( Nota: consulte la sección de documentación correspondiente para la función 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 el JSON del archivo y lo devuelve como un diccionario de Python. Se llama automáticamente cuando el archivo especificado se procesa por primera 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 accede a un valor de un par clave:valor específico en un objeto JSON y lo devuelve. El parámetro json_path:str especifica una ruta al par clave:valor (por ejemplo, campo0.campo1.[...].fieldn). Ejemplo:
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 función generará un error IncorrectFunctionParameterTypeError si su parámetro tiene un tipo incorrecto. Esta función también generará un JSONPathError si la ruta JSON especificada no es válida (no existe o no se puede acceder a ella).
JsonFileParser.append(json_path: str, append_value: any, append_at_end: bool = False) Este método agrega valor al objeto JSON existente y devuelve un diccionario de Python con contenido actualizado. El parámetro json_path:str especifica una ruta donde se agregará el nuevo valor. Para agregar valor a la raíz del objeto JSON, json_path debe ser igual a '$'. append_value:cualquier parámetro especifica un valor que se agregará. append_at_end:bool controla el comportamiento de esta función con respecto a matrices JSON de objetos (estructuras como esta: [{}, {}, {}, ...]) y matrices generales (estructuras como esta: [a, b, c, . ..]). No tiene influencia sobre otras estructuras. Si se establece en False, la función intentará agregar un valor dado a cada objeto de una matriz. Si se establece en Verdadero, la función intentará agregar el valor dado al final de una matriz. (ver ejemplos a continuación). Esta función devolverá un diccionario de Python con JSON actualizado.
Esta función generará una excepción IncorrectFunctionParameterTypeEroor si su(s) parámetro(s) tiene(-ve) un tipo incorrecto. Esta función también generará una excepción ValueError si 'agregar valor' está vacío (es igual a una cadena vacía, una matriz vacía, un diccionario vacío, etc.). Esta función generará un _JSONPathError si la ruta proporcionada no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Agregar un par clave:valor simple a la raíz de un 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'}
Agregar un nuevo objeto a la matriz 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'}]}
Agregar un par clave:valor a cada objeto de una 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'}]}
Agregar un nuevo elemento a una 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: cualquiera, estricto_modo: bool = False)
Esta función actualizará el valor en el par clave:valor y devolverá un diccionario de Python con contenidos actualizados. El parámetro json_path:str especifica una ruta al par clave:valor/matriz/etc. padre que necesita ser actualizado. (Para actualizar el valor en la raíz del objeto JSON, json_path debe ser igual a '$') mientras que el parámetro key_or_index:Union[str, int] especifica la clave (si es un objeto) o el índice de la matriz (si es una matriz). Esto implica que si necesitamos actualizar la clave con la ruta 'field0.field1.upd key', entonces _json_path será igual a 'field0.field1' y el parámetro key_or_index será igual a 'upd key'. _Nota: si usa un índice de matriz mientras el parámetro 'json_path' apunta a un objeto JSON, o si usa un nombre de propiedad mientras 'json_path' apunta a una matriz JSON, se generará una excepción (consulte los ejemplos a continuación). new_value:any especifica el valor que sobrescribirá el anterior y estricto_mode:bool habilita el modo estricto. De forma predeterminada, este modo está desactivado. Si está activado, este método garantizará que el nuevo valor tenga el mismo tipo que el anterior (si el valor anterior es una cadena, entonces el nuevo también debe ser una cadena, etc.). Si los tipos no coinciden, se generará una excepción.
Esta función generará una excepción IncorrectFunctionParameterTypeError si sus parámetros tienen (-ve) un tipo incorrecto. Esta función también generará un JSONStrictModeError en caso de tipos no coincidentes si el modo estricto está habilitado y una excepción JSONPathError si la ruta JSON no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Actualizando el par clave:valor en la raíz del 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'}
Actualizando elemento en una matriz:
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']}
Actualización de valor con modo estricto:
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 función eliminará un elemento de JSON y devolverá un diccionario de Python con contenido actualizado. El parámetro json_path:str especifica una ruta al par clave:valor/matriz/etc. padre que necesita ser eliminado. (Para eliminar el valor en la raíz del objeto JSON, json_path debe ser igual a '$') mientras que el parámetro key_or_index:Union[str, int] especifica la clave (si es un objeto) o el índice de la matriz (si es una matriz). Esto implica que si necesitamos eliminar la clave con la ruta 'field0.field1.del key', entonces _json_path será igual a 'field0.field1' y el parámetro key_or_index será igual a 'del key'. _Nota: si usa un índice de matriz mientras el parámetro 'json_path' apunta a un objeto JSON, o si usa un nombre de propiedad mientras 'json_path' apunta a una matriz JSON, se generará una excepción (consulte los ejemplos a continuación). Esta función generará una excepción IncorrectFunctionParameterTypeError si su(s) parámetro(s) tiene(-ve) un tipo incorrecto. Esta función también generará una excepción JSONPathError si la ruta JSON no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Eliminando el par clave:valor en la raíz del 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'}
Eliminar elemento en una 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 función eliminará todas las sangrías en el archivo JSON. Básicamente, comprimirá todo JSON en una línea.
Esta función no devuelve ningún valor.
JsonFileParser.prettify(indent: int = 4) Esta función agregará sangrías a JSON en el archivo fuente para mejorar su legibilidad. El parámetro sangría:int especifica el número de espacios. Por defecto es igual a 4. Esta función es completamente opuesta a JsonFileParser.minify()
Esta función no devuelve ningún valor.
Esta función generará un error IncorrectFunctionParameterTypeError si su parámetro tiene un tipo incorrecto.
JsonFileParser.reset(discard_active_object: bool = False) Esta función restablecerá el objeto JSON activo y eliminará cualquier cambio realizado en él. El parámetro descarta_active_object:bool controla el comportamiento de esta función con respecto al objeto JSON activo (propiedad JsonFileParser.active_json). Si se establece en False, este método simplemente devolverá un objeto inicial y mantendrá todos los cambios en el JSON de actove. Si se establece en Verdadero, esta función seguirá devolviendo el objeto inicial, pero también restablecerá el activo y todos los cambios desaparecerán para siempre.
Esta función generará un error IncorrectFunctionParameterTypeError si su parámetro tiene un tipo incorrecto.
Ejemplos:
Obtener un objeto inicial y almacenarlo en una variable:
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.
Obtener un objeto inicial y restablecer uno activo:
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 función guardará el objeto JSON activo en un archivo. ruta: parámetro str especifica la ruta al archivo. Si se deja vacío, el objeto activo se guardará en el archivo fuente. prettify:bool parámetro habilita sangrías. Por defecto está configurado en Verdadero. Si se establece en False, JSON se comprimirá en una línea. create_file:bool parámetro permite la creación de archivos. Si se establece en Verdadero, esta función creará un nuevo archivo y guardará el objeto activo allí, pero solo si el parámetro de ruta apunta a un archivo no existente. Nota: si create_file se establece en True y la ruta apunta a un archivo existente, se generará una excepción.
Esta función generará un JSONFileError si el archivo final no admite JSON (tiene una extensión no compatible). Esta función generará un FileExistsError si create_file está configurado en True y el archivo ya existe en la ruta especificada. Esta función generará un FileNotFoundError si create_file está configurado en False y el archivo no se pudo ubicar en la ruta especificada. Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Guardar el objeto activo en el archivo fuente:
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.
Guardar el objeto activo en un archivo 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.
Guardar el objeto activo en un archivo diferente (no 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 proporciona varios métodos para trabajar con objetos JSON directamente a través de la clase JsonObjectParser . Esta clase está diseñada específicamente para funcionar con JSON recibido de llamadas API o para usarse en API. Para acceder a él, simplemente importe JsonObjectParser desde el módulo de archivos:
from robust_json.object import JsonObjectParser
e inicializarlo:
op = JsonObjectParser(json_obj)
Nota: JsonObjectParser ahora admite el guardado automático. Si está habilitado, el módulo guardará el objeto activo después de cada cambio realizado y lo escribirá en el archivo especificado.
Para habilitar el guardado automático, simplemente inicialice este módulo con el parámetro autosave establecido en True :
op = JsonObjectParser(json_object, autosave=True)
Nota: también puede especificar un archivo para el guardado automático. Simplemente pase el parámetro autosave_path con la ruta a su archivo durante la inicialización, así:
op = JsonObjectParser(json_object, autosave=True, autosave_path=path_to_autosave_file)
Si el archivo no existe, el módulo creará uno. Si el archivo existe, se truncará y se completará con el objeto activo serializado.
Durante la inicialización se puede generar una excepción IncorrectFunctionParameterTypeError . Esto significa que el parámetro json tiene un tipo incorrecto.
Propiedades :
JsonObjectParser.active_json Esta propiedad devuelve un objeto JSON con todos los cambios recientes.
JsonObjectParser.backup Esta propiedad devuelve el objeto JSON inicial, ignorando todos los cambios recientes. Estas dos últimas propiedades pueden resultar confusas, así que aquí hay un ejemplo ( Nota: consulte la sección de documentación correspondiente para la función 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 accede a un valor de un par clave:valor específico en un objeto JSON y lo devuelve. El parámetro json_path:str especifica una ruta al par clave:valor (por ejemplo, campo0.campo1.[...].fieldn). Ejemplo:
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 función generará un error IncorrectFunctionParameterTypeError si su parámetro tiene un tipo incorrecto. Esta función también generará un JSONPathError si la ruta JSON especificada no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
JsonObjectParser.append(json_path: str, append_value: any, append_at_end: bool = False) Este método agrega valor al objeto JSON existente y devuelve un diccionario de Python con contenido actualizado. El parámetro json_path:str especifica una ruta donde se agregará el nuevo valor. Para agregar valor a la raíz del objeto JSON, json_path debe ser igual a '$'. append_value:cualquier parámetro especifica un valor que se agregará. append_at_end:bool controla el comportamiento de esta función con respecto a matrices JSON de objetos (estructuras como esta: [{}, {}, {}, ...]) y matrices generales (estructuras como esta: [a, b, c, . ..]). No tiene influencia sobre otras estructuras. Si se establece en False, la función intentará agregar un valor dado en cada objeto de una matriz. Si se establece en Verdadero, la función intentará agregar el valor dado al final de una matriz. (ver ejemplos a continuación). Esta función devolverá un diccionario de Python con JSON actualizado.
Esta función generará una excepción IncorrectFunctionParameterTypeEroor si su(s) parámetro(s) tiene(-ve) un tipo incorrecto. Esta función también generará una excepción ValueError si 'agregar valor' está vacío (cadena vacía, matriz vacía, diccionario vacío). Esta función generará un _JSONPathError si la ruta proporcionada no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Agregar un par clave:valor simple a la raíz de un 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'}
Agregar un nuevo objeto a la matriz 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'}]}
Agregar un par clave:valor a cada objeto de una 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'}]}
Agregar un nuevo elemento a una 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: cualquiera, estricto_modo: bool = False)
Esta función actualizará el valor en el par clave:valor y devolverá un diccionario de Python con contenidos actualizados. El parámetro json_path:str especifica una ruta al par clave:valor/matriz/etc. padre que necesita ser actualizado. (Para actualizar el valor en la raíz del objeto JSON, json_path debe ser igual a '$') mientras que el parámetro key_or_index:Union[str, int] especifica la clave (si es un objeto) o el índice de la matriz (si es una matriz). Esto implica que si necesitamos actualizar la clave con la ruta 'field0.field1.upd key', entonces _json_path será igual a 'field0.field1' y el parámetro key_or_index será igual a 'upd key'. _Nota: si usa un índice de matriz mientras el parámetro 'json_path' apunta a un objeto JSON, o si usa un nombre de propiedad mientras 'json_path' apunta a una matriz JSON, se generará una excepción (consulte los ejemplos a continuación). new_value:any especifica el valor que sobrescribirá el anterior y estricto_mode:bool habilita el modo estricto. De forma predeterminada, este modo está desactivado. Si está activado, este método garantizará que el nuevo valor tenga el mismo tipo que el anterior (si el valor anterior es una cadena, entonces el nuevo también debe ser una cadena, etc.). Si los tipos no coinciden, se generará una excepción.
Esta función generará una excepción IncorrectFunctionParameterTypeError si su(s) parámetro(s) tiene(-ve) un tipo incorrecto. Esta función también generará un JSONStrictModeError en caso de tipos no coincidentes si el modo estricto está habilitado y una excepción JSONPathError si la ruta JSON no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Actualizando el par clave:valor en la raíz del 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'}
Actualizando elemento en una matriz:
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']}
Actualización de valor con modo estricto:
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 función eliminará un elemento de JSON y devolverá un diccionario de Python con contenido actualizado. El parámetro json_path:str especifica una ruta al par clave:valor/matriz/etc. padre que necesita ser eliminado. (Para eliminar el valor en la raíz del objeto JSON, json_path debe ser igual a '$') mientras que el parámetro key_or_index:Union[str, int] especifica la clave (si es un objeto) o el índice de la matriz (si es una matriz). Esto implica que si necesitamos eliminar la clave con la ruta 'field0.field1.del key', entonces _json_path será igual a 'field0.field1' y el parámetro key_or_index será igual a 'del key'. _Nota: si usa un índice de matriz mientras el parámetro 'json_path' apunta a un objeto JSON, o si usa un nombre de propiedad mientras 'json_path' apunta a una matriz JSON, se generará una excepción (consulte los ejemplos a continuación). Esta función generará una excepción IncorrectFunctionParameterTypeError si sus parámetros tienen (-ve) un tipo incorrecto. Esta función también generará una excepción JSONPathError si la ruta JSON no es válida (no existe o no se puede acceder a ella). Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Eliminando el par clave:valor en la raíz del 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'}
Eliminar elemento en una 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 función restablecerá el objeto JSON activo y eliminará cualquier cambio realizado en él. El parámetro descarta_active_object:bool controla el comportamiento de esta función con respecto al objeto JSON activo (propiedad JsonObjectParser.active_json). Si se establece en False, este método simplemente devolverá un objeto inicial y mantendrá todos los cambios en el JSON de actove. Si se establece en Verdadero, esta función seguirá devolviendo el objeto inicial, pero también restablecerá el activo y todos los cambios desaparecerán para siempre.
Esta función generará un error IncorrectFunctionParameterTypeError si su parámetro tiene un tipo incorrecto. Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Obtener un objeto inicial y almacenarlo en una variable:
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
Obtener un objeto inicial y restablecer uno activo:
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 función guardará el objeto JSON activo en un archivo. ruta: parámetro str especifica la ruta al archivo. prettify:bool parámetro habilita sangrías. Por defecto está configurado en Verdadero. Si se establece en False, JSON se comprimirá en una línea. create_file:bool parámetro permite la creación de archivos. Si se establece en Verdadero, esta función creará un nuevo archivo y guardará el objeto activo allí, pero solo si el parámetro de ruta apunta a un archivo no existente. Nota: si create_file se establece en True y la ruta apunta a un archivo existente, se generará una excepción.
Esta función generará un JSONFileError si el archivo final no admite JSON (tiene una extensión no compatible). Esta función generará un FileExistsError si Cheate_file está configurado en True y el archivo ya existe en la ruta especificada. Esta función generará un FileNotFoundError si create_file está configurado en False y el archivo no se pudo ubicar en la ruta especificada. Esta función generará excepciones adicionales si ocurren.
Ejemplos:
Guardar objeto activo en un archivo (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.
Guardar objeto activo en un archivo (no 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 contiene todas las excepciones personalizadas que se pueden generar durante el tiempo de ejecución del paquete. Hay un total de 5: JSONFileError , JSONPathError , JSONStrictModeError , JSONObjectError , IncorrectFunctionParameterTypeError . Si necesita importarlos, puede hacerlo así:
import robust_json.errors as json_err
filter_json_array(json_array: lista, campo: cadena, valor: cualquiera) Esta función filtrará una matriz dada de objetos JSON y la devolverá. El parámetro json_array:list especifica la lista que debe filtrarse, campo:str especifica la clave y valor:any especifica el valor. Los dos últimos parámetros forman un par clave:valor que actúa como filtro.
Esta función devolverá una lista con contenido filtrado.
Esta función generará una excepción IncorrectFunctionParameterTypeError si uno o más de sus parámetros tienen un tipo incorrecto. Esta función generará un JSONObjectError si json_arr no es una matriz de objetos ([{}, {}, {}, ...]). Esta función generará excepciones adicionales si ocurren.
Ejemplo: filtrar una matriz de objetos por un par clave: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 función encontrará un intem en una matriz dada y devolverá su(s) índice(s). item:any especifica el elemento cuyo índice se debe encontrar. array:list especifica la matriz donde este elemento debe estar presente y always_array:bool controla el tipo de retorno de esta función. Si se establece en False, esta función devolverá una matriz si hay varias coincidencias, pero devolverá un número entero si solo hay una coincidencia. Si se establece en Verdadero, esta función siempre devolverá una matriz (ver ejemplos a continuación).
Ejemplos:
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: []
matriz_inversa(matriz: lista) Esta función invertirá una matriz y la devolverá.
Esta función generará un error IncorrectFunctionParameterTypeError si su parámetro tiene un tipo incorrecto. Esta función generará excepciones adicionales si ocurren.
Ejemplo:
from robust_json.ext import reverse_array
arr = ['a', 'b', 'c']
rev_arr = reverse_array(arr)
print(rev_arr)
# Output: ['c', 'b', 'a']
