robust json
v.1.2.7
Le package robuste-json est une bibliothèque légère mais performante pour travailler avec des fichiers et des objets JSON en Python.
Vous pouvez installer ce package directement depuis PyPI :
pip install robust-json
Cette bibliothèque est prise en charge sur python 3.x uniquement.
Si vous souhaitez améliorer ce projet, discutez d'abord de votre idée en ouvrant un nouveau numéro. Après cela, créez ce référentiel et implémentez cette fonctionnalité géniale ou corrigez ce bug ennuyeux. Créez ensuite un nouveau PR et attendez l'approbation.
Remarque : veuillez d'abord lire le fichier contribution.md. Vous y trouverez un code de conduite et des informations utiles concernant le processus de contribution.
Cette bibliothèque comprend 4 modules :
Ce module fournit diverses méthodes pour travailler avec des fichiers JSON via la classe JsonFileParser . Il analyse et charge automatiquement le JSON valide à partir du fichier spécifié et vérifie également si le fichier est prêt pour le traitement. Pour y accéder, importez simplement JsonFileParser depuis le module de fichiers :
from robust_json.file import JsonFileParser
et initialisez-le:
op = JsonFileParser(path_to_json_file)
Remarque : JsonFileParser prend désormais en charge la sauvegarde automatique. S'il est activé, le module enregistrera l'objet actif après chaque modification qui y est apportée et l'écrira dans le fichier spécifié.
Pour activer la sauvegarde automatique, initialisez simplement ce module avec le paramètre autosave défini sur True :
op = JsonFileParser(path_to_json_file, autosave=True)
Remarque : vous pouvez également spécifier un fichier pour l'enregistrement automatique. Passez simplement le paramètre autosave_path avec le chemin d'accès à votre fichier lors de l'initialisation, comme ceci :
op = JsonFileParser(path*to_json_file, autosave=True, autosave_path=path_to_autosave_file)
Si le fichier n'existe pas, le module en créera un. Si le fichier existe, il sera tronqué et rempli d'un objet actif sérialisé.
Lors de l'initialisation, une exception JSONFileError peut être déclenchée. Cela signifie que l'analyseur n'a pas pu traiter le contenu du fichier spécifié ou que le fichier a une extension non prise en charge. Également au cours de cette phase, une FileNotFoundError peut être générée, indiquant que le fichier spécifié n'existe pas. Une réception IncorrectFunctionParameterTypeError sera déclenchée si un ou plusieurs paramètres ont des types incorrects.
Propriétés :
JsonFileParser.file_formats Cette propriété répertorie toutes les extensions de fichiers prises en charge par ce module sous la forme d'un tableau. Pour le moment, seuls les fichiers .json et .txt sont pris en charge. Ceci est utilisé lors de l'initialisation de la classe pour déterminer si le fichier peut être traité.
JsonFileParser.path Cette propriété renvoie le chemin du fichier source
JsonFileParser.active_json Cette propriété renvoie l'objet JSON avec toutes les modifications récentes.
JsonFileParser.backup Cette propriété renvoie l'objet JSON initial, en ignorant toutes les modifications récentes. Ces deux dernières propriétés peuvent prêter à confusion, voici donc un exemple ( Remarque : voir la section de documentation correspondante pour la fonction 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éthodes :
JsonFileParser.get_json_from_file() Cette méthode récupère tous les JSON du fichier et les renvoie sous forme de dictionnaire Python. Il est appelé automatiquement lorsque le fichier spécifié est traité pour la première fois.
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) Cette méthode accède à une valeur à partir d'une paire clé:valeur spécifique dans l'objet JSON et la renvoie. Le paramètre json_path:str spécifie un chemin vers la paire clé:valeur (par exemple field0.field1.[...].fieldn). Exemple:
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
Cette fonction déclenchera une IncorrectFunctionParameterTypeError si son paramètre a un type incorrect. Cette fonction déclenchera également une JSONPathError si le chemin JSON spécifié n'est pas valide (n'existe pas ou n'est pas accessible).
JsonFileParser.append(json_path : str, append_value : any, append_at_end : bool = False) Cette méthode ajoute une valeur à l'objet JSON existant et renvoie un dictionnaire Python avec un contenu mis à jour. Le paramètre json_path:str spécifie un chemin où une nouvelle valeur sera ajoutée. Pour ajouter une valeur à la racine de l'objet JSON, json_path doit être égal à « $ ». append_value:any paramètre spécifie une valeur qui sera ajoutée. append_at_end:bool contrôle le comportement de cette fonction concernant les tableaux d'objets JSON (structures comme celle-ci : [{}, {}, {}, ...]) et les tableaux généraux (structures comme celle-ci : [a, b, c, . ..]). Il n'a aucune influence sur les autres structures. Si elle est définie sur False, la fonction tentera d'ajouter la valeur donnée à chaque objet d'un tableau. Si elle est définie sur True, la fonction tentera d'ajouter la valeur donnée à la fin d'un tableau. (voir exemples ci-dessous). Cette fonction renverra un dictionnaire Python avec JSON mis à jour.
Cette fonction déclenchera une exception IncorrectFunctionParameterTypeEroor si son ou ses paramètres ont (-ve) un type incorrect. Cette fonction déclenchera également une exception ValueError si la « valeur ajoutée » est vide (est égale à une chaîne vide, un tableau vide, un dictionnaire vide, etc.). Cette fonction générera une _JSONPathError si le chemin fourni n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Ajout d'une simple paire clé:valeur à la racine d'un objet
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'}
Ajout d'un nouvel objet au tableau d'objets
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'}]}
Ajout d'une paire clé:valeur à chaque objet d'un tableau
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'}]}
Ajout d'un nouvel élément à un tableau d'éléments :
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)
Cette fonction mettra à jour la valeur dans la paire clé:valeur et renverra un dictionnaire Python avec un contenu mis à jour. Le paramètre json_path:str spécifie un chemin vers la paire clé:valeur/tableau/etc. parent qui doit être mis à jour. (Pour mettre à jour la valeur à la racine de l'objet JSON, json_path doit être égal à '$') tandis que le paramètre key_or_index:Union[str, int] spécifie la clé (s'il s'agit d'un objet) ou l'index du tableau (s'il s'agit d'un tableau). Cela implique que si nous devons mettre à jour la clé avec le chemin 'field0.field1.upd key', alors _json_path sera égal à 'field0.field1' et le paramètre key_or_index sera égal à 'upd key'. _Remarque : si vous utilisez un index de tableau alors que le paramètre 'json_path' pointe vers un objet JSON, ou si vous utilisez un nom de propriété alors que 'json_path' pointe vers un tableau JSON, une exception sera levée (voir les exemples ci-dessous). new_value:any spécifie la valeur qui écrasera l'ancienne et strict_mode:bool active le mode strict. Par défaut, ce mode est désactivé. Si elle est activée, cette méthode garantira que la nouvelle valeur a le même type que l'ancienne (si l'ancienne valeur est une chaîne, alors la nouvelle doit également être une chaîne, etc.). Si les types ne correspondent pas, une exception sera levée.
Cette fonction déclenchera une exception IncorrectFunctionParameterTypeError si son ou ses paramètres ont (-ve) un type incorrect. Cette fonction déclenchera également une JSONStrictModeError en cas de types incompatibles si le mode strict est activé et une exception JSONPathError si le chemin JSON n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Mise à jour de la paire clé:valeur à la racine de l'objet :
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'}
Mise à jour d'un élément dans un tableau :
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']}
Mise à jour de la valeur avec le mode strict :
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]) Cette fonction supprimera un élément de JSON et renverra un dictionnaire Python avec un contenu mis à jour. Le paramètre json_path:str spécifie un chemin vers la paire clé:valeur/tableau/etc. parent qui doit être supprimé. (Pour supprimer la valeur à la racine de l'objet JSON, json_path doit être égal à '$') tandis que le paramètre key_or_index:Union[str, int] spécifie la clé (s'il s'agit d'un objet) ou l'index du tableau (s'il s'agit d'un tableau). Cela implique que si nous devons supprimer la clé avec le chemin 'field0.field1.del key', alors _json_path sera égal à 'field0.field1' et le paramètre key_or_index sera égal à 'del key'. _Remarque : si vous utilisez un index de tableau alors que le paramètre 'json_path' pointe vers un objet JSON, ou si vous utilisez un nom de propriété alors que 'json_path' pointe vers un tableau JSON, une exception sera levée (voir les exemples ci-dessous). Cette fonction déclenchera une exception IncorrectFunctionParameterTypeError si son ou ses paramètres ont (-ve) un type incorrect. Cette fonction déclenchera également une exception JSONPathError si le chemin JSON n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Suppression de la paire clé:valeur à la racine de l'objet :
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'}
Suppression d'un élément dans un tableau :
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() Cette fonction supprimera toutes les indentations du fichier JSON. Fondamentalement, il compressera tous les JSON sur une seule ligne.
Cette fonction ne renvoie aucune valeur.
JsonFileParser.prettify(indent: int = 4) Cette fonction ajoutera des indentations à JSON dans le fichier source pour améliorer sa lisibilité. Le paramètre indent:int spécifie le nombre d'espaces. Par défaut, il est égal à 4. Cette fonction est complètement opposée à JsonFileParser.minify()
Cette fonction ne renvoie aucune valeur.
Cette fonction déclenchera une IncorrectFunctionParameterTypeError si son paramètre a un type incorrect.
JsonFileParser.reset(discard_active_object: bool = False) Cette fonction réinitialisera l'objet JSON actif, supprimant toutes les modifications qui y sont apportées. Le paramètre throw_active_object:bool contrôle le comportement de cette fonction concernant l'objet JSON actif (propriété JsonFileParser.active_json). Si elle est définie sur False, cette méthode renverra simplement un objet initial et conservera toutes les modifications apportées au JSON actif. Si elle est définie sur True, cette fonction renverra toujours l'objet initial, mais réinitialisera également l'objet actif, et toutes les modifications seront définitivement supprimées.
Cette fonction déclenchera une IncorrectFunctionParameterTypeError si son paramètre a un type incorrect.
Exemples :
Récupérer un objet initial et le stocker dans une 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.
Récupérer un objet initial et réinitialiser un objet actif :
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) Cette fonction enregistrera l'objet JSON actif dans un fichier. Le paramètre path:str spécifie le chemin d'accès au fichier. S'il est laissé vide, l'objet actif sera enregistré dans le fichier source. Le paramètre prettify:bool active les indentations. Par défaut, il est défini sur True. S'il est défini sur False, JSON sera compressé sur une seule ligne. Le paramètre create_file:bool permet la création de fichiers. Si elle est définie sur True, cette fonction créera un nouveau fichier et y enregistrera l'objet actif, mais uniquement si le paramètre path pointe vers un fichier inexistant. Remarque : si create_file est défini sur True et que le chemin pointe vers un fichier existant, une exception sera levée.
Cette fonction générera une JSONFileError si le fichier de fin ne prend pas en charge JSON (a une extension non prise en charge). Cette fonction générera une FileExistsError si create_file est défini sur True et que le fichier existe déjà sous le chemin spécifié. Cette fonction générera une FileNotFoundError si create_file est défini sur False et que le fichier ne peut pas être localisé sous le chemin spécifié. Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Enregistrement de l'objet actif dans le fichier source :
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.
Enregistrement de l'objet actif dans un autre fichier (existant) :
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.
Enregistrement de l'objet actif dans un autre fichier (non existant) :
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.
Ce module fournit diverses méthodes pour travailler avec un objet JSON directement via la classe JsonObjectParser . Cette classe est spécifiquement conçue pour fonctionner avec le JSON reçu des appels d'API ou pour être utilisée dans les API. Pour y accéder, importez simplement JsonObjectParser depuis le module file :
from robust_json.object import JsonObjectParser
et initialisez-le:
op = JsonObjectParser(json_obj)
Remarque : JsonObjectParser prend désormais en charge la sauvegarde automatique. S'il est activé, le module enregistrera l'objet actif après chaque modification qui y est apportée et l'écrira dans le fichier spécifié.
Pour activer la sauvegarde automatique, initialisez simplement ce module avec le paramètre autosave défini sur True :
op = JsonObjectParser(json_object, autosave=True)
Remarque : vous pouvez également spécifier un fichier pour l'enregistrement automatique. Passez simplement le paramètre autosave_path avec le chemin d'accès à votre fichier lors de l'initialisation, comme ceci :
op = JsonObjectParser(json_object, autosave=True, autosave_path=path_to_autosave_file)
Si le fichier n'existe pas, le module en créera un. Si le fichier existe, il sera tronqué et rempli d'un objet actif sérialisé.
Lors de l'initialisation, une exception IncorrectFunctionParameterTypeError peut être déclenchée. Cela signifie que le paramètre json a un type incorrect.
Propriétés :
JsonObjectParser.active_json Cette propriété renvoie l'objet JSON avec toutes les modifications récentes.
JsonObjectParser.backup Cette propriété renvoie l'objet JSON initial, en ignorant toutes les modifications récentes. Ces deux dernières propriétés peuvent prêter à confusion, voici donc un exemple ( Remarque : voir la section de documentation correspondante pour la fonction 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éthodes :
JsonObjectParser.get_key_value(json_path: str) Cette méthode accède à une valeur à partir d'une paire clé:valeur spécifique dans l'objet JSON et la renvoie. Le paramètre json_path:str spécifie un chemin vers la paire clé:valeur (par exemple field0.field1.[...].fieldn). Exemple:
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
Cette fonction générera une IncorrectFunctionParameterTypeError si son paramètre a un type incorrect. Cette fonction déclenchera également une JSONPathError si le chemin JSON spécifié n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
JsonObjectParser.append(json_path : str, append_value : any, append_at_end : bool = False) Cette méthode ajoute une valeur à l'objet JSON existant et renvoie un dictionnaire Python avec un contenu mis à jour. Le paramètre json_path:str spécifie un chemin où une nouvelle valeur sera ajoutée. Pour ajouter une valeur à la racine de l'objet JSON, json_path doit être égal à « $ ». append_value:any paramètre spécifie une valeur qui sera ajoutée. append_at_end:bool contrôle le comportement de cette fonction concernant les tableaux d'objets JSON (structures comme celle-ci : [{}, {}, {}, ...]) et les tableaux généraux (structures comme celle-ci : [a, b, c, . ..]). Il n'a aucune influence sur les autres structures. Si elle est définie sur False, la fonction tentera d'ajouter la valeur donnée dans chaque objet d'un tableau. Si elle est définie sur True, la fonction tentera d'ajouter la valeur donnée à la fin d'un tableau. (voir exemples ci-dessous). Cette fonction renverra un dictionnaire Python avec JSON mis à jour.
Cette fonction déclenchera une exception IncorrectFunctionParameterTypeEroor si son ou ses paramètres ont un type incorrect. Cette fonction déclenchera également une exception ValueError si la « valeur ajoutée » est vide (chaîne vide, tableau vide, dictionnaire vide). Cette fonction générera une _JSONPathError si le chemin fourni n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Ajout d'une simple paire clé:valeur à la racine d'un objet
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'}
Ajout d'un nouvel objet au tableau d'objets
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'}]}
Ajout d'une paire clé: valeur à chaque objet d'un tableau
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'}]}
Ajout d'un nouvel élément à un tableau d'éléments :
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)
Cette fonction mettra à jour la valeur dans la paire clé:valeur et renverra un dictionnaire Python avec un contenu mis à jour. Le paramètre json_path:str spécifie un chemin vers la paire clé:valeur/tableau/etc. parent qui doit être mis à jour. (Pour mettre à jour la valeur à la racine de l'objet JSON, json_path doit être égal à '$') tandis que le paramètre key_or_index:Union[str, int] spécifie la clé (s'il s'agit d'un objet) ou l'index du tableau (s'il s'agit d'un tableau). Cela implique que si nous devons mettre à jour la clé avec le chemin 'field0.field1.upd key', alors _json_path sera égal à 'field0.field1' et le paramètre key_or_index sera égal à 'upd key'. _Remarque : si vous utilisez un index de tableau alors que le paramètre 'json_path' pointe vers un objet JSON, ou si vous utilisez un nom de propriété alors que 'json_path' pointe vers un tableau JSON, une exception sera levée (voir les exemples ci-dessous). new_value:any spécifie la valeur qui écrasera l'ancienne et strict_mode:bool active le mode strict. Par défaut, ce mode est désactivé. Si elle est activée, cette méthode garantira que la nouvelle valeur a le même type que l'ancienne (si l'ancienne valeur est une chaîne, alors la nouvelle doit également être une chaîne, etc.). Si les types ne correspondent pas, une exception sera levée.
Cette fonction déclenchera une exception IncorrectFunctionParameterTypeError si son ou ses paramètres ont (-ve) un type incorrect. Cette fonction déclenchera également une JSONStrictModeError en cas de types incompatibles si le mode strict est activé et une exception JSONPathError si le chemin JSON n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Mise à jour de la paire clé:valeur à la racine de l'objet :
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'}
Mise à jour d'un élément dans un tableau :
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']}
Mise à jour de la valeur avec le mode strict :
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]) Cette fonction supprimera un élément de JSON et renverra un dictionnaire Python avec un contenu mis à jour. Le paramètre json_path:str spécifie un chemin vers la paire clé:valeur/tableau/etc. parent qui doit être supprimé. (Pour supprimer la valeur à la racine de l'objet JSON, json_path doit être égal à '$') tandis que le paramètre key_or_index:Union[str, int] spécifie la clé (s'il s'agit d'un objet) ou l'index du tableau (s'il s'agit d'un tableau). Cela implique que si nous devons supprimer la clé avec le chemin 'field0.field1.del key', alors _json_path sera égal à 'field0.field1' et le paramètre key_or_index sera égal à 'del key'. _Remarque : si vous utilisez un index de tableau alors que le paramètre 'json_path' pointe vers un objet JSON, ou si vous utilisez un nom de propriété alors que 'json_path' pointe vers un tableau JSON, une exception sera levée (voir les exemples ci-dessous). Cette fonction déclenchera une exception IncorrectFunctionParameterTypeError si son ou ses paramètres ont (-ve) un type incorrect. Cette fonction déclenchera également une exception JSONPathError si le chemin JSON n'est pas valide (n'existe pas ou n'est pas accessible). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Suppression de la paire clé:valeur à la racine de l'objet :
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'}
Suppression d'un élément dans un tableau :
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) Cette fonction réinitialisera l'objet JSON actif, supprimant toutes les modifications qui y sont apportées. Le paramètre throw_active_object:bool contrôle le comportement de cette fonction concernant l'objet JSON actif (propriété JsonObjectParser.active_json). Si elle est définie sur False, cette méthode renverra simplement un objet initial et conservera toutes les modifications apportées au JSON actif. Si elle est définie sur True, cette fonction renverra toujours l'objet initial, mais réinitialisera également l'objet actif, et toutes les modifications seront définitivement supprimées.
Cette fonction déclenchera une IncorrectFunctionParameterTypeError si son paramètre a un type incorrect. Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Récupérer un objet initial et le stocker dans une 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
Récupérer un objet initial et réinitialiser un objet actif :
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) Cette fonction enregistrera l'objet JSON actif dans un fichier. Le paramètre path:str spécifie le chemin d'accès au fichier. Le paramètre prettify:bool active les indentations. Par défaut, il est défini sur True. S'il est défini sur False, JSON sera compressé sur une seule ligne. Le paramètre create_file:bool permet la création de fichiers. Si elle est définie sur True, cette fonction créera un nouveau fichier et y enregistrera l'objet actif, mais uniquement si le paramètre path pointe vers un fichier inexistant. Remarque : si create_file est défini sur True et que le chemin pointe vers un fichier existant, une exception sera levée.
Cette fonction générera une JSONFileError si le fichier de fin ne prend pas en charge JSON (a une extension non prise en charge). Cette fonction générera une FileExistsError si cheate_file est défini sur True et que le fichier existe déjà sous le chemin spécifié. Cette fonction générera une FileNotFoundError si create_file est défini sur False et que le fichier ne peut pas être localisé sous le chemin spécifié. Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemples :
Enregistrement de l'objet actif dans un fichier (existant) :
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.
Sauvegarde de l'objet actif dans un fichier (inexistant) :
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.
Ce module contient toutes les exceptions personnalisées qui peuvent être déclenchées lors de l'exécution du package. Il y en a au total 5 : JSONFileError , JSONPathError , JSONStrictModeError , JSONObjectError , IncorrectFunctionParameterTypeError . Si vous devez les importer, cela peut être fait comme ceci :
import robust_json.errors as json_err
filter_json_array(json_array: list, field: string, value: any) Cette fonction filtrera un tableau donné d'objets JSON et le renverra. Le paramètre json_array:list spécifie la liste qui doit être filtrée, field:str spécifie la clé et value:any spécifie la valeur. Deux derniers paramètres forment une paire clé:valeur qui joue le rôle de filtre.
Cette fonction renverra une liste avec du contenu filtré.
Cette fonction déclenchera une exception IncorrectFunctionParameterTypeError si un ou plusieurs de ses paramètres ont un type incorrect. Cette fonction générera une JSONObjectError si json_arr n'est pas un tableau d'objets ([{}, {}, {}, ...]). Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemple : Filtrage d'un tableau d'objets par une paire clé:valeur spécifique
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) Cette fonction trouvera un intem dans un tableau donné et renverra son index(-es). item:any spécifie l'élément dont l'index doit être trouvé. array:list spécifie le tableau où cet élément doit être présent et always_array:bool contrôle le type de retour de cette fonction. Si elle est définie sur False, cette fonction renverra un tableau s'il y a plusieurs correspondances, mais renverra un entier s'il n'y a qu'une seule correspondance. Si elle est définie sur True, cette fonction renverra toujours un tableau (voir les exemples ci-dessous).
Exemples :
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) Cette fonction inversera un tableau et le renverra.
Cette fonction déclenchera une IncorrectFunctionParameterTypeError si son paramètre a un type incorrect. Cette fonction déclenchera des exceptions supplémentaires si cela se produit.
Exemple:
from robust_json.ext import reverse_array
arr = ['a', 'b', 'c']
rev_arr = reverse_array(arr)
print(rev_arr)
# Output: ['c', 'b', 'a']
