From 4592f5f87bb83b89abfe51479152d329c40fc2b4 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 29 Oct 2026 09:08:25 +0100 Subject: [PATCH] Documentazione: uso con ambiente .venv creato con uv Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 2 +- README.md | 30 ++++++++++++++++++++---------- docs/FUNZIONALITA.md | 2 +- docs/SPEC.md | 10 +++++----- 4 files changed, 27 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0d67fe9..f6cb818 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Stato -[genera.py](genera.py) è lo script unico (PEP 723, `uv run genera.py config.toml --seed 42`, scrive in `output/`). [grafico.py](grafico.py) disegna un CSV di output (script separato, dipende da matplotlib; `genera.py` resta con solo numpy); `genera.py` implementa [docs/SPEC.md](docs/SPEC.md), unica fonte di verità su output, modello, CLI, errori e controlli di accettazione. Leggila per intero prima di scrivere codice. Documentazione, commenti e messaggi di errore sono in italiano. +[genera.py](genera.py) è lo script unico (`python genera.py config.toml --seed 42` nell'ambiente `.venv`, creato con `uv venv`; scrive in `output/`). [grafico.py](grafico.py) disegna un CSV di output (script separato, dipende da matplotlib; `genera.py` resta con solo numpy); `genera.py` implementa [docs/SPEC.md](docs/SPEC.md), unica fonte di verità su output, modello, CLI, errori e controlli di accettazione. Leggila per intero prima di scrivere codice. Documentazione, commenti e messaggi di errore sono in italiano. ## File diff --git a/README.md b/README.md index 28adde0..da030b4 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,17 @@ Genera un CSV con la temperatura `T` di un sensore IR e la differenza `ΔT = T − T_amb`, con rumore, quantizzazione e jitter dei tempi simili a un sensore reale. `T` parte dalla temperatura ambiente, sale con i gradini di riscaldamento e ridiscende fino a `T_amb`. -## Requisiti +## Requisiti e ambiente -[uv](https://docs.astral.sh/uv/). Gli script dichiarano le loro dipendenze (Python ≥ 3.11, `numpy`, `matplotlib` per il grafico): al primo avvio uv crea da solo l'ambiente virtuale e, se serve, scarica Python. Non serve installare altro. +Python ≥ 3.11 con `numpy` e `matplotlib` (quest'ultimo solo per il grafico), in un ambiente virtuale `.venv` nella cartella del progetto. Lo si crea con [uv](https://docs.astral.sh/uv/), più veloce di `venv` + `pip`: + +```bash +uv venv .venv +uv pip install numpy matplotlib +source .venv/bin/activate # poi si usa `python ...`; senza attivare: `.venv/bin/python ...` +``` + +`.venv/` è ignorato da git. Con `venv` classico: `python -m venv .venv && .venv/bin/pip install numpy matplotlib`. ### Installare uv @@ -18,11 +26,13 @@ Apri un nuovo terminale e verifica con `uv --version`. Altre opzioni (Homebrew, ## Uso +Con l'ambiente `.venv` attivo (altrimenti sostituisci `python` con `.venv/bin/python`): + ```bash -uv run genera.py config.toml # scrive output/gen_.csv, seed casuale -uv run genera.py config.toml --seed 42 # riproducibile: output/gen_42.csv -uv run genera.py config.toml -o dati/prova.csv # percorso a scelta (cartelle create se mancano) -uv run genera.py config.toml -o - > out.csv # su stdout +python genera.py config.toml # scrive output/gen_.csv, seed casuale +python genera.py config.toml --seed 42 # riproducibile: output/gen_42.csv +python genera.py config.toml -o dati/prova.csv # percorso a scelta (cartelle create se mancano) +python genera.py config.toml -o - > out.csv # su stdout ``` | Opzione | Descrizione | @@ -36,12 +46,12 @@ Stesso seed e stessa configurazione danno sempre lo stesso file. La cartella `ou ## Grafico ```bash -uv run grafico.py # apre il grafico dell'ultimo CSV in output/ -uv run grafico.py output/gen_42.csv # un CSV preciso -uv run grafico.py -o grafico.png # salva l'immagine (png, pdf, svg) invece di aprire la finestra +python grafico.py # apre il grafico dell'ultimo CSV in output/ +python grafico.py output/gen_42.csv # un CSV preciso +python grafico.py -o grafico.png # salva l'immagine (png, pdf, svg) invece di aprire la finestra ``` -Mostra `T` e `ΔT` in funzione del tempo. `grafico.py` ha le sue dipendenze (`numpy`, `matplotlib`), gestite da uv come per `genera.py`; senza schermo usa `-o`. +Mostra `T` e `ΔT` in funzione del tempo. `grafico.py` ha le sue dipendenze (`numpy`, `matplotlib`), vedi sopra; senza schermo usa `-o`. ## Pulizia diff --git a/docs/FUNZIONALITA.md b/docs/FUNZIONALITA.md index d323318..5158b22 100644 --- a/docs/FUNZIONALITA.md +++ b/docs/FUNZIONALITA.md @@ -31,7 +31,7 @@ Formato dell'uscita: `t_ms,T_C,dT_C` (`t_ms` intero, gli altri a due decimali). ## Ambiente -- Gli script girano con [uv](https://docs.astral.sh/uv/): le dipendenze (`numpy`, più `matplotlib` per il grafico) sono dichiarate nello script (PEP 723) e uv crea da solo l'ambiente virtuale. +- Gli script girano in un ambiente `.venv` nel progetto (creato con [uv](https://docs.astral.sh/uv/): `numpy`, più `matplotlib` per il grafico). Le dipendenze sono dichiarate anche nello script (PEP 723), quindi `uv run` funziona comunque. - La cartella `output/` è ignorata da git. ## Riferimento dati reali diff --git a/docs/SPEC.md b/docs/SPEC.md index 6c6b874..822c4d5 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -36,9 +36,9 @@ Nessun valore è scritto nello script: chiave mancante ⇒ errore. Poi arrotondamento a `passo_T_c`. 5. **Ambiente e ΔT**: `amb_i = round_{amb_passo}( amb_inf + amb_A·exp(−t/τ_amb) + N(0, amb_sigma²) )`; `dT_i = round_{passo}( T_i − amb_i )`. -## 4. Uso con uv (un solo file, nessun progetto) +## 4. Uso (script unico, ambiente `.venv`) -`genera.py` con dipendenza dichiarata in testa (PEP 723): +`genera.py` con dipendenza dichiarata in testa (PEP 723, usata anche da `uv run`); ambiente `.venv` creato con `uv venv` e `uv pip install numpy`: ```python # /// script # requires-python = ">=3.11" @@ -46,9 +46,9 @@ Nessun valore è scritto nello script: chiave mancante ⇒ errore. # /// ``` ```bash -uv run genera.py config.toml --seed 42 # riproducibile -> output/gen_42.csv -uv run genera.py config.toml -o out.csv # percorso a scelta, seed casuale (stampato su stderr) -uv run genera.py config.toml -o - > out.csv # stdout +python genera.py config.toml --seed 42 # riproducibile -> output/gen_42.csv +python genera.py config.toml -o out.csv # percorso a scelta, seed casuale (stampato su stderr) +python genera.py config.toml -o - > out.csv # stdout ``` Opzioni: `config` (posizionale), `-o/--output` (default `output/gen_.csv`, cartella creata se manca; `-` = stdout), `--seed` (default: casuale, stampato su stderr). Uscita con errore (exit 1) e messaggio in italiano se manca una chiave, se `t_impulsi_s` e `dT_impulsi_c` hanno lunghezze diverse