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
}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 seularche.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’écritarchec 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 checkcontinue 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
}Comment un def se relie au modèle :
- Un
fnsans 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,bodyet l’/ actiond’une transition. - Certains noms se relient sans rien écrire :
on_enter_<State>,on_exit_<State>,on_receive_<port>eton_write_<MEMORY>. codesur 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
selfet les arguments du fn. Pour un hook, ce sont les noms qu’Arche donne à ce hook :msg,rise,from_,writer, etc. - Un def sans
selfest une simple fonction, comme en contient le.pyd’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. Unfn gcdnu, 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 --writedé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 paquetarchetypé 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 simle lance dans un vraipython3, et la page dans Pyodide (sim.md). Un fichiercode "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 --doctestlance 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
}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 simcherche alorspython3.14dans 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 :
- ce que le dernier build a écrit ;
- ce que contient le projet Arche maintenant ;
- 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é.
--forceabandonne ce code. - Dans VS Code, un enregistrement dans Arche propose le pull. Le réglage
arche.pullOnChangevautask,alwaysounever. 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 testetarchec runfont 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 ditsimulation-only. Il ne tourne qu’en simulation.convert-handlerstraduit Python et TypeScript instruction par instruction. Ce qu’il ne sait pas traduire reste en commentaireTODO(convert), à réécrire.Un nom de premier niveau dans un fichier
.pyne 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.