torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity

Beschaffung aus raw_cmd.py herauslösen: ein Paket pro Unterkommando statt 2.734 Zeilen in einer Datei #206

New Issue
Closed
opened 2026-10-09 21:38:45 +00:00 by torben · 3 comments
torben commented 2026-10-09 21:38:45 +00:00
Owner
Copy link
Copy source

Angelegt am 2026-10-09 in der Design-Sitzung zu #87/#200 (Stand 9.0.0, 7cfafd7). Voraussetzung für die Site-Handler (#200) und den Abruf mit Session (#169), die sonst ebenfalls in raw_cmd.py landen würden.

Abgeschlossen am 2026-10-10: Umbau publiziert als Commit 059a0a1 in Version 9.0.1-beta.2. Lokal grün (pytest 2.714 passed / 3 skipped wie vor dem Umbau, docs verify, instructions verify); CI grün auf dem publizierten Commit (Läufe 642 und 643). Im Abschluss geprüft: kein Dokument veraltet (siehe § Verifikation).

Befund

tools/chemenu/commands/raw_cmd.py hatte 2.734 Zeilen und trug sechs Unterkommandos. Die Datei war durch Abschnittsköpfe gegliedert:

Zeilen (ca.) Abschnitt
115-460 gemeinsame Hilfen: incoming/, Datums-Shard, Verweigerungen, belegte Stämme, Ordner- und Bundle-Planung
460-1387 raw accept samt --replaces/--replaces-bundle
1388-1572 raw pending
1573-1839 raw fetch (Kern in tools/chemenu/web_capture.py)
1840-2316 raw derive (Kern in tools/chemenu/filters/)
2317-2734 raw capture / raw status

Importiert wurde raw_cmd von tools/chemenu/cli.py, tools/chemenu/upload.py (nur ein Docstring-Verweis) und sieben Testdateien (test_raw_cmd.py, test_raw_fetch.py, test_raw_derive.py, test_raw_derive_testfiles.py, test_raw_capture.py, test_export_guidelines.py, test_docs_verify.py).

Entwurf (entschieden und umgesetzt)

  1. raw_cmd.py ist das Paket tools/chemenu/commands/raw/: _common.py, accept.py, pending.py, fetch.py, derive.py, capture.py (mit status). Die Kommando-Records (cli_contract) ziehen mit ihrem Kommando um. Die Typer-Gruppe app entsteht in raw/__init__.py, das die Kommandos in der alten Reihenfolge importiert und registriert (accept, pending, fetch, derive, capture, status), damit -h und die Record-Reihenfolge gleich bleiben.
  2. Die Kerne bleiben, wo sie sind (web_capture.py, filters/, repo_capture.py). Dieses Paket verschiebt nur die CLI-Adapter.
  3. Importe in cli.py und den Tests sind umgestellt. Es gibt keine Re-Export-Hülle raw_cmd.py: Zwei Wege zum selben Namen wären eine zweite Stelle, die veralten kann.
  4. Schnitt (im Bau entschieden): Was von mindestens zwei Unterkommandos erreicht wird, steht in _common.py (31 Definitionen, auch wenn der Abschnitt der Tabelle es woanders führte, etwa _derive_hint und _write_exclusive); was nur eines erreicht, steht in dessen Modul. raw status teilt sich seine Hilfen nur mit raw capture und liegt deshalb in capture.py. Maßgeblich war die Erreichbarkeit vom Kommando aus, nicht die Position in der Datei. Das Ergebnis ist maschinell geprüft: alle 77 Top-Level-Definitionen sind im AST gleich den alten, bis auf den entfallenen @app.command-Dekorator.

Zeilen: _common.py 499, accept.py 949, pending.py 210, fetch.py 259, derive.py 501, capture.py 430.

Invariante

Reine Umstrukturierung. Jede Ausgabe jedes raw-Kommandos bleibt byte-identisch, auch Hilfetexte und Exit-Codes, und der generierte Teil von tools/CONTRACT.md und docs/reference/commands/ ändert sich nicht.

