Entwicklung

Aufbau des Codes, Tests, Build

Veröffentlichungsdatum

23. September 2026

In einem Satz

Der Arbeitsbereich enthält alles, was zu den Notebooks gehört, und nichts sonst; eine Änderung gilt erst als fertig, wenn Tests, Build und eine Probe am laufenden Dienst sie belegen.

1 Aufbau

flowchart LR
  qmd["notebook.fam"] --> parse["parse und binder"]
  parse --> runner["runner"]
  runner --> harness["ExecutionHarness"]
  runner --> ops["ops: lokale Schritte"]
  runner --> remote["remote: Peer"]
  runner --> log["log"]
  log --> server["server"]
  server --> web["web: Viewer"]
  log --> lua["famulus.lua: Quarto"]

Teil	Datei	Aufgabe
Projekt	`project.py`	`famulus.yml`, Notebooks, Register, Suche nach Projekten
Parser	`parse.py`, `fnx.py`	liest die `.fam`-Datei und die Blöcke
Binder	`binder.py`	bildet die Präambel auf Partitur und Eingaben ab
Ausführung	`runner.py`, `engine.py`	spielt die Blöcke in Abhängigkeitsordnung, schreibt die Versionen
Verweise, Versionen	`refs.py`, `log.py`	`fam:`-Verweise auflösen; Versionsordner, Kopf der Artefakte
Aktualität	`lock.py`	Status, `refresh`, Reihenfolge der Notebooks und Projekte, `famulus.lock`
Übertragung, Bau	`migrate.py`, `build.py`	alte Pakete zu Projekten; Schattenkopien für Quarto
Lokale Schritte	`ops.py`	`duckdb-read`, Artefaktbau, die gedienten Lesungen für Peers
Verknüpfung	`peers.py`, `remote.py`	Peers auflösen, Blöcke fern ausführen, Logs übernehmen
Zugang	`auth.py`	Token, Tailnet, Besitzer am eigenen Rechner
Anzeige	`display.py`, `site/_extensions/famulus/`	Ergebnisform und Urteil für Viewer und Quarto
Journal, Goldens	`journal.py`, `goldens.py`	neue Fragen anhängen, Golden-Notebook erzeugen
Dienst	`server.py`, `cli.py`, `config.py`	API, Viewer, Kommandozeile, Pfade
Viewer	`web/src/`	React; `NotebookApp`, `BlockCard`, `ResultView`, `ComposerView`, `LearnView`

2 Tests

uv run --extra dev python -m pytest -q

tests/test_peers.py startet einen zweiten Dienst auf einem freien Port, trägt ihn als Peer fern mit einer toten ersten Adresse ein und prüft daran die Probe-Reihenfolge, die ferne Lesung, die ferne Ausführung, den fernen Querverweis, die Abweisung ohne Token und die Regeln für Anmerkungen. Die Tests brauchen keine Sammlung; sie legen eine kleine DuckDB-Datei im Testordner an.

Nach einer Änderung am Viewer prüft scripts/notebook_smoke.py die laufende Seite in einem Chrome ohne Fenster: Notebooks laden, Lektor-Marken sitzen, die Seite rollt, Neue Frage und Lernen zeigen Inhalt.

3 Viewer bauen

cd web && npm run build

Der Build schreibt nach src/famulus_notebook/static/. Ein Vite-Entwicklungsserver wird nicht gestartet; der Dienst auf 5118 liefert den gebauten Viewer aus, ein Neuladen der Seite genügt.

4 Regeln

Eine Zahl in einer Antwort, einem Test oder dieser Dokumentation nennt ihre Quelle und ihren Zählmodus.
Ein fehlender Pfad, eine unerreichbare Sammlung oder ein unbekannter Subtask ist ein Fehler mit Grund, kein leeres Ergebnis.
Datenbankverbindungen sind kurzlebig und lesend.
Diagnosedaten stehen unter Diagnose, nicht im Ergebnis.
Ein Token steht in keinem Log, keinem Notebook, keiner Adresse, die der Server protokolliert.
Nach einer Änderung am Python-Code wird der Dienst neu gestartet und mit /api/health geprüft.