Package: atrium-tools
Ce package rassemble un ensemble d'outils permettant de communiquer avec, ou agir sur, la base documentaire Atrium
en utilisant l'interface APIREST entre le serveur Nuxeo et des applications clientesDeux composantes principales:atrium_shell: application cliente offrant plusieurs actions de navigation vers la base Atriumnuxeolib: la librairie de base implémentant l'APIREST selon le protocole décrit dans la documentation Nuxeo,
ainsi que plusieurs utilitaires basés sur les conventions Atrium.InstallationInstallation de baseIci, nous allons exploiter le mécanisme standard du monde Python:pippour installer ce package Python.Le packageatrium_toolsa été configuré au format standard des packages Python, et a été déposé dans le
dépôt officielPyPi.Le seul mode d'installation proposé ici est basé sur les environnements virtuels de Python. Nous supposons
que Python (version >= 3) est installé dans votre système> python -V
> python -m venv atrium

> source atrium/bin/activate (*sous Unix*)
> atrium \Scripts\activate (*sous Windows*)

> pip install atrium-tools
> python -m atrium_shell.atrium_shell login=<myatriumaccount> -lsPour mettre à jour la version du package:> pip install --upgrade atrium-toolsIl est possible de questionner l'installation actuelle:> pip show atrium-toolsOu bien de désinstaller le package:> pip uninstall -y atrium-toolsEt de désactiver l'environatriumPython> deactivateL'application atrium_shellIntroductionCette application permet d'interroger la base Atrium un peu comme la commandelsen unix oudiren windows.AuthentificationPour accéder au serveur Nuxeo, une authentification est nécessaire. Deux méthodes d'authentification sont possibles:en utilisant le paramètrelogin=xxxsur la ligne de commande. Ensuite, le mot de passe
sera demandé en interrogation cachéeen utilisant le fichier.netrc(https://sites.google.com/site/diezone/ftp---file-transfert-protocol/ftp---le-fichier-netrc)Il est ainsi possible de spécifier le couple<user id>/<mdp>dans le fichier Unix/Windows standard$HOME/.netrcCe fichier doit obligatoirement être protégé ainsi:> ls -al ../.netrc
-rw------- 1 arnault SI 399 Apr  8 17:10 ../.netrcAutrement dit, seul l'utilisateur doit avoir accès à ce documentCe fichier texte contient des lignes au format suivant:machine atrium.in2p3.fr login <identifiant> password <motdepasse>Si le fichier~/.netrcexiste et que la variable d'environnementHOMEest définie,
alors il ne sera pas nécessaire d'utiliser l'argumentlogin=xxxet la connexion Atrium sera établie automatiquement avec l'identifant décrit dans le ficher~/.netrcArgumentslogin = str      : Compte Atrium (le mot de passe sera demandé)

cd    =  str[/]  : Dossier courant 
                   Par exemple cd=/Laboratoires/IPNO

user   = str[]   : Specification alternative pour le dossier au lieu de cd
                   exemple: arnault@lal.in2p3.fr


cp      = str[]  : document à copier
set_acl = str[]  : acl à installer sur le dossier spécifié (<permission>,<group/user>)
rm_acl  = str[]  : acl à supprimer du le dossier spécifié (<permission>,<group/user>)
subs_acl = str[] : acl à supprimer du le dossier spécifié (<permission1>,<group1/user1>,<permission2>,<group2/user2>)

permission:
    Publisher
    Approver
    Validator
    Reader
    PublisherSection
    LocalAdmin
    Writer

to      = str[]  : document destination (cp, set_acl, rm_acl, subs_acl)

depth  =  int[0] : Profondeur dans l'arborescence. Par défaut la valeur 0 indique le seul premier niveau

-ls              : Listing des documents à partir d'un espace donné
-csv             : Production d'un fichier CSV décrivant l'arborescence des documents 
-draw            : Production d'un graphique décrivant l'arborescence des documents 
-rights          : Controle l'affichage des droitsQuelques précisions:La cible de départ peut être spécifiée:soit aveccdpour un espace institutionnelsoit avecuserpour un espace personnel, en spécifiant l'intitulé du compte AtriumL'optionset_acls'applique uniquement au dossier spécifié avecto=<dossier>L'optionrm_acls'applique récursivement à tous les dossiers enfants à partir du dossierto=<dossierL'optionsubs_acls'applique récursivement à tous les dossiers enfants à partir du dossierto=<dossierDans l'optionsubs_aclon peut substituer une groupe/user indépendemment de la permission en utilisant "%" pour la permissionLes optionsls,csv,drawexploitent l'optiondepth=nUtilisationQuelques exemples d'utilisation (dans les exemples ci-dessous on suppose que
l'authentification est réalisée via le fichier .netrc):>>> python -m atrium_shell.atrium_shell -ls cd=/Laboratoires/LAL/ATLAS
//Atrium/Laboratoires/LAL/ATLAS
  ATLAS/PIXELS
  ATLAS/CALORIMÉTRIE Argon Liquide [Block]
  ATLAS/HGTD (High Granularity Timing Detector)


>>> python -m atrium_shell.atrium_shell -ls cd=/Laboratoires/LAL/ATLAS depth=1
//Atrium/Laboratoires/LAL/ATLAS
  ATLAS/PIXELS
    ATLAS/PIXELS/Mécanique [Block]
    ATLAS/PIXELS/Omégapix [Block]
    ATLAS/PIXELS/FEi4 [Block]
    ATLAS/PIXELS/Doping_Profile [Block]
    ATLAS/PIXELS/RD53 [Block]
    ATLAS/PIXELS/Interconnexion [Block]
    ATLAS/PIXELS/Acquisition [Block]
    ATLAS/PIXELS/atlas_synchro [Block]
    ATLAS/PIXELS/Salle Blanche PIXELS
  ATLAS/CALORIMÉTRIE Argon Liquide [Block]
    ATLAS/CALORIMÉTRIE Argon Liquide/Banc de tests robotisé
  ATLAS/HGTD (High Granularity Timing Detector)
    ATLAS/HGTD (High Granularity Timing Detector)/Ingénierie Mécanique
    ATLAS/HGTD (High Granularity Timing Detector)/Recrutement-AI bac+2NuxeolibCe module contient tous les appels de bas niveau vers l'APIREST de Nuxeo, et permet de développer des applications
utilitaires accédant à la base de données Atrium.checkout(ref)checkin(ref, version='minor', comment='')checkoutin(ref, version='minor', comment='')create_tree_snapshot(ref, version='minor')create_version(ref, increment='Minor', save_document=True)set_property(ref, xpath, value)delete(ref)get_children(ref)get_parent(ref)get_versions(ref)lock(ref)unlock(ref)move(ref, target, name=None)publish(ref, target)copy(ref, target, name=None)add_permission(ref, permission, user, acl='local')get_relations(ref)delete_relation(source, destination)create_relation(ref, destination)query(query, language=None)get_blob(ref)get_blobs(ref)attach_blob(ref, blob)open_batch()close_batch(batch_id)upload_files(input_names=None, batch_id=None)change_title(uid, title)get_document(name)get the uid of a document from its pathcreate_document_with_properties(path,
name,
doc_type,
properties=None,
files=None,
from_uid=None)We create a document in one single operation:
    - mandatory args are: path, name, doc_type
    - properties can be added(dc:title, uid:minor_version, dc:description, ...)
    - files: joint files.update_document_with_properties(uid,
title,
doc_type,
properties=None,
files=None)this function is similar to the create function, but for updating an existing document.read_document(doc_id)read the properties of an existing documentget_acls(doc_id)delete_document(doc_id)change_document_state(uid, state=u'')read_user(name)read the properties of an user accountcreate_user(user,
first_name=None,
last_name=None,
email='a@b.c',
password='user',
company=None)Basic creation function the required properties are:
         identifier (generally it's the email
         first name
         name
         email
         passwordupdate_user(user,
first_name=None,
last_name=None,
email=None,
password=None,
company=None,
is_inactive=None)delete_user(user)get_users(query=u'*', data=False, max_results=None)query all users using a wildcard expression
    this internally get a multipage request and assembles the pagesget_directory(domain)query a vocabularyadd_directory_entry(directory, entry)get_groups(pattern)create_group(group)get_group(group)add_user_to_group(group, user)add_subgroup_to_group(group, subgroup)delete_group(group)init_session(host=u'local', login='', password='', auth='')Initialise the session according to the host modes: local, dev, prodconnect(host, login, auth='')on top of the init_session function permit to enter the hidden passwordget_login()retreive the actual loginpurge_document(session, path, title='', edms='')Deep suppression of a given document (including from the Corbeille)init_objets_from_string(lignes, constructor, key, output_dict)init_objets(file_name, constructor, key, output_dict)Read a CSV file , building a dictionary of objectswe assume that the input file obeys the following format:the first line contains the object field listfields are separated by ';'empty lines are ignoredlines starting with '#' are ignoredevery line generates one object using the specified constructorthe specified key is the key to the dictionaryset_atrium_functional_domain(session, user, domain, role)call the SetAtriumFunctionalDomain primitiveset_atrium_is_inactive(session, user, is_inactive=True)call the SetAtriumIsInactive primitivetest_atrium_is_inactive(session, user)test if atrium_is_inactiveget_fds(session, cat="Laboratoire")Reading all functional domains for Laboratoires|Projets|Activites declared in the Atrium base :we get all primary spaces of type Laboratoire|Projet|Activite then whe read the FunctionalDomain metadata
this approach is needed since the FunctionalDomain vocabulary does not differenciate
Laboratoires | Projets | Activitéstest_user_role(session, user, fd)test if this user has a role for this functional domainreturn 2 values:
bool = True if the user exists
role or None = granted role.get_user_workspace(host, session, email)Get the user personal space to build the Atrium perma-linkbuild_account_creation_mail(email, prenom, nom, pwd, racine, url, role='Reader')Construct a mail contents after the account creationthis mail give
+ the password
+ the perma-link to the personal spacebuild_logging_creation_mail(email, prenom, nom, racine, role='Reader')Construct a mail contents after the account creationthis mail give
+ the password
+ the perma-link to the personal spacesendmail(sender, to, message)Sending a email to one single destination
the message itself has to be constructed using the MIMEText facility.get_random_password()Utility to create a random passwordcreate_user(host, session, nom, prenom, email, racine)creation of a user accountspecify the host mode (local|dev|prod)give name and first nameemail is the account identifierspecify the functional domain (IE. laboratory)Installation en tant que développeur, du packageatrium_toolsOn peut installer ce package à partir deGitLab, par exemple en téléchargeant et installant l'archive au format ZIP.
Mais il est aussi possible declonerdirectement le projet à partir deGitLabsi on souhaite contribuer
au développement.Ce logiciel est entièrement basé sur le langage Python. Il est développé en compatibilité avec la
version >=3.6 du langage Python.
Donc il est indispensable qu'une version >= 3.6 du langage Python soit installée sur votre machineEnsuite pour installer la suite logicielle voici les deux méthodes:en clonant le dépôt Git::mkdir myworkspace
cd myworkspace
git clonegit@gitlab.in2p3.fr:atrium/atrium_tools.gitpetit rappel pour modifier un élément en git::> [edit]...
> git status
> git commit -am "porquoi cette modification"
> git pushen récupérant une archive ZIP à partir de GitLab::à partir du site GitLabhttps://gitlab.in2p3.fr/atrium/atrium_toolsinstaller et dézipper l'archive