Guides pratiques › Écrire les handlers en TypeScript ou Python

Guides pratiques

Handlers en TypeScript ou en Python

Le comportement d’un projet peut se trouver dans des fichiers .py ou .ts placés à côté du modèle, là où les outils de votre éditeur vous aident. archec relie chaque fonction à sa place dans le modèle par son nom. Il copie le code dans le projet Arche et récupère le code que vous modifiez dans l’application Arche. Cette page traite de ces fichiers ; le contrat avec Arche est décrit dans handlers.md.

Un premier fichier de code#

Enregistrez ceci sous main.arche. La fonction fn main du compteur n’a pas de corps dans le modèle : elle prend le def main de counter.py.

project "Counter" {
  handlers python
}

message TICK { n: int32 }

component Counter "Counter" {
  code "counter.py"
  out tx: data sends TICK
  var n:  int32 = 0
  fn main
}

component Display "Display" {
  in rx: data receives TICK
}

system Desk {
  part counter: Counter
  part display: Display
  counter.tx -> display.rx
}
Diagramme : Desk
Ce qu’archec dessine depuis ce code : Desk

Et ceci sous counter.py, à côté :

from arche import *

async def main(self):
    while True:
        await wait(ms(10))
        self.n += 1
        send(self.tx, TICK(n=self.n))

Lancez-le :

$ archec sim main.arche --for 30ms
Counter — system Desk, 30.000 ms simulated
   10.000 ms  counter.tx → display.rx  TICK {"n":1}
   20.000 ms  counter.tx → display.rx  TICK {"n":2}
   30.000 ms  counter.tx → display.rx  TICK {"n":3}

3 message(s), 0 state change(s)

archec stubs main.arche écrit un paquet arche typé. Votre éditeur connaît ainsi les noms qu’apporte from arche import *. Le paquet est écrit dans .arche/typings, pas à côté de votre code :

$ archec stubs main.arche
✓ .arche/typings/arche/__init__.pyi
✓ .arche/typings/arche/_model.pyi
  pyright: extraPaths = [".arche/typings"] under [tool.pyright] in pyproject.toml · mypy: mypy_path = ".arche/typings"

__init__.pyi contient les fonctions d’aide d’Arche, et il est le même pour tous les modèles. _model.pyi contient les messages et les constantes de ce modèle. L’extension VS Code écrit d’elle-même les mêmes fichiers, et Pylance les trouve sans aucun réglage (voir editor.md).

En ligne de commande, indiquez au vérificateur où se trouve le paquet. Dans pyproject.toml :

[tool.pyright]
extraPaths = [".arche/typings"]

[tool.mypy]
mypy_path = ".arche/typings"

Utilisez extraPaths de pyright, pas stubPath : avec stubPath, pyright trouve les noms mais avertit que le module n’a pas de source.

  • Un fichier principal qui porte un autre nom a son propre dossier : archec stubs bench.arche écrit .arche/typings/bench/arche/, et affiche le chemin à utiliser.
  • --out <dir> écrit le paquet dans le dossier que vous nommez.
  • --beside écrit un seul arche.py à côté des fichiers .py, comme le faisaient les versions précédentes.
  • Le dossier a son propre .gitignore : git l’ignore, et il est réécrit à partir du modèle.

Le langage des handlers#

Un projet indique le langage dans lequel son comportement est écrit :

  • project { handlers typescript }. C’est ce qu’écrit archec new.
  • python.
  • arche : le langage d’action, qu’archec traduit.

Les corps TypeScript reçoivent self. Quand un message les a déclenchés, ils reçoivent aussi msg, un objet { name, …fields }. L’API est celle d’Arche : await wait(ms(10)), send(self.out, MSG({ f: 1 })), await goto("Run").

archec lit le TypeScript sans que TypeScript soit installé. Il l’exécute dans archec sim, écrit .arche/typings/arche.d.ts pour l’éditeur (archec stubs) et indique le langage à Arche dans simulation.yaml. Pour un exemple, voir examples/ts-handlers.

