Aller au contenu

Documentation pour les développeurs ScoDoc

Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.

Pour le développement de logiciels externes, utiliser l'API.

Accès à la plate-forme Gitea.

Informations générales

Les échanges se font sur Discord, voir contacts. Il y a un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel Viennet (@emm).

Développer sur ScoDoc

Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9.

Installation d'un serveur de développement

Quelques conseils pour configurer votre serveur de développement

Style et formatage du code

L'ancienneté de la base de code a rendu le style un peu incohérent, mais cela s'est nettement amélioré avec ScoDoc 9 (respect PEP 8).

Le code DOIT être formaté avec black avant tout commit (configurez votre éditeur pour appeler black à l'enregistrement).

Documentation

On pourra adopter le style "Google": https://google.github.io/styleguide/pyguide.html#383-functions-and-methods

Exemple:

    """Description résumée de la fonction

    blah blah sur la fonction

    Args:
        table_handle: An open smalltable.Table instance.
        keys: A sequence of strings representing the key of each table
          row to fetch.  String keys will be UTF-8 encoded.
        require_all_keys: Optional; If require_all_keys is True only
          rows with values set for all keys will be returned.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {b'Serak': ('Rigel VII', 'Preparer'),
         b'Zim': ('Irk', 'Invader'),
         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
    """

Git

Voir la page sur git et ScoDoc

Tests et tests unitaires

Voir TestsScoDoc

Cache Redis

Certains objets couteux à calculer sont cachés. Depuis ScoDoc 9, on utilise Redis, via flask-caching.

Au besoin, mémo:

  • client ligne de commande: https://redis.io/topics/rediscli

  • afficher les clés: redis-cli KEYS '*'

  • redis-cli TTL key affiche le TTL d'une clé, -1 si infini.

  • redis-cli -r -1 -i 3 KEYS '*_NT_*' surveille certaines clés (ici NT), affiche toutes les 3 secondes.

  • flask clear-cache efface le cache Redis.

Re-création du virtualenv

ScoDoc est livré avec un "virtualenv", qui contient tous les modules python nécessaires. Il se trouve sous /opt/scodoc/venv. Si vous souhaitez repartir de zéro, tester de nouvelles versions de certaines bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ainsi:

  # en tant qu'utilisateur scodoc
  cd /opt/scodoc
  /bin/rm -rf venv # ou mv ...
  python3 -m venv venv
  source venv/bin/activate
  pip install wheel

Puis soit vous installez les versions "officielles" (testées)

  pip install -r requirements-3.11.txt

Soit vous prenez les versions les plus à jour disponibles. Une façon rapide de faire ceci est:

  cut -d= -f 1 requirements-3.11.txt | xargs pip install

à adapter selon vos objectifs.

Pour régénérer le fichier indiquant la liste des paquets:

  pip freeze > requirements-3.11.txt

Enfin, pour mettre à jour les paquets pip, il faut dégeler les versions (unpin) puis upgrader et re-générer le fichier, comme suit:

cp requirements-3.11.txt requirements.txt
sed -i 's/[~=]=/>=/' requirements.txt
pip install -U -r requirements.txt
pip freeze > requirements-new.txt
# et si tout va bien
mv requirements-new.txt requirements-3.11.txt

Note: la mise à jour par apt recrée le virtualenv à chaque fois.

Roadmap

Voir aussi