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

Tableaux, rapports et courriel

Tableaux, fichiers Excel, graphiques, rapports et courriel.

Toutes les pages de documentation

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.
  • columns choisit et ordonne les colonnes. Un nom qu'aucune ligne n'a est une erreur qui liste les colonnes existantes.
  • True s'affiche yes, False s'affiche no, l'absence de valeur donne une cellule vide. Un Secret s'affiche toujours ***.
  • Une liste vide affiche (no rows).
Bogolang
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).

Bogolang
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
  • kind vaut "line" ou "bar". path doit se terminer par .png.
  • La colonne y contient 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.
  • picture d'un fichier qui n'existe pas est une erreur.
Bogolang
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 Secret est 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.