Pacchetto Windows: LEGGIMI dei report PDF (DLL, variabili, flag Nuitka, licenze) (TieMeasureFlow#78)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,149 @@
|
|||||||
|
# Report PDF nel pacchetto Windows
|
||||||
|
|
||||||
|
Questa cartella contiene quello che serve perché i report PDF di TieMeasureFlow
|
||||||
|
(`src/backend/services/report_service.py`: Jinja2, Plotly con Kaleido 1.2.0, WeasyPrint 68.1)
|
||||||
|
funzionino su Windows, dentro il pacchetto, **senza Internet**. Riferimento: TieMeasureFlow#78
|
||||||
|
(parte del pacchetto Windows, madre #76).
|
||||||
|
|
||||||
|
## Come funziona
|
||||||
|
|
||||||
|
Un report SPC passa da due componenti nativi che su Windows non arrivano con `pip`:
|
||||||
|
|
||||||
|
1. **WeasyPrint** disegna il PDF e carica a runtime le DLL di Pango/GTK
|
||||||
|
(`libgobject-2.0-0`, `libpango-1.0-0`, `libharfbuzz-0`, `libharfbuzz-subset-0`,
|
||||||
|
`libfontconfig-1`, `libpangoft2-1.0-0` e le loro dipendenze).
|
||||||
|
2. **Kaleido 1.x** trasforma i grafici Plotly in SVG pilotando un browser Chromium già installato
|
||||||
|
(non porta più Chromium con sé). Su ogni Windows 10/11 c'è Edge.
|
||||||
|
|
||||||
|
### Le DLL: `prendi-gtk.ps1`
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
powershell -NoProfile -ExecutionPolicy Bypass -File packaging\windows\pdf\prendi-gtk.ps1 -Destinazione <cartella>
|
||||||
|
```
|
||||||
|
|
||||||
|
- Scarica da `repo.msys2.org` (ucrt64) 21 pacchetti **pinnati con sha256** (nome file e hash stanno nello
|
||||||
|
script), verifica l'hash, estrae solo le 27 DLL necessarie, `etc\fonts` di fontconfig e le licenze.
|
||||||
|
- Idempotente: se la cartella è già pronta (file `.gtk-pin` uguale ai pin dello script) esce subito.
|
||||||
|
- Se un hash non coincide fallisce e non lascia mezza cartella.
|
||||||
|
- I pacchetti scaricati stanno in `%LOCALAPPDATA%\Tielogic\tmf-gtk-cache` (`-Cache` per cambiarla).
|
||||||
|
- Serve Internet **solo alla build**. Estrae `.zst` con `tar.exe` di Windows (verificato: bsdtar 3.8.9 con
|
||||||
|
zstd); se `tar.exe` non sa di zstd ripiega su `uv run --with zstandard`.
|
||||||
|
- Gira da utente non admin con PowerShell 5.1.
|
||||||
|
- ⚠️ `repo.msys2.org` tiene solo le versioni recenti: se un file pinnato sparisce (404) vanno aggiornati nome
|
||||||
|
e sha256 dal db `https://repo.msys2.org/mingw/ucrt64/ucrt64.db` e rifatto il test. Conservare la cache
|
||||||
|
(Wasabi o NAS) evita la corsa contro il repository.
|
||||||
|
|
||||||
|
Il piano C copia `<cartella>` in `P\gtk\` (P = cartella programma).
|
||||||
|
|
||||||
|
### Variabili d'ambiente (le imposta `avvio.py`, piano C)
|
||||||
|
|
||||||
|
| Variabile | Valore | Perché |
|
||||||
|
|---|---|---|
|
||||||
|
| `WEASYPRINT_DLL_DIRECTORIES` | `<P>\gtk` | WeasyPrint chiama `os.add_dll_directory` su ogni cartella (separatore `;`) **prima** di caricare le DLL. Va impostata prima di importare `weasyprint` (lo fa `report_service` all'import). |
|
||||||
|
| `BROWSER_PATH` | `msedge.exe` o `chrome.exe` | Choreographer (sotto Kaleido) la legge da sé e ha la precedenza su ogni ricerca (verificato: un percorso inesistente dà `FileNotFoundError`). Senza la variabile Kaleido cerca Edge/Chrome da solo (registro e percorsi tipici). Nessun codice in `report_service.py` per questo. |
|
||||||
|
|
||||||
|
Fontconfig non richiede variabili: trova `etc\fonts` accanto alle DLL (verificato). Se manca `etc\fonts`
|
||||||
|
WeasyPrint stampa "Fontconfig error: Cannot load default config file". I font dei report vengono da
|
||||||
|
`C:\Windows\Fonts`.
|
||||||
|
|
||||||
|
### MathJax: la modifica a `report_service.py`
|
||||||
|
|
||||||
|
Kaleido 1.x inserisce nella pagina di render uno `<script>` MathJax da `cdnjs.cloudflare.com` anche quando i
|
||||||
|
grafici non hanno formule. Misurato su daitarn con Edge: con rete che scarta i pacchetti ogni grafico aspetta
|
||||||
|
~19 s (due grafici per report SPC); con rete che rifiuta subito ~2 s. `report_service.py` imposta
|
||||||
|
`pio.defaults.mathjax` su un file `.js` vuoto in `%TEMP%` (`tmf-mathjax-vuoto.js`): nessuna richiesta di rete,
|
||||||
|
report SPC in ~7 s anche a rete bloccata. Se un giorno i grafici useranno LaTeX, qui serve un MathJax locale.
|
||||||
|
`plotly.min.js` invece è già locale (dentro il pacchetto `plotly`).
|
||||||
|
|
||||||
|
## Flag Nuitka e dati da includere (per `build.ps1`, piano C)
|
||||||
|
|
||||||
|
⚠️ Stato: ricavati leggendo i sorgenti installati (versioni del `uv.lock`); **non provati con una build
|
||||||
|
Nuitka**: la verifica è la prima build di C. I dati e i metadati sono quelli che il codice legge davvero da disco.
|
||||||
|
|
||||||
|
Dati dei pacchetti (file non `.py` letti a runtime):
|
||||||
|
|
||||||
|
```text
|
||||||
|
--include-package-data=weasyprint # css/html5_ua.css, html5_ph.css, html5_ua_form.css, pdf/sRGB2014.icc
|
||||||
|
--include-package-data=pyphen # dictionaries/*.dic (84 file, sillabazione)
|
||||||
|
--include-package-data=kaleido # vendor/kaleido_scopes.js (pagina di render)
|
||||||
|
--include-package-data=plotly # package_data/plotly.min.js (Kaleido lo cerca come file accanto a plotly/__init__), templates/*.json, validators/_validators.json
|
||||||
|
--include-package-data=tzdata # zoneinfo: Windows non ha il database IANA (vedi sotto)
|
||||||
|
--include-data-dir=src/backend/templates=src/backend/templates # Jinja2: report_service legge i .html dal disco
|
||||||
|
```
|
||||||
|
|
||||||
|
`choreographer/resources/last_known_good_chrome.json` serve solo al comando che scarica Chrome: non serve.
|
||||||
|
|
||||||
|
Metadati delle distribuzioni (`importlib.metadata.version` al momento dell'import): senza, `import plotly` e
|
||||||
|
Kaleido falliscono con `PackageNotFoundError`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
--include-distribution-metadata=plotly
|
||||||
|
--include-distribution-metadata=kaleido
|
||||||
|
```
|
||||||
|
|
||||||
|
Import dinamici che l'analisi statica di Nuitka può perdere:
|
||||||
|
|
||||||
|
```text
|
||||||
|
--include-package=fontTools # ttLib/ttFont.py importa le tabelle con __import__("fontTools.ttLib.tables." + tag)
|
||||||
|
--include-package=plotly # _plotly_utils/importers.py: importlib.import_module lazy dei moduli graph_objs
|
||||||
|
--include-package=_plotly_utils
|
||||||
|
--include-module=_cffi_backend # WeasyPrint usa cffi in modalita' ABI (dlopen), serve il modulo C di cffi
|
||||||
|
--include-package=weasyprint
|
||||||
|
--include-package=kaleido
|
||||||
|
--include-package=choreographer
|
||||||
|
```
|
||||||
|
|
||||||
|
Altre note per C:
|
||||||
|
|
||||||
|
- WeasyPrint salta `os.add_dll_directory` se `sys.frozen` esiste (`weasyprint/text/ffi.py`). Nuitka di norma
|
||||||
|
non lo imposta (PyInstaller sì): se in `TieMeasureFlow.exe` le DLL non si trovassero, chiamare
|
||||||
|
`os.add_dll_directory(<P>\gtk)` da `avvio.py` prima dell'import.
|
||||||
|
- Le DLL **non** vanno compilate né incluse da Nuitka: restano file in `P\gtk\`.
|
||||||
|
- Il controllo "nessun `.py`" di `build.ps1` non deve scandire `gtk\` (non ci sono `.py`, ma è meglio
|
||||||
|
saperlo) né `licenze\`.
|
||||||
|
- **`tzdata` manca da `pyproject.toml`**: su Windows `ZoneInfo("Europe/Rome")` (usato da
|
||||||
|
`src/backend/utils/tempo.py`, quindi da ogni report) dà `ZoneInfoNotFoundError`. Va aggiunto
|
||||||
|
`tzdata; sys_platform == 'win32'` agli extra server e client (o al gruppo `windows`) e il frontend
|
||||||
|
(`src/frontend/flask_app/app.py` usa `ZoneInfo`) ne ha bisogno allo stesso modo.
|
||||||
|
- `pdfplumber` è già nell'extra `server` (il test lo usa per leggere i PDF).
|
||||||
|
|
||||||
|
## Licenze delle DLL
|
||||||
|
|
||||||
|
Le DLL sono binari MSYS2/MinGW (ucrt64) non modificati, collegati dinamicamente. `prendi-gtk.ps1` mette in
|
||||||
|
`<cartella>\licenze\` i testi di licenza di ogni pacchetto più un `<pacchetto>.txt` con nome del file e licenza.
|
||||||
|
**L'installer deve includere `gtk\licenze\`.**
|
||||||
|
|
||||||
|
| Libreria | Licenza |
|
||||||
|
|---|---|
|
||||||
|
| Pango, GLib/GObject/GIO, fribidi, libthai, libdatrie, graphite2, libintl (gettext-runtime), libiconv | LGPL 2.1 o successive |
|
||||||
|
| FreeType | FTL oppure GPL 2+ (si sceglie FTL) |
|
||||||
|
| HarfBuzz, expat, libffi, brotli, fontconfig | MIT / permissiva |
|
||||||
|
| libpng, zlib-ng, bzip2, pcre2 | permissive (libpng, Zlib, bzip2, BSD-3) |
|
||||||
|
| libgcc, libstdc++ | GPL 3 con GCC Runtime Library Exception (ridistribuzione libera) |
|
||||||
|
| libwinpthread | MIT e BSD-3 |
|
||||||
|
|
||||||
|
Per le librerie LGPL, chi riceve il pacchetto può sostituire le DLL (sono file separati in `gtk\`); i sorgenti
|
||||||
|
sono pubblici su MSYS2 (`https://packages.msys2.org/`), e l'elenco esatto delle versioni è nello script.
|
||||||
|
|
||||||
|
## Test
|
||||||
|
|
||||||
|
`src/backend/tests/test_report_windows.py` (saltato fuori da Windows, senza DLL, senza Edge/Chrome o senza
|
||||||
|
`tzdata`): in un sottoprocesso con WeasyPrint **vero** (il `conftest.py` altrimenti lo sostituisce con un
|
||||||
|
mock) genera su SQLite in memoria il report SPC (carta di controllo e istogramma) e quello a tabella, e
|
||||||
|
controlla con `pdfplumber` byte `%PDF-`, almeno una pagina, titoli dei grafici e segni vettoriali.
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# DLL (una volta) e test
|
||||||
|
powershell -NoProfile -ExecutionPolicy Bypass -File packaging\windows\pdf\prendi-gtk.ps1 -Destinazione packaging\windows\pdf\gtk
|
||||||
|
uv run --python 3.13 --extra server --extra dev pytest src/backend/tests/test_report_windows.py -q
|
||||||
|
```
|
||||||
|
|
||||||
|
`packaging/windows/pdf/gtk/` e `cache/` sono in `.gitignore`: le DLL non si committano.
|
||||||
|
|
||||||
|
### Prova a rete bloccata
|
||||||
|
|
||||||
|
`HTTP_PROXY`/`HTTPS_PROXY` non bastano: Edge e Chrome usano il **proxy di sistema** di Windows. Per provare davvero
|
||||||
|
il PC senza Internet: impostare temporaneamente il proxy di sistema (Impostazioni, Rete, Proxy) su un indirizzo
|
||||||
|
morto (`127.0.0.1:9` rifiuta subito; `10.255.255.1:8080` scarta i pacchetti, il caso peggiore), generare i
|
||||||
|
report e **ripristinare** il proxy. Esito del 2026-10-17 con proxy che scarta i pacchetti: report SPC e report a
|
||||||
|
tabella completi in ~7 s.
|
||||||
Reference in New Issue
Block a user