nakalapycon 0.0.9

Librairie Python pour interagir avec Nakala (Nakala est un entrepôt de données de recherche en SHS développé par Huma-Num)

NakalaPycon

Librairie 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 Nakala depuis les programme écrits en Python.

Elle peut être vue comme un wrapper de l'API. Les différents end-points de l'API sont séparées dans les fichiers python suivants :

• nklAPI_Datas

• nklAPI_Collections

• nklAPI_Groups

• nklAPI_Users

• nklAPI_Vocabularies

Pour 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 Jupyter

Buts

1. Nakala Production versus Nakala Test

L'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 librairie nakalapycon propose une classe NklTarget dont on créer une instance la manière suivante

# création d'une cible Nakala Test avec une Key Api d'utilisateur valide
myApiKey = "f41f5957-d396-3bb9-ce35-a4692773f636"
targetTest = nklT.NklTarget(isNakalaProd=False, apiKey=)


# création d'une cible Nakala Production avec une Key Api d'utilisateur vide
myApiKey = ""
targetProd = nklT.NklTarget(isNakalaProd=True, apiKey=)

Toutes les fonctions mise à dispositions dans nakalapycon prennent en paramètre entrant une instance d'un objet NklTarget. 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 retours

Lorsque 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 de nakalapycon retourne une instance d'un objet NklResponse

La classe NklResponse peut être vue comme un sac contenant 4 variables :

• NklResponse.isSuccess : retourne False en cas de code d'erreur server ou cas de problème reseau

• NklResponse.code : le status_code retourné par le serveur Nakala

• NklResponse.message : la description associée au code d'erreur nakala ou le message d'exception de la librairie request

• NklResponse.dictVals : les valeurs json renvoyés par le serveur en cas de succès sous la forme d'un dictionnaire python

3. 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 libraire request né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 Nakala
  • en cas de requêtes mal formées
  • en 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 internet
  • lorsque notre connexion wifi se coupe
  • lorsque le proxy de notre établissement disfonctionne
  • lorsque le serveur nakala est momentanement inacessible

Afin 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 librairie nakalapycon prend en charge la capture de toutes erreurs et retourne de manière unifiée des NklResponse.

4. Faciliter le développement de fonctions plus aux niveaux

En 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 dans nklUtils

Cas d'usages

1. Intéragir avec Nakala depuis un notebook Jupyter

• Gé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 COLLECTION

2. Développer sa chaîne de traitement semi-automatisé intégrant Nakala dans la chaîne

• Fabriquer son outil de dépôt et MAJ "sur-mesure" intégrant Nakala. Découvrir le projet sync Sharedocs Nakala

Installation

Cette librairie est déposée sur l'entrpôt de package PyPi.

Il suffit donc de l'installer avec la commande :

pip install nakalapycon

puis de l'utiliser depuis votre script après un import :

import nakalapycon as nklco

Il est également possible de l'installer depuis Anaconda.Navigator