Cette page décrit Bogolang lui-même : comment un fichier est organisé, ce que veut dire « un type sur chaque ligne », ce qui diffère de Python, et les instructions que Bogolang ajoute. Les commandes intégrées sont sur les pages de chaque groupe, et chaque nom est dans reference.md.
Bogolang est Python 3.15 avec des ajouts pour le travail réseau et télécom. Un fichier .bogo
est lu, vérifié et exécuté sur un moteur Python 3.15 que Bogolang apporte. Rien n'est compilé
en code natif. La vérification a lieu avant chaque exécution, et un programme qui contient une
erreur ne démarre pas.
Comment un fichier est organisé
Le haut d'un fichier .bogo contient seulement :
- la ligne
edition 2027, comme première ligne qui n'est ni vide ni un commentaire ; - un texte descriptif (une docstring), comme première instruction ;
- des imports :
import x,from x import y,from __future__ import ..., etlazy import; - des classes.
Les commentaires peuvent se trouver n'importe où. Toute autre instruction au niveau du haut est
refusée, un message par instruction. Cela couvre une fonction, une affectation, un appel, if,
for, try, with et un alias type :
top.bogo:3:1: error: code must be inside a class
x = 1
^
Only imports and classes stand at the top of a file. Put this line in a method of a class.
Le corps d'une classe contient seulement un texte descriptif comme première instruction, ...,
pass, des champs (avec ou sans type écrit), des méthodes (aussi async), des classes, des
alias type, et les deux blocs Bogolang rule et on. Une instruction isolée dans le corps
d'une classe est refusée, là où Python l'exécuterait :
top.bogo:6:5: error: this line cannot stand in the body of a class
print("hi")
^
A class holds fields, methods, classes, rule and on. Put this line in a method.
La règle vaut pour toute classe, aussi pour une classe dans une classe ou dans une méthode.
Dans une méthode, tout Python et toutes les instructions de Bogolang sont valides, sauf on.
Tout ce que Python offre pour les classes reste : l'héritage, les décorateurs, @dataclass,
Enum, Protocol, les propriétés, les méthodes de classe.
Où un programme commence
Un programme commence dans la classe dont le nom correspond au nom du fichier. Seuls les
lettres et les chiffres sont comparés, en minuscules : link_check.bogo, LinkCheck.bogo et
link-check.bogo correspondent tous à class LinkCheck. Un nom de fichier qui commence par un
chiffre reçoit un trait de soulignement devant : 1st_check.bogo correspond à
class _1stCheck.
main s'écrit exactement ainsi : le décorateur @staticmethod et aucun autre, pas async,
une entrée nommée args de type list[str], sans valeur par défaut, et le type de résultat
None. args contient les mots tapés après le nom du fichier.
edition 2027
"""Says which routers answer."""
class LinkCheck:
"""Pings each router twice."""
routers: list[IP] = [192.0.2.1, 192.0.2.2]
@staticmethod
def main(args: list[str]) -> None:
for r in LinkCheck.routers:
print(r, ping(r, count=2))
Dans une méthode, un champ de la classe est atteint par la classe, LinkCheck.routers, ou par
self, comme en Python.
Quand le programme s'exécute, le fichier est d'abord lu de haut en bas : les champs reçoivent
leurs valeurs, les règles sont enregistrées et les écouteurs de on s'ouvrent. Puis main
est appelé.
La classe de départ n'est exigée que du fichier qui est exécuté (bogo run, bogo FILE.bogo,
bogo pack). Un fichier sans classe de départ est une bibliothèque : d'autres fichiers
importent ses classes, et bogo check et bogo test l'acceptent. bogo run link_check.bogo
sur un tel fichier dit
link_check.bogo:1:1: error: this file has no class LinkCheck with a main method, suivi des
quatre lignes d'une classe de départ. Une classe sans main reçoit
class LinkCheck has no main method, et un main écrit autrement reçoit
main is not written the way a program starts.
Tests
Un test est une méthode dont le nom commence par test_, dans une classe dont le nom commence
par Test, au niveau du haut d'un fichier. Il ne prend que self et ne renvoie rien. Il
réussit quand il se termine sans erreur, et utilise assert comme en Python.
- Dans un projet, les fichiers de test sont
tests/test_*.bogo, etbogo testles exécute tous. - Un programme peut aussi contenir ses propres classes
Test.bogo test FILEexécute celles d'un fichier. - Chaque test s'exécute sur un nouvel objet de sa classe, donc un champ changé par un test est neuf pour le suivant. Les tests s'exécutent dans l'ordre où ils sont écrits.
- Un test avec une autre entrée échoue avec :
a test takes self only. Write it as: def test_name(self) -> None:. - Une méthode
test_dans une classe dont le nom ne commence pas parTestn'est pas exécutée.
edition 2027
class Plan:
@staticmethod
def halves(n: Net) -> list[Net]:
return n.split(n.prefix + 1)
class TestPlan:
def test_a_24_gives_two_25(self) -> None:
assert Plan.halves(192.0.2.0/24) == [192.0.2.0/25, 192.0.2.128/25]
tools.md donne les options de bogo test.
Des types sur chaque ligne
Chaque valeur du code Bogolang a un type connu avant que le programme s'exécute. En pratique :
- Chaque fonction et méthode donne le type de chaque entrée et de son résultat.
- Une variable prend le type de sa première valeur.
net = 192.0.2.0/24est unNetet le reste. Lui donner un texte plus tard est une erreur. - Une variable dont la première valeur ne dit rien de son type est déclarée :
rows: list[str] = []. - Rien ne peut avoir le type « inconnu ». Un
Anyécrit est refusé.
Écrire le type de chaque variable est aussi permis. Les exemples utilisent les deux styles.
used: list[Net] = [192.0.2.0/26]
free = next_free(192.0.2.0/24, 26, used)
total = free.size - 2
print(free, total)
Ce que la vérification dit pour chaque cas :
| Erreur | Message |
|---|---|
| Une méthode sans types | this method has no types |
rows = [] |
rows needs a type, avec l'indication For example: rows: list[<type>] = ... |
net = 192.0.2.0/24, puis net = "x" |
this value is a str, but the variable is declared as Net |
Une valeur venant de code sans types, comme json.loads(...) |
the type of this value is unknown |
Valeurs venant de code sans types
Un paquet Python qui a des types est utilisé tel quel. Une valeur venant d'un paquet sans types reçoit son type sur la ligne où elle entre :
import json
class Read:
@staticmethod
def count(text: str) -> int:
n: int = json.loads(text)
return n
Cette ligne est aussi testée quand le programme s'exécute : si la valeur n'est pas un int, le
programme s'arrête là avec un message clair. Pour un conteneur comme list[int], seul
l'extérieur est testé. Une ligne name: type = value dans le corps d'une classe n'est pas
testée quand le programme s'exécute, donc une telle valeur entre dans une méthode.
Sans le type, la vérification dit :
kinds.bogo:8:16: error: the type of this value is unknown
data = json.loads("{}")
^^^^^^^^^^^^^^^^
It comes from code that has no types. Give it a type on the line where it enters,
for example: count: int = ...
Un lambda donné comme key= à max, min, sorted ou .sort passe la vérification quand
il ne nomme que son propre paramètre et des noms intégrés, comme dans key=lambda r: r.loss.
Celui qui nomme une variable de l'extérieur est refusé. L'indication dit quoi écrire : une
petite méthode avec des types, donnée par son nom.
Untyped
Un objet venant d'un paquet sans types, comme un objet de connexion, ne peut pas recevoir un
vrai type. Déclarez-le Untyped. Il peut alors être appelé, lu, écrit, indexé, parcouru en
boucle et utilisé dans un bloc with. Chaque résultat reçoit son propre type sur une ligne à
part :
```bogo skip conn: Untyped = oldpackage.connect("192.0.2.1") banner: str = conn.read_banner() conn.close()
Refusé avant l'exécution : passer une valeur `Untyped` là où un type est demandé, faire de
l'arithmétique dessus, et la donner à une variable qui a déjà un type. `bogo check` liste chaque
ligne qui contient un objet `Untyped`, pour relecture, après `no errors`. Ce qui est fait avec
l'objet lui-même n'est vérifié que lorsque le programme s'exécute.
## Ce qui diffère de Python
| Python | Bogolang |
|---|---|
| N'importe quelle instruction au niveau du haut d'un fichier | Seulement des imports et des classes (voir plus haut) |
| Des instructions isolées dans le corps d'une classe | Refusées |
| Un programme commence en haut du fichier | Il commence dans `main` de la classe qui porte le nom du fichier |
| Les types sont facultatifs | Les types sont obligatoires, et vérifiés avant chaque exécution |
| `192.0.2.1` est une erreur de syntaxe | Un littéral `IP`. Aussi les sous-réseaux, les MAC et les unités ([types-and-units.md](types-and-units.md)) |
| `ping` et le reste doivent être importés | Les noms intégrés sont présents dans chaque fichier, sans import |
| `python file.py` | `bogo run file.bogo` ou `bogo file.bogo` |
Un programme peut réutiliser un nom intégré pour quelque chose à lui, comme il peut réutiliser
un nom intégré de Python. Dans une méthode, un nom local l'emporte toujours. Il reste un cas :
un fichier qui définit son propre `Net` ou `Power` ne peut pas aussi écrire le littéral
correspondant.
Les nouveaux mots (`where`, `parallel`, `change`, `apply`, `rollback`, `verify`, `every`,
`wait`, `retry`, `only`, `watch`, `alert`, `on`, `rule`) ne sont spéciaux qu'aux endroits
montrés ci-dessous. Partout ailleurs, ce sont des noms ordinaires.
Limites du lecteur : un littéral dans les `{}` d'une f-string n'est pas reconnu (mettez d'abord
la valeur dans une variable), et la ligne d'en-tête de chaque nouvelle instruction doit tenir
sur une seule ligne.
## Les nouvelles instructions
| Instruction | Où elle s'écrit | Page |
|---|---|---|
| `for ... where ... parallel` | Dans une méthode | ci-dessous |
| `wait until`, `retry`, `every`, `only between` | Dans une méthode | ci-dessous |
| `watch`, `alert when` | Dans une méthode | [watch-listen.md](watch-listen.md) |
| `change on` | Dans une méthode | [changes.md](changes.md) |
| `rule` | Dans le corps d'une classe ou dans une méthode | [config-audit-templates.md](config-audit-templates.md) |
| `on syslog`, `on trap`, `on netflow` | Dans le corps d'une classe seulement | [watch-listen.md](watch-listen.md) |
### `for ... where ... parallel`
`where` saute les éléments pour lesquels la condition est fausse. `parallel N` exécute le bloc
pour au plus N éléments en même temps. L'un ou l'autre peut être utilisé seul.
```bogo
devices: list[Device] = inventory("devices.csv")
for d in devices where d.role == "core" parallel 4:
with ssh(d) as s:
print(d.name, s.show("version").text.splitlines()[0])
for f in last_failures():
print(f)
Dans un bloc parallèle :
- Une variable qui reçoit une valeur dans le bloc appartient à cette seule exécution. Les variables de l'extérieur peuvent être lues, et on peut ajouter à une liste de l'extérieur.
breaketreturnsont refusés par la vérification.continuesaute l'élément en cours.- Ce qu'une exécution affiche est retenu et montré d'un seul bloc, dans l'ordre de la liste.
- Une erreur dans une exécution n'arrête que cette exécution. Après la boucle,
last_failures()donne les éléments qui ont échoué, avec la raison. Si le programme ne le lit pas, un résumé est affiché à la fin et l'exécution se termine avec un code d'échec.
Une limite : la vérification ne refuse pas encore un programme qui lit une variable du bloc après la boucle. Un tel programme s'arrête quand il s'exécute.
wait until
Teste une condition toutes les 5 secondes, ou selon la durée donnée après every, jusqu'à ce
qu'elle soit vraie. Une erreur si le délai d'attente expire d'abord.
wait until tcping(192.0.2.1, 22) timeout 2min every 10s
retry
Exécute le bloc. Sur une erreur, il l'exécute de nouveau, jusqu'au nombre total d'essais, avec
une pause facultative. Après le dernier essai, la dernière erreur est levée. Un change dans
un retry est refusé : un changement qui échoue fait l'objet d'un retour arrière, et la raison
est trouvée avant qu'il soit envoyé de nouveau.
retry 3 every 5s:
r: PingResult = ping(192.0.2.1, count=2)
print(r)
every
Exécute le bloc, attend que la période soit passée depuis le début de cette exécution, et
recommence jusqu'à ce que le programme soit arrêté (Ctrl+C) ou que le bloc utilise break.
turns = 0
every 1min:
print(now(), ping(192.0.2.1, count=3))
turns += 1
if turns == 10:
break
only between : fenêtres horaires
Exécute le bloc seulement quand l'heure du jour dans un fuseau est dans la fenêtre. En dehors,
le programme s'arrête avec une erreur. Sous --dry, il affiche une ligne et saute le bloc à la
place. Une fenêtre peut passer minuit. Le fuseau est un nom simple comme UTC, ou un nom entre
guillemets comme "Europe/Paris".
only between time"22:00" and time"04:00" UTC:
print("inside the maintenance window")
En dehors de la fenêtre, l'erreur nomme la fenêtre et l'heure qu'il est dans ce fuseau.
watch et alert when
watch EXPR every PERIOD [for TIME] trace la valeur en direct dans le terminal jusqu'à ce
qu'il soit arrêté ou que la durée soit écoulée.
alert when CONDITION for TIME [per KEY] [as NAME]: exécute son bloc une fois quand la condition est vraie depuis cette durée, et une fois
quand elle disparaît. Il se trouve dans un bloc every ; dans une boucle, il a besoin de
per, pour que chaque élément garde sa propre mémoire.
hosts: list[IP] = [192.0.2.10, 198.51.100.20]
watch ping(192.0.2.10, count=1).avg every 1s for 1min
every 1min:
for h in hosts:
r: PingResult = ping(h, count=4)
alert when r.loss > 5pct for 3min per h as a:
print(h, "raised" if a.raised else "cleared", a.lasted)
change on
Un changement sur un équipement, avec les lignes qui l'annulent. Un changement sans rollback
est refusé par la vérification. changes.md donne les étapes qu'il suit.
sw: Device = Device(name="access-sw1", ip=192.0.2.21, platform="iosxe")
port: str = "GigabitEthernet1/0/5"
change on sw revert_after 5min:
apply:
interface {port}
description CAMERA-12
rollback:
interface {port}
no description
verify:
"CAMERA-12" in show(f"interfaces {port} description")
Les lignes sous apply et rollback sont du texte d'équipement, envoyé tel qu'il est écrit.
{name} met une valeur dans la ligne ; {{ et }} envoient de vraies accolades.
rule et on
Une rule est une liste de tests, un par ligne, chacun vrai ou faux pour un équipement.
audit(...) exécute les règles. Un bloc on écoute le syslog, les traps ou NetFlow, et
s'exécute pour chaque événement. Il s'écrit dans le corps d'une classe seulement ; son écouteur
s'ouvre quand la classe est lue, avant main.
edition 2027
class Watcher:
devices: list[Device] = [Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")]
rule "no telnet on the vty lines" for d where d.role != "server":
not config.has("transport input telnet")
on syslog port 5514 from devices matching "UPDOWN" as e:
print(e.received, e.device, e.message)
@staticmethod
def main(args: list[str]) -> None:
for c in listen(10min):
print(c.received, "events")
L'écouteur s'ouvre sur chaque adresse de l'ordinateur sauf si address en nomme une :
on syslog port 5514 address 192.0.2.50 from devices as e:. Un bloc on ne peut pas contenir
de change. Dans le bloc, un champ de la classe est atteint par la classe.
Éditions
Une édition fixe le sens du langage. Un Bogolang plus récent exécute chaque édition plus ancienne avec le sens qu'elle avait. Un changement qui modifierait ce que fait du code existant, ou qui retirerait quelque chose, ne vient que dans une nouvelle édition, après une édition d'avertissement.
- Il existe une seule édition aujourd'hui :
2027. - Un fichier seul l'indique sur sa première ligne :
edition 2027. - Un projet l'indique dans
bogo.toml, et ses fichiers n'ont pas besoin de la répéter. - Un fichier seul sans ligne d'édition s'exécute avec l'édition la plus récente et reçoit un
avertissement :
this file does not say which edition it is written for, avec la ligne à ajouter. - Une édition inconnue est une erreur qui liste les éditions connues.
Python 3.15
Le moteur est Python 3.15, et sa nouvelle syntaxe est utilisable dans le cadre de la règle des
classes. Essayé et testé dans Bogolang : lazy import, lazy from ... import, le dépaquetage
dans une compréhension de liste, d'ensemble et de dictionnaire, et le nom intégré
frozendict.
edition 2027
lazy import json
class Newer:
groups: list[list[int]] = [[1, 2], [3]]
@staticmethod
def main(args: list[str]) -> None:
flat = [*g for g in Newer.groups]
merged = {**d for d in [{"a": 1}, {"b": 2}]}
fixed = frozendict(a=1, b=2)
print(flat, merged, fixed["a"], json.dumps(flat))
Un lazy import d'un autre fichier .bogo compte comme un import simple : le fichier est
vérifié avec le programme.
Paquets Python
Chaque paquet Python fonctionne, importé tel quel. Dans un projet, ajoutez-en un avec
bogo add, qui l'installe dans l'environnement du projet et l'écrit dans bogo.toml et
bogo.lock :
bogo add requests
bogo add "netaddr>=1.3"
bogo add requests --from FOLDER
--from FOLDER installe à partir de fichiers de paquets dans un dossier, sans internet.
bogo remove NAME retire de nouveau un paquet. Un programme l'importe ensuite :
```bogo skip import requests
class Fetch: @staticmethod def main(args: list[str]) -> None: r = requests.get("https://192.0.2.80/status", timeout=5) code: int = r.status_code print(code) ```
Les paquets des commandes intégrées (Netmiko, pysnmp et les autres) font partie de Bogolang ;
un projet ne les ajoute pas. Les simples fichiers .py à côté d'un programme peuvent aussi
être importés. La règle des classes ne concerne que les fichiers .bogo.
Les types propres à Bogolang sont des objets Python ordinaires. .to_python() sur un IP ou
un Net donne l'objet du module ipaddress de Python, pour un paquet qui en veut un.