mtn_dpt

  1"""
  2Package `Maintenance`. Maintient les dépôts maquisdoc.
  3
  4Modifié le 08/12/23 @author: remy
  5
  6Attention dans cette documentation, le terme 'dépôt' désigne une composante
  7du projet maquisdoc. On utilisera 'dépot (GitHub)' pour désigner un dépôt
  8hébergé par GitHub. Par exemple, ce package est un dépot (GitHub)
  9[mtn-dpt](https://github.com/nicolair/mtn_dpt).
 10
 11La maintenance assure automatiquement la cohérence entre l'état local d'un dépôt dans lequel un
 12 auteur vient de travailler et les autres composantes du projet.
 13
 14Des scénarios de travail couvrant les actions les plus courantes sont définis à l'avance et la cohérence n'est assurée que pour ces scénarios. Ils sont précisés dans la documentation du fichier d'initialisation codant le manifeste du dépôt.
 15
 16Le rôle de la maintenance est de :
 17
 18* pousser les modifications locales vers le dépôt en ligne
 19 (un dépôt maquisdoc est un dépôt GitHub).
 20* compiler localement les images qui doivent l'être.
 21* pousser vers les espaces de diffusion les images nouvelles ou modifiées.
 22* mettre à jour la base de données en graphe.
 23
 24Chaque dépôt est un dossier de la machine de travail de l'auteur et un
 25dépôt(GitHub). Les scripts et modules de maintenance ne sont pas encore implémentés pour tous les dépôts. Actuellement:
 26
 27|Nom dossier local | Nom dépôt(GitHub) | Nom du script de maintenance |
 28| ---------------- | ----------------- | --------------------------- |
 29|math-exos         | [math-exos](https://github.com/nicolair/math-exos) | [`maintenir_mathExos`](maintenance/maintenir_mathExos.html)|
 30|math-pbs          | [math-pbs](https://github.com/nicolair/math-pbs) | [`maintenir_mathPbs`](maintenance/maintenir_mathPbs.html)|
 31|math-cours        | [math-cours](https://github.com/nicolair/math-cours) | [`maintenir_mathCours`](maintenance/maintenir_mathCours.html) |
 32|math-rapidexos    | [math-cours](https://github.com/nicolair/math-rapidexos) | à faire |
 33
 34Le script de maintenance importe des sous-modules spécifiques ainsi que des sous-modules communs.
 35
 36Par exemple, les sous-modules dont le nom se termine par `_mathExos` sont
 37spécifiques au dépôt d'exercices `math-Exos`.
 38
 39Sur la machine de travail de l'auteur, un dépôt est un sous-dossier
 40de `maquisdoc-depots` dont le nom contient un tiret '-'.
 41En python, les noms de modules ne doivent pas contenir de tiret. Les noms des
 42modules spécifiques sont formés en passant du tiret à la majuscule dans le
 43nom du dépôt. Exemple `init_mathExos` et `exl_mathExos`.
 44dans lesquels `math-exos` a été changé en `mathExos`.
 45
 46La maintenance utilise des modules externes à la bibliothèque Python standard. La gestion de l'environnement virtuel et des dépendances est assuré par [Poetry](https://python-poetry.org/docs/).  
 47Exemples de commande:
 48- `poetry install` pour installer localement les dépendances du projet définies dans `pyproject.toml`. 
 49- `poetry run python ./maintenir_mathExos.py`  pour lancer la maintenance du dépôt
 50 d'exercices.
 51- `poetry run pdoc "$PWD" ./docs` pour lancer la création de cette
 52 documentation.
 53
 54La maintenance d'un dépôt est lançée par le script indiqué dans le tableau précédent. Il importe d'abord le module spécifique d'initialisation (son nom commence par `init_`) représentant le *manifeste* du dépôt. Il importe ensuite des modules communs ainsi que d'autres modules spécifiques. Les différents types de modules et les classes définies sont précisés dans le paragraphe suivant. La maintenance du dépôt des problèmes est détaillée.
 55
 56####  Modules et classes
 57Les modules importés lors d'une maintenance sont de différents types.
 58
 59<div style="text-align: center;">
 60  Modules locaux communs
 61</div>
 62
 63| nom           | rôle             | importe |
 64| ------------- | ---------------- | --------- |
 65| `depot`       | [module principal](maintenance/depot.html) | `execlocal`, `espace`, `graphdb` |
 66| `execlocal`   | [définit la classe `Execlocal`](maintenance/execlocal.html) | `scantex`, `exl_` spécifique |
 67| `scantex`     | [outils d'analyse de fichiers .tex](maintenance/scantex.html) |     |
 68| `espace`      | [definit la classe `Espace`](maintenance/espace.html) |     |
 69| `graphdb`     | [définit la classe `Maquis`](maintenance/graphdb.html) | `bdg_` spécifique |
 70
 71
 72
 73<div style="text-align: center; margin-top: 5px;">
 74  Modules locaux spécifiques
 75</div>
 76
 77| nom            | rôle                       |
 78| -------------- | -------------------------- |
 79| `init_mathPbs` | [initialisation, manifeste](maintenance/init_mathPbs.html) |
 80| `exl_mathPbs`  | [scripts de manipulation de fichiers locaux](maintenance/exl_mathPbs.html) |
 81| `bdg_mathPbs`  | [manipulation de données de la base en graphe](maintenance/bdg_mathExos.html) |
 82| `init_mathExos` | [initialisation, manifeste](maintenance/init_mathExos.html) |
 83| `exl_mathExos` | [scripts de manipulation de fichiers locaux](maintenance/exl_mathExos.html) |
 84
 85
 86<div style="text-align: center; margin-top: 5px;">
 87  Modules de la bibliothèque Python
 88</div>
 89
 90| nom          | rôle  |
 91| -----------  | ----- |
 92| `os`         | [Operating system interface](https://docs.python.org/3.11/library/os.html#module-os) |
 93| `sys`        | [System-specific parameters and functions](https://docs.python.org/3.11/library/sys.html?highlight=sys#module-sys) |
 94| `importlib`  | [The implementation of import](https://docs.python.org/3.11/library/importlib.html?highlight=importlib#module-importlib) |
 95| `subprocess` | [Subprocess management](https://docs.python.org/3.11/library/subprocess.html?highlight=subprocess#module-subprocess) |
 96| `glob`       | [Unix style pathname pattern expansion](https://docs.python.org/3.11/library/glob.html)|
 97| `os.path`    | [Common pathname manipulations](https://docs.python.org/3.11/library/os.path.html) |
 98| `mimetypes`  | [Map filenames to MIME types](https://docs.python.org/3.11/library/mimetypes.html?highlight=mimetypes#module-mimetypes) |
 99
100<div style="text-align: center; margin-top: 5px;">
101  Modules externes
102</div>
103| nom          | rôle  |
104| -----------  | ----- |
105| `boto3`      |[client de l'API d'un espace](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html)|
106| `neo4j`      |[client de l'API de la base de données en graphe (neo4j)](https://neo4j.com/docs/api/python-driver/current/)|
107|`pdoc`        |[génération de cette documentation](https://pdoc.dev/docs/pdoc.html)|
108
109
110Les modules définissent diverses classes. Ce sont les instanciations de ces classes qui effectuent les différentes tâches de la maintenance.
111
112<div style="text-align: center;">
113  Classes
114</div>
115
116| nom         | module      | rôle |
117| ----------- | ----------- | ----- |
118| `Depot`     | `depot`     | instancie les 3 classes suivantes |
119| `Execlocal` | `execlocal` | interface avec le dossier local du dépôt  |
120| `Espace`    | `espace`    | interface avec l'espace Digital Ocean |
121| `Maquis`    | `graphdb`   | interface avec la base en graphe neo4j |
122
123####  Exemple avec *math-pbs*
124La maintenance est lancée par la commande
125
126    python3 maintenir_mathPbs
127
128dans le dossier contenant le script.
129
130Ce script importe les modules `init_mathPbs` et `depot` puis instancie un objet `Depot`.  
131Le module `depot` importe les modules `execlocal`, `espace` et `graphdb`.  
132L'initialisation de l'instance de `Depot` instancie
133- un objet `Execlocal`
134- un objet `Espace`
135- un objet `Maquis`
136
137L'instanciation de l'objet `Execlocal` met à jour le dossier local et extrait du dépôt les données locales utiles aux traitements suivants.
138
139L'instanciation de l'objet `Espace` met à jour l'espace associé au dépôt.
140
141> Le module `boto3` fournit un client Python pour l'API de l'espace.  
142> Les credentials d'accès à un espace sont des clés générées à partir de l'interface Digital Ocean. Ces clés sont stockées localement dans le fichier `~/.aws/credentials` auquel accède silencieusement le client `boto3`.
143
144
145L'instanciation de l'objet `Maquis` met à jour la partie de la base en graphe associée au dépôt.
146
147> Le module `neo4j` fournit un client Python pour l'API de la base en graphe.  
148> Les credentials d'accès à la base (user, password) sont récupérés (`sp_connect_data`) à partir de variables d'environnement lors de l'importation de `init_mathPbs`.
149
150
151"""
152
153import os
154import sys
155
156# pour permettre l'import programmatique
157localpath = os.path.dirname(__file__)
158if localpath not in sys.path:
159    sys.path.append(os.path.dirname(__file__))
160
161__all__ = [
162    "maintenir_mathCours",
163    "maintenir_mathExos",
164    "maintenir_mathPbs",
165    "depot",
166    "init_mathCours",
167    "init_mathExos",
168    "init_mathPbs",
169    "scantex",
170    "execlocal",
171    "exl_mathCours",
172    "exl_mathExos",
173    "exl_mathPbs",
174    "graphdb",
175    "bdg_mathCours",
176    "bdg_mathExos",
177    "bdg_mathPbs",
178    "espace"
179    ]