atrium-tools 4.3.3
Atrium utilities

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 clientes

Deux composantes principales:

- **atrium_shell**: application cliente offrant plusieurs actions de navigation vers la base Atrium
- **nuxeolib**: 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.


Installation
============

Installation de base
--------------------

Ici, nous allons exploiter le mécanisme standard du monde Python: **pip** pour installer ce package Python.

Le package **atrium_tools** a été configuré au format standard des packages Python, et a été déposé dans le
dépôt officiel **PyPi**.

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> -ls

Pour mettre à jour la version du package:

    > pip install --upgrade atrium-tools

Il est possible de questionner l'installation actuelle:

    > pip show atrium-tools


Ou bien de désinstaller le package:

    > pip uninstall -y atrium-tools

Et de désactiver l'environ `atrium` Python

    > deactivate

L'application atrium_shell
==========================

Introduction
------------

Cette application permet d'interroger la base Atrium un peu comme la commande **ls** en unix ou **dir** en windows.

Authentification
----------------

Pour accéder au serveur Nuxeo, une authentification est nécessaire. Deux méthodes d'authentification sont possibles:

- en utilisant le paramètre ``login=xxx`` sur la ligne de commande. Ensuite, le mot de passe
  sera demandé en interrogation cachée

- en 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/.netrc`
Ce fichier doit obligatoirement être protégé ainsi:

    > ls -al ../.netrc
    -rw------- 1 arnault SI 399 Apr  8 17:10 ../.netrc

Autrement dit, seul l'utilisateur doit avoir accès à ce document

Ce fichier texte contient des lignes au format suivant:

    machine atrium.in2p3.fr login <identifiant> password <motdepasse>

Si le fichier `~/.netrc` existe et que la variable d'environnement `HOME` est définie, 
alors il ne sera pas nécessaire d'utiliser l'argument `login=xxx` 
et la connexion Atrium sera établie automatiquement avec l'identifant décrit dans le ficher `~/.netrc` 


Arguments
---------

    login = 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 droits

Quelques précisions:

* La cible de départ peut être spécifiée:
    * soit avec `cd` pour un espace institutionnel
    * soit avec `user` pour un espace personnel, en spécifiant l'intitulé du compte Atrium
* L'option `set_acl` s'applique uniquement au dossier spécifié avec `to=<dossier>`
* L'option `rm_acl` s'applique récursivement à tous les dossiers enfants à partir du dossier `to=<dossier`
* L'option `subs_acl` s'applique récursivement à tous les dossiers enfants à partir du dossier `to=<dossier`
* Dans l'option `subs_acl` on peut substituer une groupe/user indépendemment de la permission en utilisant "%" pour la permission
* Les options `ls`, `csv`, `draw` exploitent l'option `depth=n`

Utilisation
-----------

Quelques 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+2



Nuxeolib
=========

Ce 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 path

- create_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 document


- get_acls(doc_id)
- delete_document(doc_id)
- change_document_state(uid, state=u'')
- read_user(name)

        read the properties of an user account


- create_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
               password


- update_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 pages


- get_directory(domain)

        query a vocabulary


- add_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, prod

- connect(host, login, auth='')

    on top of the init_session function permit to enter the hidden password

- get_login()

    retreive the actual login

- purge_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 objects

    - we assume that the input file obeys the following format:
      + the first line contains the object field list
      + fields are separated by ';'
      + empty lines are ignored
      + lines starting with '#' are ignored
    - every line generates one object using the specified constructor
    - the specified key is the key to the dictionary

- set_atrium_functional_domain(session, user, domain, role)

    call the SetAtriumFunctionalDomain primitive

- set_atrium_is_inactive(session, user, is_inactive=True)

    call the SetAtriumIsInactive primitive

- test_atrium_is_inactive(session, user)

    test if atrium_is_inactive

- get_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és

- test_user_role(session, user, fd)

    test if this user has a role for this functional domain

     return 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-link

- build_account_creation_mail(email, prenom, nom, pwd, racine, url, role='Reader')

    Construct a mail contents after the account creation
     - this mail give
      + the password
      + the perma-link to the personal space

- build_logging_creation_mail(email, prenom, nom, racine, role='Reader')

    Construct a mail contents after the account creation
     - this mail give
      + the password
      + the perma-link to the personal space

- sendmail(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 password

- create_user(host, session, nom, prenom, email, racine)

    creation of a user account
     - specify the host mode (local|dev|prod)
     - give name and first name
     - email is the account identifier
     - specify the functional domain (IE. laboratory)

Installation en tant que développeur, du package **atrium_tools**
-----------------------------------------------------------------

On peut installer ce package à partir de **GitLab**, par exemple en téléchargeant et installant l'archive au format ZIP.
Mais il est aussi possible de *cloner* directement le projet à partir de **GitLab** si 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 machine

Ensuite pour installer la suite logicielle voici les deux méthodes:

1. en clonant le dépôt Git::

    > mkdir myworkspace
    > cd myworkspace
    > git clone git@gitlab.in2p3.fr:atrium/atrium_tools.git

petit rappel pour modifier un élément en git::

    > [edit]...
    > git status
    > git commit -am "porquoi cette modification"
    > git push


2. en récupérant une archive ZIP à partir de GitLab::

    à partir du site GitLab https://gitlab.in2p3.fr/atrium/atrium_tools
    installer et dézipper l'archive