Une partie du TypeScript est portable : elle s’en tient à ce que le langage d’action sait dire. Cela comprend les affectations, if, while, le for à compteur, send, goto, wait, log, Math, les fonctions de la part et msg.field. archec gen --target c|embassy|go traduit le TypeScript portable comme il traduit ```arche, et archec difftest le compare à son C. Pour tout le reste, archec check nomme la construction (ts-portable) et le code généré contient un TODO (handlers.md).

Pour passer un modèle dans un autre langage, lancez archec convert-handlers main.arche --to typescript (ou python, arche). La commande réécrit sur place les blocs, les fichiers de code et les gardes du modèle.

  • Depuis ```arche, le résultat est exact.
  • Depuis Python et TypeScript, la conversion se fait instruction par instruction.
  • Ce qui ne se traduit pas reste sous forme de commentaire TODO(convert). archec check continue de le signaler tant que vous ne l’avez pas réécrit.

Du code dans des fichiers .py et .ts#

Cette section traite des corps Python gardés dans des fichiers .py à côté du modèle. La suivante traite du chemin retour, depuis l’application Arche et le simulateur.

Un corps que le langage d’action sait exprimer se lit mieux dans un bloc ```arche : voir les concepts. Un code plus long se lit mieux dans un fichier .ts ou .py, avec les outils de votre éditeur. Un fichier .ts se relie de la même façon ; ses fonctions ressemblent à export function main(self: Ctrl) { … }.

component ctrl {
  code "ctrl.py"
  fn main                                  // ← def main(self) in ctrl.py
  in sense: i2c receives SAMPLE { on-receive on_sense }
  states { state Off; state On { on-enter enter_on } }   // on-exit: def on_exit_On, by its name
}
Diagramme : ctrl
Ce qu’archec dessine depuis ce code : ctrl

Comment un def se relie au modèle :

  • Un fn sans bloc prend le def du même nom.
  • Chaque propriété de code prend le def qu’elle nomme : on-enter, on-exit, on-receive, on-write, body et l’/ action d’une transition.
  • Certains noms se relient sans rien écrire : on_enter_<State>, on_exit_<State>, on_receive_<port> et on_write_<MEMORY>.
  • code sur le projet ou sur un système désigne un fichier partagé. Ses defs ne se relient que lorsqu’ils sont nommés.
  • Les paramètres d’un def sont self et les arguments du fn. Pour un hook, ce sont les noms qu’Arche donne à ce hook : msg, rise, from_, writer, etc.
  • Un def sans self est une simple fonction, comme en contient le .py d’une bibliothèque. Il se relie à un fn dont les paramètres ont les mêmes noms, dans le même ordre : def gcd(a, b) se relie à fn gcd(a: int64, b: int64) -> int64. Un fn gcd nu, qui ne dit aucun paramètre, prend ceux du def.
  • La docstring d’un def devient la description de l’élément.

Arche garde le Python à l’intérieur de ses fichiers de projet. archec copie donc chaque corps. Le projet Arche est identique à celui que vous obtiendriez en écrivant le même code en ligne.

  • archec fmt --extract-code --write déplace les blocs existants vers des fichiers : un fichier par composant, ou un seul fichier avec --extract-code=behaviour.py. Des tests vérifient que le résultat ne change pas.
  • Les imports, constantes et fonctions utilitaires en tête de fichier sont copiés dans les corps qui les utilisent.
  • Chaque corps reçoit sa propre copie. Un nom de premier niveau ne peut donc pas garder d’état entre deux appels, et une fonction qui en modifie un est une erreur. Gardez plutôt l’état sur le composant (var n, self.n).
  • from arche import * ne sert qu’à l’éditeur. archec stubs écrit un paquet arche typé dans .arche/typings, avec les fonctions d’aide d’Arche et les messages et constantes du modèle. L’extension VS Code l’écrit d’elle-même. Pylance ou pyright complètent et vérifient alors le code.

Le Python que le langage d’actions ne sait pas dire#

Certain Python n’a pas de traduction : une liste qui grandit, un dict, un entier au-delà de 64 bits, numpy. Un tel corps tourne quand même en simulation :

  • archec sim le lance dans un vrai python3, et la page dans Pyodide (sim.md). Un fichier code "x.py" est chargé comme un module : ses imports, ses fonctions d’aide et ses classes sont là.
  • Le simulateur d’Arche le lance, comme il lance tout Python.
  • archec sim main.arche --doctest lance les doctests du fichier.

Deux propriétés disent ce dont ce code a besoin :

component Primes {
  simulation-only                 // it runs in simulation and on a host, not on a microcontroller
  pip "sympy>=1.12"               // what its Python imports; archec sim prints the pip command when missing
  code "primes.py"
  fn primes_below(n: int64) -> any
}
Diagramme : Primes
Ce qu’archec dessine depuis ce code : Primes
  • simulation-only : les générateurs C, C++, Rust (Embassy) et Go refusent un déploiement qui le met sur un microcontrôleur, et disent pourquoi. Un processus sous Linux le garde. (sim.md)
  • pip : les paquets, comme pip les prend. pip "python>=3.14" demande une version de Python : archec sim cherche alors python3.14 dans le PATH.

Une valeur qui est une liste, un dict ou un objet est typée any dans le modèle (ou T[], ou une struct avec les clés du dict). sim.md dit comment chaque valeur passe.

Le chemin retour : le code modifié dans Arche et les erreurs du simulateur#

Chaque build écrit .archec/sourcemap.json dans le projet. Ce fichier note d’où vient chaque morceau de code, et le texte qu’il avait.

Le code modifié dans l’application Arche retourne à sa source#

archec pull main.arche --write compare trois choses :

  1. ce que le dernier build a écrit ;
  2. ce que contient le projet Arche maintenant ;
  3. ce que donnent vos sources maintenant.

Le code modifié uniquement dans Arche est réécrit là d’où il vient : dans le def du fichier .py, ou dans le bloc ``` du fichier .arche. Un def devient async def si le nouveau corps contient un await.

  • Un code modifié des deux côtés est un conflit. Vous le fusionnez vous-même.
  • Une modification du code de premier niveau copié dans un corps vous revient aussi. Faites-la dans le fichier .py.
  • Un build refuse d’écraser du code modifié dans Arche et pas encore récupéré. --force abandonne ce code.
  • Dans VS Code, un enregistrement dans Arche propose le pull. Le réglage arche.pullOnChange vaut ask, always ou never. Le pull s’applique en une seule modification, que vous pouvez annuler. Arche: Pull Code Changes le fait à la main.