Betroffene Dateien

  • tools/chemenu/commands/raw_cmd.py → tools/chemenu/commands/raw/*.py
  • tools/chemenu/cli.py, tools/chemenu/upload.py (nur Docstring)
  • die sieben Testdateien oben (Importe; zwei Abweichungen siehe Kriterium 2)
  • tools/README.md (Zeile zu commands/), VERSION, CHANGES.md

Akzeptanzkriterien

  • tools/chemenu/commands/raw_cmd.py existiert nicht mehr; kein Modul unter tools/chemenu/commands/raw/ hat mehr als 1.000 Zeilen (größtes: accept.py, 949).
  • Die bestehenden Tests laufen mit geänderten Importen und sonst unverändert grün (2.714 passed, 3 skipped, wie vorher). Abweichung vom Wortlaut „nur Import-Zeilen": zusätzlich ändern sich eine Pfadzeile in test_docs_verify.py (raw_cmd.py → raw/accept.py in der Export-Plan-Prüfung) und ein Docstring-Verweis in test_raw_cmd.py (raw_cmd._shard_dir()), weil beide die gelöschte Datei nennen. Keine Assertion über Verhalten ändert sich.
  • tools/wikitool raw <cmd> -h ist für alle sechs Unterkommandos und für raw -h byte-identisch mit dem Stand vor dem Umbau (per diff gegen vorher aufgenommene Ausgaben).
  • tools/wikitool docs verify ist grün; docs contract und docs reference melden den generierten Teil als aktuell, ohne Änderung an tools/CONTRACT.md oder docs/reference/commands/.
  • pytest, instructions verify grün lokal; CI grün auf dem publizierten Commit 059a0a1 (Läufe 642 und 643, beide success).

Versionsteil

--patch. Keine Änderung an Kommandos, Flags, Dateiformaten oder dem Importnamen chemenu. chemenu.commands.raw_cmd ist keine zugesicherte Schnittstelle, ausgeliefert wird nur der Launcher. Drop-in in beide Richtungen. Gebumpt als 9.0.1-beta.2, --impact low.

Verifikation

Publiziert als 059a0a1 (Version 9.0.1-beta.2). CI-Lauf 642 (https://gitea.nehmer.net/torben/chemenu/actions/runs/642) und 643 (https://gitea.nehmer.net/torben/chemenu/actions/runs/643) auf diesem Commit: beide success, head_sha 059a0a1 über gitea-mcp nachgelesen.

Prüfung auf veraltete Dokumente im Abschluss: git grep raw_cmd findet außer in CHANGES.md keinen Verweis mehr, auch nicht in docs/, instructions/, den Contracts oder README.md. tools/README.md beschreibt das Paket schon (im Commit selbst nachgezogen). Keine Installationsanleitung und keine Überschrift berührt, daher kein Nachziehen, kein Bump und kein weiterer Lauf.

Kette

Kette „Beschaffung und Konfiguration“

> Angelegt am 2026-10-09 in der Design-Sitzung zu #87/#200 (Stand `9.0.0`, `7cfafd7`). Voraussetzung für die Site-Handler (#200) und den Abruf mit Session (#169), die sonst ebenfalls in `raw_cmd.py` landen würden. > > **Abgeschlossen am 2026-10-10:** Umbau publiziert als Commit `059a0a1` in Version `9.0.1-beta.2`. Lokal grün (`pytest` 2.714 passed / 3 skipped wie vor dem Umbau, `docs verify`, `instructions verify`); CI grün auf dem publizierten Commit (Läufe 642 und 643). Im Abschluss geprüft: kein Dokument veraltet (siehe § Verifikation). ## Befund `tools/chemenu/commands/raw_cmd.py` hatte 2.734 Zeilen und trug sechs Unterkommandos. Die Datei war durch Abschnittsköpfe gegliedert: | Zeilen (ca.) | Abschnitt | |---|---| | 115-460 | gemeinsame Hilfen: `incoming/`, Datums-Shard, Verweigerungen, belegte Stämme, Ordner- und Bundle-Planung | | 460-1387 | `raw accept` samt `--replaces`/`--replaces-bundle` | | 1388-1572 | `raw pending` | | 1573-1839 | `raw fetch` (Kern in `tools/chemenu/web_capture.py`) | | 1840-2316 | `raw derive` (Kern in `tools/chemenu/filters/`) | | 2317-2734 | `raw capture` / `raw status` | Importiert wurde `raw_cmd` von `tools/chemenu/cli.py`, `tools/chemenu/upload.py` (nur ein Docstring-Verweis) und sieben Testdateien (`test_raw_cmd.py`, `test_raw_fetch.py`, `test_raw_derive.py`, `test_raw_derive_testfiles.py`, `test_raw_capture.py`, `test_export_guidelines.py`, `test_docs_verify.py`). ## Entwurf (entschieden und umgesetzt) 1. `raw_cmd.py` ist das Paket `tools/chemenu/commands/raw/`: `_common.py`, `accept.py`, `pending.py`, `fetch.py`, `derive.py`, `capture.py` (mit `status`). Die Kommando-Records (`cli_contract`) ziehen mit ihrem Kommando um. Die Typer-Gruppe `app` entsteht in `raw/__init__.py`, das die Kommandos in der alten Reihenfolge importiert und registriert (`accept, pending, fetch, derive, capture, status`), damit `-h` und die Record-Reihenfolge gleich bleiben. 2. Die Kerne bleiben, wo sie sind (`web_capture.py`, `filters/`, `repo_capture.py`). Dieses Paket verschiebt nur die CLI-Adapter. 3. Importe in `cli.py` und den Tests sind umgestellt. Es gibt **keine** Re-Export-Hülle `raw_cmd.py`: Zwei Wege zum selben Namen wären eine zweite Stelle, die veralten kann. 4. **Schnitt (im Bau entschieden):** Was von mindestens zwei Unterkommandos erreicht wird, steht in `_common.py` (31 Definitionen, auch wenn der Abschnitt der Tabelle es woanders führte, etwa `_derive_hint` und `_write_exclusive`); was nur eines erreicht, steht in dessen Modul. `raw status` teilt sich seine Hilfen nur mit `raw capture` und liegt deshalb in `capture.py`. Maßgeblich war die Erreichbarkeit vom Kommando aus, nicht die Position in der Datei. Das Ergebnis ist maschinell geprüft: alle 77 Top-Level-Definitionen sind im AST gleich den alten, bis auf den entfallenen `@app.command`-Dekorator. Zeilen: `_common.py` 499, `accept.py` 949, `pending.py` 210, `fetch.py` 259, `derive.py` 501, `capture.py` 430. ## Invariante Reine Umstrukturierung. **Jede Ausgabe jedes `raw`-Kommandos bleibt byte-identisch**, auch Hilfetexte und Exit-Codes, und der generierte Teil von `tools/CONTRACT.md` und `docs/reference/commands/` ändert sich nicht. ## Betroffene Dateien - `tools/chemenu/commands/raw_cmd.py` → `tools/chemenu/commands/raw/*.py` - `tools/chemenu/cli.py`, `tools/chemenu/upload.py` (nur Docstring) - die sieben Testdateien oben (Importe; zwei Abweichungen siehe Kriterium 2) - `tools/README.md` (Zeile zu `commands/`), `VERSION`, `CHANGES.md` ## Akzeptanzkriterien - [x] `tools/chemenu/commands/raw_cmd.py` existiert nicht mehr; kein Modul unter `tools/chemenu/commands/raw/` hat mehr als 1.000 Zeilen (größtes: `accept.py`, 949). - [x] Die bestehenden Tests laufen mit geänderten Importen und sonst unverändert grün (2.714 passed, 3 skipped, wie vorher). **Abweichung vom Wortlaut „nur Import-Zeilen":** zusätzlich ändern sich eine Pfadzeile in `test_docs_verify.py` (`raw_cmd.py` → `raw/accept.py` in der Export-Plan-Prüfung) und ein Docstring-Verweis in `test_raw_cmd.py` (`raw_cmd._shard_dir()`), weil beide die gelöschte Datei nennen. Keine Assertion über Verhalten ändert sich. - [x] `tools/wikitool raw <cmd> -h` ist für alle sechs Unterkommandos und für `raw -h` byte-identisch mit dem Stand vor dem Umbau (per `diff` gegen vorher aufgenommene Ausgaben). - [x] `tools/wikitool docs verify` ist grün; `docs contract` und `docs reference` melden den generierten Teil als aktuell, ohne Änderung an `tools/CONTRACT.md` oder `docs/reference/commands/`. - [x] `pytest`, `instructions verify` grün lokal; CI grün auf dem publizierten Commit `059a0a1` (Läufe 642 und 643, beide `success`). ## Versionsteil **`--patch`.** Keine Änderung an Kommandos, Flags, Dateiformaten oder dem Importnamen `chemenu`. `chemenu.commands.raw_cmd` ist keine zugesicherte Schnittstelle, ausgeliefert wird nur der Launcher. Drop-in in beide Richtungen. Gebumpt als `9.0.1-beta.2`, `--impact low`. ## Verifikation Publiziert als `059a0a1` (Version `9.0.1-beta.2`). CI-Lauf 642 (https://gitea.nehmer.net/torben/chemenu/actions/runs/642) und 643 (https://gitea.nehmer.net/torben/chemenu/actions/runs/643) auf diesem Commit: beide `success`, `head_sha` `059a0a1` über `gitea-mcp` nachgelesen. Prüfung auf veraltete Dokumente im Abschluss: `git grep raw_cmd` findet außer in `CHANGES.md` keinen Verweis mehr, auch nicht in `docs/`, `instructions/`, den Contracts oder `README.md`. `tools/README.md` beschreibt das Paket schon (im Commit selbst nachgezogen). Keine Installationsanleitung und keine Überschrift berührt, daher kein Nachziehen, kein Bump und kein weiterer Lauf. ## Kette Kette „Beschaffung und Konfiguration“ - Vorgänger: #205 - Nachfolger: #207
torben added the prio/plannedsize/Marea/kbkind/build labels 2026-10-09 21:38:45 +00:00
torben commented 2026-10-10 09:56:31 +00:00
Author
Owner
Copy link
Copy source

Changelog: Build-Sitzung abgeschlossen. Im Bau entschieden: der Schnitt richtet sich nach der Erreichbarkeit vom Kommando aus (31 Definitionen in _common.py, raw status in capture.py). Zwei Abweichungen vom Kriterium „nur Import-Zeilen" in den Tests (Pfadzeile in test_docs_verify.py, Docstring in test_raw_cmd.py), kein Verhalten betroffen. Publiziert als 059a0a1, Version 9.0.1-beta.2, CI grün (Läufe 642 und 643).

**Changelog:** Build-Sitzung abgeschlossen. Im Bau entschieden: der Schnitt richtet sich nach der Erreichbarkeit vom Kommando aus (31 Definitionen in `_common.py`, `raw status` in `capture.py`). Zwei Abweichungen vom Kriterium „nur Import-Zeilen" in den Tests (Pfadzeile in `test_docs_verify.py`, Docstring in `test_raw_cmd.py`), kein Verhalten betroffen. Publiziert als `059a0a1`, Version `9.0.1-beta.2`, CI grün (Läufe 642 und 643).
torben commented 2026-10-10 09:56:42 +00:00
Author
Owner
Copy link
Copy source

Changelog: Publiziert als 059a0a1 in Version 9.0.1-beta.2; alle Akzeptanzkriterien abgehakt. CI-Läufe 642 und 643 auf dem Commit sind grün und im Body als Verifikation genannt; der Hinweis „Noch nicht publiziert" im Kopf ist entfernt.

**Changelog:** Publiziert als `059a0a1` in Version `9.0.1-beta.2`; alle Akzeptanzkriterien abgehakt. CI-Läufe 642 und 643 auf dem Commit sind grün und im Body als Verifikation genannt; der Hinweis „Noch nicht publiziert" im Kopf ist entfernt.
torben commented 2026-10-10 11:00:46 +00:00
Author
Owner
Copy link
Copy source

Changelog: Abschluss: Body in Endstand gebracht (Kopf „Abgeschlossen“, Prüfung auf veraltete Dokumente unter § Verifikation). Kein Dokument veraltet, kein Nachziehen nötig. CI-Läufe 642 und 643 auf 059a0a1 nachgelesen, beide success. Geschlossen; nächstes Glied der Kette ist #207.

**Changelog:** Abschluss: Body in Endstand gebracht (Kopf „Abgeschlossen“, Prüfung auf veraltete Dokumente unter § Verifikation). Kein Dokument veraltet, kein Nachziehen nötig. CI-Läufe 642 und 643 auf `059a0a1` nachgelesen, beide `success`. Geschlossen; nächstes Glied der Kette ist #207.
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
area/corpus
Betrifft Demo-/Testbett-Frage, Inhalt und Umfang von kb/
 area/distribution
Betrifft Auslieferung, Upgrade, Versionierung einer Instanz
 area/kb
Betrifft kb/-Schema, Contract, Confidence, Lint, Wissensbasis
 area/process
Betrifft den Entwicklungsprozess selbst, nicht den Stack als Artefakt
 area/workflow
Betrifft Git, Merge, Branching, Publish, PRs
 kind/build
Spezifiziert, wartet nur noch auf Umsetzungszeit
 kind/decision
Wartet auf eine Betreiberentscheidung
 kind/defect
Befund: Doku und Realitaet, oder zwei Dokus, widersprechen sich
 prio/blocking
Blockiert oder beschaedigt laufende Arbeit - als naechstes
 prio/planned
Traegt bald Zinsen - eingeplant
 prio/waiting
Sinnvoll, wartet auf einen Ausloeser
 size/L
Mehrere Sitzungen oder offene Designfragen vor dem ersten Commit
 size/M
Mehrere Dateien, Contract- oder Instruction-Aenderung, eigener Testaufwand
 size/S
Eine Sitzung, ein Publish, klar umrissener Schnitt
 status/blocked
Wartet auf ein anderes, noch offenes Issue - nicht eigenstaendig bearbeitbar
 status/incoming
Vom Menschen angelegte Anforderung, unvollständig, muss durch den Stack komplettiert werden.
 status/unconfirmed
Gemeldeter Verdacht, noch nicht gegen tatsaechliches Verhalten geprueft - size/prio vorlaeufig
No labels area/kb kind/build prio/planned size/M
Milestone
No items
No Milestone
Assignees
Clear assignees
torben
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torben/chemenu#206