Package: nakalapycon
NakalaPyconLibrairie Python pour interagir avec Nakala (Nakala : entrepôt de données de recherche en SHS développé par Huma-Num).Cette librairie vise à simplifier l'utilisation de l'API Nakaladepuis les programme écrits en Python.Elle peut être vue comme unwrapperde l'API.
Les différents end-points de l'API sont séparées dans les fichiers python suivants :nklAPI_DatasnklAPI_CollectionsnklAPI_GroupsnklAPI_UsersnklAPI_VocabulariesPour mieux comprendre le fonctionnement sous-jacent de cette librairie nous recommandons les lectures suivantes :NakalaPyConnect : Dépôt facilitant l'appropriation de Nakala et de son API.Notebook Api Nakala : Une présentation de l'API de NAKALA sous forme d'un notebook JupyterButs1. Nakala Production versus Nakala TestL'entrepôt Nakala existe sous 2 instances :(Nakala Test)[https://test.nakala.fr/](Nakala Production)[https://nakala.fr/]Lors de développements en interactions avec Nakala, il est impératif de commencer par prototyper sur Nakala Test avant de lancer ses scripts sur Nakala Production.Pour faciliter le choix et le changement de Nakala Test vers Nakala Production, la librairienakalapyconpropose une classeNklTargetdont on créer une instance la manière suivante# création d'une cible Nakala Test avec une Key Api d'utilisateur validemyApiKey="f41f5957-d396-3bb9-ce35-a4692773f636"targetTest=nklT.NklTarget(isNakalaProd=False,apiKey=)# création d'une cible Nakala Production avec une Key Api d'utilisateur videmyApiKey=""targetProd=nklT.NklTarget(isNakalaProd=True,apiKey=)Toutes les fonctions mise à dispositions dansnakalapyconprennent en paramètre entrant une instance d'un objetNklTarget. Par ce mécanisme
il est très facile de changer le Nakala ciblé.
Il est même facilement envisageable de réaliser des communications entre Nakala Test et Nakala Production.2. Unifier les valeurs retoursLorsque l'on communique avec l'API Nakala il est important de pouvoir obtenir les objets JSON contenant les données retournés par le server mais il est également important de savoir si la requête c'est réalisée correctement. Cependant, les codes retours serveurs sont assez différents d'un access-point à l'autre. Tandis qu'il est en général simplement important de savoir si la requête s'est passée correctement Oui ou Non ?
Pour cela, toutes les fonctions denakalapyconretourne une instance d'un objetNklResponseLa classeNklResponsepeut être vue comme un sac contenant 4 variables :NklResponse.isSuccess : retourne False en cas de code d'erreur server ou cas de problème reseauNklResponse.code : le status_code retourné par le serveur NakalaNklResponse.message : la description associée au code d'erreur nakala ou le message d'exception de la librairie requestNklResponse.dictVals : les valeurs json renvoyés par le serveur en cas de succès sous la forme d'un dictionnaire python3. Encapsuler les appels bas niveau nécessaires au requêtage HTTP de l'API Nakala.Cette librairie se charge d'encapsuler et masquer les appels bas niveau à la librairerequestnécessaires au requetage HTTP de l'API Nakala et de traiter les codes retours servers.Lors de la communication avec l'API Nakala, il peut se produire 2 types d'erreurs classiques :les erreurs retournées par le server Nakalaen cas de requêtes mal forméesen cas de mauvaises valeurs : comme c'est le cas lorsque l'on cherche à modifier une DATA Nakala alors que nous ne disposons pas des droits suffisants sur cette DATA.les erreurs du au réseau internetlorsque notre connexion wifi se coupelorsque le proxy de notre établissement disfonctionnelorsque le serveur nakala est momentanement inacessibleAfin de décharger les développeurs de script communiquant avec Nakala de traiter la difficulté de ces deux types d'erreurs dont les erreurs réseaux levant des "exceptions" provoquant l'arrêt du script si elles ne sont pas capturées, la librairienakalapyconprend en charge la capture de toutes erreurs et retourne de manière unifiée desNklResponse.4. Faciliter le développement de fonctions plus aux niveauxEn ayant simplifier l'accessibilité de l'API il est plus facile d'envisager la création de fonctions plus haut niveaux. Comme par exemple des traitements par lots sur toutes les DATA d'un COLLECTION.Ce genre de traitement haut niveau se trouve dansnklUtilsCas d'usages1. Intéragir avec Nakala depuis un notebook JupyterGénérer un rapport de donnnées intéractif en ciblant une collection depuis un notebook jupyter.Ajouter des droits administrateurs à un groupe d'utilisateur sur toutes les DATA d'une COLLECTION2. Développer sa chaîne de traitement semi-automatisé intégrant Nakala dans la chaîneFabriquer son outil de dépôt et MAJ "sur-mesure" intégrant Nakala. Découvrir le projetsync Sharedocs NakalaInstallationCette librairie est déposée sur l'entrpôt de packagePyPi.Il suffit donc de l'installer avec la commande :pip install nakalapyconpuis de l'utiliser depuis votre script après un import :import nakalapycon as nklcoIl est également possible de l'installer depuis Anaconda.Navigator