Seul le code revient. Les positions, les noms et les autres modifications faites dans l’application sont toujours écrasés par le build suivant.

Les erreurs du simulateur pointent vers vos lignes#

Arche signale une erreur sur une ligne de sa copie, par exemple ZeroDivisionError (Controller › Control loop, line 4).

  • archec test et archec run font le build, lancent arche-cli et ajoutent la ligne source : (Controller › Control loop, line 4 → ctrl.py:32).
  • archec where main.arche "<error>" fait de même pour n’importe quel texte. arche-cli test out | archec where main.arche - aussi.
  • Dans VS Code, Arche: Run Tests place chaque erreur sur sa ligne dans la vue Problems. Arche: Go to Simulator Error… prend une erreur collée depuis l’application Arche.
  • L’on-enter et l’on-exit d’un état partagent une même étiquette dans les messages d’Arche. Les deux lignes sont donc proposées.

Limites#

Ces limites sont décrites plus haut ; les voici réunies.

  • Le Python que le langage d’actions ne sait pas dire n’est pas traduit : archec gen écrit un TODO pour lui sur un hôte, et le refuse sur un microcontrôleur quand le composant dit simulation-only. Il ne tourne qu’en simulation.

  • convert-handlers traduit Python et TypeScript instruction par instruction. Ce qu’il ne sait pas traduire reste en commentaire TODO(convert), à réécrire.

  • Un nom de premier niveau dans un fichier .py ne peut pas garder d’état entre deux appels : chaque corps reçoit sa propre copie. Gardez l’état sur le composant.

  • Une modification du code de premier niveau copié dans un corps n’est pas récupérée depuis Arche. Faites-la dans le fichier .py.

  • Seul le code revient de l’application Arche. Les positions, les noms et les autres modifications faites là-bas sont écrasés par le build suivant.

  • L’on-enter et l’on-exit d’un état partagent une même étiquette dans les messages d’Arche : une erreur à cet endroit pointe donc vers les deux lignes.