Aller au contenu

La version 0.1.0 est une première version, à l'essai. Voir ce qui n'est pas prouvé →

bogolang
EN

← Documentation

Le langage

La règle des classes, les types sur chaque ligne, ce qui diffère de Python, les nouvelles instructions, les éditions.

Toutes les pages de documentation

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 ..., et lazy 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.

Bogolang
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, et bogo test les exécute tous.
  • Un programme peut aussi contenir ses propres classes Test. bogo test FILE exé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 par Test n'est pas exécutée.
Bogolang
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/24 est un Net et 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.

Bogolang
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 :

Bogolang
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.
  • break et return sont refusés par la vérification. continue saute 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.

Bogolang
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.

Bogolang
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.

Bogolang
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".

Bogolang
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.

Bogolang
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.

Bogolang
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.

Bogolang
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.

Bogolang
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.