Cette page couvre ce qu'un programme rend aux personnes : un tableau à l'écran, un fichier CSV ou Excel, un graphique, un rapport en HTML, Word ou PDF, et un courriel. L'exemple report_chart utilise la plupart d'entre eux.
Lignes
table, export, chart et un rapport prennent tous des lignes. Une liste de lignes peut
contenir n'importe quelle sorte de chose, une seule à la fois :
| Une ligne est | Ses colonnes |
|---|---|
Un Row (issu de .table() sur une sortie d'équipement, Meraki, une API web) |
ses colonnes |
Un dict |
ses clés |
Un tuple nommé ou une classe NamedTuple |
ses champs |
Tout autre objet, comme un PingResult ou un LogEvent |
ses valeurs publiques ; les listes qu'il contient ne sont pas des colonnes |
| Une valeur simple (texte, nombre, adresse, quantité) | une colonne nommée value |
Chaque ligne d'une même liste doit être de la même sorte. Une liste mélangée est une erreur qui
nomme les deux sortes. Un AuditResult issu de audit() est pris comme ses lignes.
table
| Commande | Fait |
|---|---|
table(rows: Sequence[object] \| AuditResult, columns: list[str] \| None = None) |
affiche les lignes sous forme de tableau |
- Les nombres sont à droite, le texte à gauche. Les longues lignes ne sont pas coupées.
columnschoisit et ordonne les colonnes. Un nom qu'aucune ligne n'a est une erreur qui liste les colonnes existantes.Trues'afficheyes,Falses'afficheno, l'absence de valeur donne une cellule vide. UnSecrets'affiche toujours***.- Une liste vide affiche
(no rows).
rows: list[dict[str, str]] = [
{"host": "core-sw1", "ip": "192.0.2.1", "state": "up"},
{"host": "edge-rt2", "ip": "192.0.2.2", "state": "down"},
]
table(rows)
table(rows, ["host", "state"])
host ip state
-------- --------- -----
core-sw1 192.0.2.1 up
edge-rt2 192.0.2.2 down
host state
-------- -----
core-sw1 up
edge-rt2 down
export
| Commande | Fait |
|---|---|
export(rows: Sequence[object] \| AuditResult, path: str, columns: list[str] \| None = None) |
écrit les lignes dans un fichier |
La terminaison de path choisit le type. export n'écrit que deux types :
| Terminaison | Ce qui est écrit |
|---|---|
.csv |
UTF-8 avec une marque d'ordre des octets, pour qu'Excel l'ouvre avec les bons accents. Chaque valeur est du texte, telle que table l'affiche |
.xlsx |
Une feuille. La première ligne contient les noms des colonnes en gras, figée, avec un filtre. Les nombres sont écrits comme des nombres. Les colonnes sont aussi larges que leur texte, jusqu'à 60 caractères |
Toute autre terminaison est une erreur. D'autres fichiers sont écrits par d'autres commandes :
Topology.save écrit du .json, du .csv ou du .dot (voir
journaux et topologie), et une configuration ou un instantané a son propre
.save (voir équipements).
rows: list[dict[str, str]] = [{"host": "core-sw1", "state": "up"}]
export(rows, "hosts.csv")
export(rows, "hosts.xlsx", ["host"])
chart et picture
| Commande | Donne |
|---|---|
chart(rows: Sequence[object], x: str, y: str, path: str, kind: str = 'line', title: str = '') |
Picture : trace la colonne y en fonction de la colonne x et écrit un .png |
picture(path: str) |
Picture : un fichier image déjà sur le disque, à placer dans un rapport |
kindvaut"line"ou"bar".pathdoit se terminer par.png.- La colonne
ycontient des nombres, ou des quantités d'une seule sorte. Une colonne de quantités est tracée dans l'unité dans laquelle s'affiche sa plus grande valeur, et cette unité est écrite sur l'axe : 900 kbps et 1.2 Mbps sont tracés comme 0.9 et 1.2 sur un même axe en Mbps. - Une ligne sans valeur dans
y, ou avec une autre sorte de valeur, est une erreur qui nomme la ligne. - Sans
title, le graphique est intitulé « y by x ». - Aucune fenêtre ne s'ouvre : le graphique est tracé directement dans le fichier.
pictured'un fichier qui n'existe pas est une erreur.
readings: list[dict[str, Rate]] = [{"peak": 12Mbps}, {"peak": 86Mbps}, {"peak": 92Mbps}]
drawn: Picture = chart(readings, x="peak", y="peak", path="peak.png", kind="bar", title="Peak")
logo: Picture = picture("logo.png")
report
| Commande | Fait |
|---|---|
report(template: str, path: str, **values: object) |
remplit les trous du modèle et écrit path |
La terminaison de path choisit le type de rapport :
path se termine par |
Le modèle est | Notes |
|---|---|---|
.html |
un fichier HTML (.html ou .htm) |
Une image est placée dans la page elle-même, si bien que le fichier se suffit à lui-même |
.docx |
un fichier Word (.docx) |
L'ingénieur garde ses propres styles, son logo et sa page de couverture |
.pdf |
un fichier Word (.docx) |
Bogolang remplit le fichier Word, puis le convertit |
Trous
Un trou est un simple nom entre accolades, comme {link}, comme dans les modèles d'équipement
de la page configuration et modèles.
- Une vraie accolade s'écrit deux fois :
{{donne{et}}donne}. Cela compte dans le CSS d'un modèle HTML :body {{ margin: 2em; }}. - Un trou est un nom fait de lettres, de chiffres et de
_. Une expression comme{a + b}est refusée : calculez la valeur en Bogolang et passez-la par son nom. - Chaque trou a besoin d'une valeur, et chaque valeur a besoin d'un trou. Une valeur pour laquelle le modèle n'a pas de trou est une erreur, ainsi un nom mal orthographié ne passe pas inaperçu.
- Un
Secretest refusé : un rapport ne contient jamais de secret.
Ce que devient une valeur :
| Valeur | En HTML | En Word |
|---|---|---|
| Du texte, un nombre, une quantité, une adresse | le texte, rendu sûr pour le HTML | le texte, dans le style de l'endroit où commence le trou |
Une liste de lignes, ou un AuditResult |
un <table> avec une ligne d'en-tête |
un tableau Word |
Une Picture |
un <img> avec l'image dans la page |
l'image, sur 16 cm de large |
Dans un modèle Word, un tableau ou une image a besoin d'un paragraphe à lui : le trou doit y être seul. Un trou dans une cellule de tableau, un en-tête ou un pied de page ne prend que du texte. Word peut découper un trou en plusieurs morceaux de texte aux styles différents ; Bogolang le lit en entier.
Un exemple
Le modèle de l'exemple report_chart, template.html :
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Uplink report</title>
<style>
body {{ font-family: sans-serif; margin: 2em; }}
table {{ border-collapse: collapse; }}
th, td {{ border: 1px solid #999; padding: 4px 8px; }}
th {{ background: #1f3864; color: white; }}
</style>
</head>
<body>
<h1>Uplink report: {link}</h1>
<p>Capacity {capacity}. Busiest hour {busiest} at {peak}. Hours above {limit} of the capacity: {busy_hours}.</p>
{chart}
<h2>Readings</h2>
{readings}
</body>
</html>
Le programme le remplit :
```bogo skip report("template.html", str(out / "report.html"), link=c.link, capacity=c.capacity, busiest=top.hour, peak=top.peak, limit=f"{c.limit:.0%}", busy_hours=len(busy), chart=drawn, readings=c.readings)
La page qu'il écrit commence ainsi :
Uplink report: edge-rt2 Gi0/0/1
Capacity 100Mbps. Busiest hour 14:00 at 92Mbps. Hours above 80% of the capacity: 2.
<img src="data:image/png;base64,...
L'exemple ne fait pas de rapport Word, car un modèle Word est un fichier que personne ne peut
lire comme du texte. Pour en faire un, écrivez les mêmes trous dans un document Word,
enregistrez-le sous `template.docx`, et appelez `report("template.docx", "report.docx", ...)`.
### Les erreurs sont trouvées avant que rien ne soit écrit
bad.html, line 2: '{ margin: 2em; }' is not a hole. A hole is a plain name of letters, digits and _, such as {vlan}. Work out values in Bogolang and pass them by name. The hole {capacity} in template.html has no value. Give it as report(..., capacity=...). good.html has no hole {extra}. Holes: link.
La première est une accolade CSS écrite une seule fois. Écrite deux fois, c'est une vraie
accolade.
### PDF
Pour `.pdf`, Bogolang fait le fichier Word et le convertit. Il utilise Microsoft Word sous
Windows quand le paquet `docx2pdf` est installé, sinon LibreOffice. Sans aucun des deux, il
s'arrête avec une erreur qui le dit ; un rapport `.html` ou `.docx` fonctionne sans eux.
**Aucun rapport PDF n'a jamais été fait.** Seul le choix entre Word et LibreOffice a été testé.
Voir [non prouvé](not-proven.md).
## `mail`
| Commande | Fait |
|---|---|
| `mail(to: str, subject: str, body: str, attach: list[str] \| None = None)` | envoie un courriel |
### Les réglages
Le serveur de courriel est enregistré une seule fois, dans le magasin protégé du système
d'exploitation :
bogo login --mail
Il demande le serveur, la sécurité (`starttls`, `ssl` ou `none`), le port (proposé à 587, 465
pour `ssl`, 25 pour `none`), l'utilisateur, le mot de passe et l'adresse de l'expéditeur. Un
serveur qui ne demande pas d'authentification prend un utilisateur vide. Un programme ne les
contient jamais. `bogo logout --mail` les supprime. Un programme qui envoie sans réglages
enregistrés s'arrête avec : `No mail settings are stored. Store
them first with: bogo login --mail`.
### Ce que fait `mail`
- `to` contient une adresse, ou plusieurs séparées par des virgules. La forme de chacune est
vérifiée avant que rien ne soit envoyé.
- Une pièce jointe qui n'existe pas arrête le programme avant que rien ne soit envoyé.
- Un courriel quitte l'ordinateur et ne peut pas être repris. Un programme qui en envoie un
devrait demander d'abord avec `confirm(...)`, sauf s'il tourne sans surveillance exprès.
- Un envoi raté arrête le programme avec une erreur. Un mot de passe dans le texte de l'erreur
s'affiche `***`.
- Chaque courriel est une ligne du journal d'exécution (`bogo run --record`) : les adresses,
l'objet et s'il est parti. Le corps n'est pas enregistré.
```bogo
if confirm("Send the loss report to the NOC?"):
mail("noc@example.com, oncall@example.com", "Loss report",
"Two hosts checked.\nOne is down.", attach=["hosts.csv"])
--dry et --replay montrent le courriel et n'envoient rien
Avec bogo run --dry, mail affiche ce qu'il enverrait. Il ne lit aucun réglage et ne contacte
aucun serveur. Un essai à blanc n'écrit aucune ligne dans le journal d'exécution. Une exécution
avec --replay fait de même, et sa première ligne commence par REPLAY au lieu de DRY RUN.
DRY RUN: mail to noc@example.com, oncall@example.com. Nothing is sent.
Subject: Loss report
Two hosts checked.
One is down.
Attachments: hosts.csv
Un programme peut demander s'il tourne à blanc avec dry_run(), pour dire « enverrait » et non
« envoyé ».
mail n'a jamais parlé à un vrai serveur de courriel. Les tests remplacent la seule fonction
qui envoie. Un brouillon placé dans Outlook pour que l'ingénieur le lise et l'envoie lui-même
n'est pas dans cette version. Voir non prouvé.
Pour poster une ligne vers un outil de discussion ou d'alerte, voir webhook sur la
page API et plateformes.