Repository navigation
fix(profile): profila la stessa relazione del clean — pipeline, file e stato - #551
Merged
Merged
Conversation
…e stato
Il profilo RAW aveva un parser proprio: costruiva una `read_csv` a mano mentre
il clean usa `read_raw_to_relation`. Le due copie sono divergite e il profilo
falliva in silenzio (zero colonne, warning solo dentro l'artefatto) su ogni
dataset con `columns` compatto `column00: "nome:VARCHAR"`, con
`normalize_rows_to_columns` per nome o con `align_by_header`. Misurato: dei 219
run con profilo vuoto, 188 erano ancora riproducibili con il codice precedente;
dopo il fix 190 tornano pieni e 0 falliscono. I 434 dataset `latest` restano
sul percorso invariato.
Lettura. `profile_with_read_cfg` costruisce `RAW_INPUT_VIEW` con
`core.duckdb_read.read_raw_to_relation`, la stessa funzione del clean: formato
compatto, normalize, align_by_header, Excel e `.ods` non hanno piu' un parser
separato (`profile_excel` diventa un wrapper di 3 righe; `.ods` era trattato
come "zip non supportato" mentre il clean lo legge). Passa anche `read_mode`
del dataset (`strict`/`fallback`/`robust`), cosi' il profilo non puo'
dichiarare leggibile un file che il clean rifiuterebbe, e restituisce
`row_count` senza la seconda connessione che rileggeva il file da capo.
Selezione. Il profilo prendeva sempre il `primary_output_file`; con
`mode: all|explicit|largest` il clean legge N file (o il sottoinsieme di
`include`), quindi hint, `row_count`, `col_count` e `null_counts` descrivevano
un'altra relazione. Ora la selezione e' quella del clean, riusando
`select_raw_input`. Misurato: 54 dataset su 80 con selezione multi-file
cambiano, con scarti fino a 10x sulle righe (`ga_sentenze` 65.768 -> 501.531 su
31 file, `openga_ricorsi_appalto` 8.446 -> 70.232 su 32) e colonne in piu'
dalla union per nome (`senato_ddl` 16 -> 27). Per questo
`clean/input_selection.py` -> `core/input_selection.py`: la selezione dei file
RAW e' un contratto condiviso, non un dettaglio del clean.
Stato. Un profilo vuoto non e' piu' un successo silenzioso: `metadata.json`
espone `profile: {status, file, row_count, columns, warnings}`,
`run_raw_validation` emette `raw_profile_empty`, e readiness / `inspect schema`
/ `review-readiness` riportano `profile_status` e i warning del profilo. A
valle il clean leggeva con i soli hint dello sniff leggero e si spegnevano
scaffold check, inferenza NOT NULL e suggerimento `dateformat`.
Codice morto rimosso: `build_suggested_read_cfg` non emette piu'
`ignore_errors`/`null_padding`/`auto_detect`/`strict_mode` — `clean.read` li
filtrava sempre, quindi suggeriva un comportamento inesistente.
Test: test_profile_read_parity.py (8: compact columns, union multi-file,
include, read_mode strict, row_count), test_raw_profile_visibility.py (5:
metadata + warning del gate). Due test riscritti dove pattavano
implementazione rimossa (`_profile_view`) con CSV realmente irregolari.
Suite: 1405 passed, ruff e mypy puliti.
L'audit dei marker (job audit-markers) richiede un marker per ogni test: i quattro test di test_raw_profile_visibility.py proteggevano il formato dell'artefatto (metadata.profile + warning del gate), quindi `contract`.
…rectory `_select_profile_files` chiamava `select_raw_input(raw_dir, ...)` senza `root/dataset/year`: con `dataset=None` la funzione ricade su `list_input_files(raw_dir)` (la directory), mentre il clean usa `list_raw_candidates` -> `_metadata_candidates` (le entry del manifest). Con un file presente su disco ma non elencato nel manifest il profilo descriveva un'altra relazione — la stessa classe che questa PR vuole chiudere. Casi reali nel workspace (5 dataset in mode all/explicit/largest con manifest valido e file extra): - `anac_stati_avanzamento`: 9 file a manifest, 10 su disco (copia del full). Profilo 3.459.926 righe contro le 2.185.125 del clean. - `openga_ricorsi_appalto`: 31 file a manifest, 32 su disco (`raw_input.csv`, concatenazione dei 31 da 35.116 righe). Profilo 70.232 contro 35.116. Il numero di 70.232 citato nella descrizione iniziale della PR era proprio quello gonfiato: corretto. Fix a due livelli, con la regola in un solo posto: - `run_raw` passa `source_files` = i file scritti da questo run. E' la verita' quando il profilo gira dentro il run: il `metadata.json` sul disco e' ancora quello del run precedente, quindi leggerlo darebbe la relazione vecchia. - senza `source_files` (chiamante diretto) la selezione usa il manifest via `select_raw_input(root=..., dataset=..., year=...)`, con la stessa soglia del clean (ultimo run RAW SUCCESS). `_is_usable_input_file` diventa pubblico (`is_usable_input_file`) perche' il filtro dei candidati e' la stessa regola, non una seconda copia. Test: due casi nuovi in test_profile_read_parity.py con layout reale (`<root>/data/raw/<ds>/<year>`), manifest a 2 file e un terzo file sciolto da 3 righe: `row_count` resta 2 sia passando `source_files` sia lasciando che la selezione legga il manifest. Suite 1407 passed, marker audit 60/60.
…ust con None Tre note dal review, più una regressione che è emersa scrivendone il test. 1. `inspect profile` non passava `read_mode`: `run_profile` profilava in `fallback` anche su dataset `strict`/`robust`, quindi la garanzia "il profilo non dichiara leggibile un file che il clean rifiuterebbe" valeva solo per `run_raw`. Ora legge `clean.read_mode`. 2. `_raw_root` è un'euristica sul layout `<root>/data/raw/<ds>/<year>`: `profile_raw` accetta `root` esplicito (lo usa `run_profile` con `cfg.root`) e l'inferenza resta solo come fallback per i chiamanti che non lo passano. 3. Regressione trovata dal test di (1): `robust_preset` usava `setdefault`, che non sovrascrive una chiave presente con valore `None` — e la config tipizzata emette tutte le chiavi. Il preset robusto restava quindi disattivato (`ignore_errors=None`, `null_padding=None`) e il fallback strict->robust falliva come lo strict. Il clean non lo vedeva perché riceve un dict già filtrato da `merge_read_cfg`; il profilo riceve quello grezzo, quindi ogni CSV irregolare profilato con `source: auto` finiva in `profile_failed`. Ora `None` vale "non impostato", anche in `create_profile_relation` (la parità con il clean passa da qui). Test: `test_inspect_profile_passes_read_mode` (fallback -> colonne, strict -> profilo vuoto) e `test_robust_preset_treats_none_as_unset`. Suite 1409 passed, marker audit 74/74.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sintesi
Il profilo RAW aveva un parser proprio: costruiva una
read_csva mano mentre il clean usaread_raw_to_relation. Le due copie sono divergite e il profilo falliva in silenzio — zero colonne, warning solo dentro_profile/raw_profile.json— lasciando il run verde.Misurato sul workspace (219 run con profilo vuoto): 188 erano ancora riproducibili con il codice precedente. Dopo il fix: 190 tornano pieni, 0 falliscono. La stessa PR chiude le due metà della parità (parametri di lettura e selezione dei file) e rende lo stato del profilo visibile nel gate.
Contesto collegato
Nessuna issue collegata: emerso da un'analisi della fase raw/profile su 631
dataset.ymle 1.480 artefattiraw_profile.jsondel workspace. La verifica prima/dopo è nei numeri qui sotto.Cosa cambia
Tre blocchi, un solo tema: il profilo deve descrivere la relazione che il clean legge.
1. Lettura.
profile_with_read_cfgcostruisceRAW_INPUT_VIEWconcore.duckdb_read.read_raw_to_relation, la funzione esatta del clean. Sparisce il parser del profilo, che non gestiva il formato compattocolumns: {column00: "nome:VARCHAR"}(DuckDB ricevevanome:VARCHARcome tipo),normalize_rows_to_columnsper nome ealign_by_header. Passa ancheread_mode(strict/fallback/robust) del dataset, quindi il profilo non può più dichiarare leggibile un file che il clean rifiuterebbe..odsera trattato come "zip non supportato" mentre il clean lo legge: ora è profilato.profile_exceldiventa un wrapper di 3 righe invece di un secondo parser pandas.2. Selezione file. Il profilo prendeva sempre il
primary_output_file; conmode: all|explicit|largestil clean legge N file (o il sottoinsieme diinclude), quindi hint,row_count,col_countenull_countsdescrivevano un'altra relazione. Ora la selezione è quella del clean, riusandoselect_raw_input, con una precisazione sul chi la decide:run_rawcontano i file scritti da questo run (source_files): ilmetadata.jsonsul disco è ancora quello del run precedente, quindi leggerlo darebbe la relazione vecchia;source_files) contano le entry del manifest, con la stessa soglia del clean (ultimo run RAWSUCCESS);Per questo
clean/input_selection.py→core/input_selection.py: è un contratto condiviso, non un dettaglio del clean.3. Stato visibile.
metadata.jsonesponeprofile: {status, file, row_count, columns, warnings};run_raw_validationemetteraw_profile_empty; readiness,inspect schemaereview-readinessriportanoprofile_statuse i warning.Codice morto rimosso:
build_suggested_read_cfgnon emette piùignore_errors/null_padding/auto_detect/strict_mode—clean.readli filtrava sempre (filter_suggested_format_keys), quindi suggeriva un comportamento che non arrivava mai.Impatto su contratti pubblici
dataset.yml(nuovo campo, cambio obbligatorietà)Dettaglio:
clean.input_selection→core.input_selection: verificata l'assenza di import in tutta l'org (rgsu workspace, esclusi_local/e note storiche). Nessuno shim: il modulo non era esportato daclean/__init__.profile_with_read_cfg(file0, ...)→(files: Path | Sequence[Path], ...): compatibile in posizione, accetta una lista per il multi-file. Nessun chiamante usafile0=come keyword.profile_excel(file0, ...)→(files: Path | Sequence[Path], ...): stessa forma di ritorno, ora wrapper.metadata.jsonraw: nuova chiave rootprofile(additiva; nessun consumer fuori dal toolkit la legge).build_suggested_read_cfg: rimossi 4 campi dall'output. Verificato che l'unico consumer (clean/read_config.load_suggested_read) li filtrava già.docs/:CHANGELOG.mdaggiornato. Nessun doc descrive le funzioni interne cambiate;docs/advanced-workflows.mdcontinua a valere (suggested_read.ymlnon più prodotto, leggibile come fallback).Verifica
Suite completa e strumenti statici:
Verifica sul campo, non solo unit test — rieseguendo il profilo sui dati reali del workspace con il codice nuovo:
FAILcon il codice precedente → 190ok, 0FAIL.mode: all|explicit|largest): 54 cambiano, 26 restano identici (quelli con un solo file). Scarti:ga_sentenze65.768 → 501.531 righe (31 file),openga_ricorsi_appalto8.446 → 35.116 (31 file a manifest),senato_ddl16 → 27 colonne,mur_esoneri9 → 15,bdap_ni_indicatorivuoto → 35 colonne / 8.801 righe. Costo: caso peggiore 1,6 s.anac_stati_avanzamento3.459.926 → 2.185.125 righe (9 file a manifest, non 10),openga_ricorsi_appalto70.232 → 35.116 (31 file, non 32:raw_input.csvè la concatenazione degli altri 31). Numeri verificati con lo stessoread_raw_to_relationche usa il clean.mode: latest: percorso invariato (manifest primary), nessuna modifica attesa né osservata.open-aciconincludediverso dal primary: ora profilano il file che il clean legge (Parco_veicolare_2025.xlsx, nonCircolante_Copert_2025.xlsx).None, oppure artefatti prodotti con un config precedente — es.skip: 1vsskip: 9attuale; un caso,inps_retribuzioni, ha il raw riscaricato l'11/11 contro un profilo del 28/10).Test aggiunti:
tests/test_profile_read_parity.py(11, markerregression/policy): formato compattocolumn00: "nome:VARCHAR", parità colonne profilo↔clean,align_by_header,read_mode: strict,row_count, union multi-file,include,latestinvariato, due casi con layout reale<root>/data/raw/<ds>/<year>dove un file sciolto nella directory non deve entrare (source_filese fallback al manifest), einspect profileche rispettaread_mode.tests/test_raw_profile_visibility.py(5):profile.statusnel metadata, warningraw_profile_emptynel gate,load_raw_profile_statusper artefatto assente/pieno/vuoto.2 test riscritti in
test_profile_sniff.py: pattavano_profile_view(implementazione rimossa) con un monkeypatch; ora usano un CSV realmente irregolare e testano il comportamento.pytest -m corepassa (suite intera eseguita)ruff check .passamypy toolkit/passaModificato o aggiunto test con marker appropriato (
contract/policy/regression/adapter/pure_unit/smoke) — verificato conaudit-test-markers tests --diff --files ...: 60/60 marcatiChecklist PR
rgsu tutta l'org, nessun importer del modulo spostato. Nessuna funzione pubblica rimossa.Note per chi revisiona
Punti da guardare con attenzione:
_select_profile_files: conlatest/fallbackresta ilprimary_output_filericevuto darun_raw(nessuna lettura extra del manifest). Conall/explicit/largestla selezione è delegata aselect_raw_input. Se la selezione solleva, si ricade sul primary con un warning — meglio un profilo parziale e dichiarato che nessuno.metadata.profileè una chiave nuova ma additiva. Non l'ho usata come fonte nei consumer:path_resolverereadinessrileggono l'artefatto conload_raw_profile_status, così un metadata vecchio resta leggibile.robust_preseteNone: il preset usavasetdefault, che non sovrascrive una chiave presente con valoreNone— e la config tipizzata le emette tutte. Il fallback strict→robust restava quindi disattivato per il profilo (il clean riceve un dict già filtrato damerge_read_cfg). Corretto:Nonevale "non impostato". Lo ha fatto emergere il test suinspect profile, che a sua volta non passavaread_mode.source_filesvs manifest: sono due percorsi per lo stesso risultato. Dentrorun_rawserve il primo (manifest sul disco = run precedente); per un chiamante diretto serve il secondo. Il test copre entrambi con lo stesso fixture, così una futura semplificazione non può romperne uno in silenzio.fail_on_error: true, trasformare un profilo vuoto in errore avrebbe reso rossi dataset oggi verdi. Il gate restawarn_only; l'escalation a errore è una decisione separata.ignore_errors: truequesto include il health probe diread_csv(uno scan in più). Sui dataset del workspace il caso peggiore misurato è 1,6 s.raw.sources[].namenon subisce la sostituzione di{year}(soloargsla subisce). Inappalti-pubblici/anac_bandi_garail sorgente si chiamacig_{year}senzaargs.filename, quindi il file viene scritto letteralmentecig_{year}.csve il manifest contiene unprimary_output_fileinesistente (il clean recupera con fallback "legacy selection"). Il fix cambia i nomi dei file raw: conmode: allun rilancio leggerebbe vecchio e nuovo insieme. Serve una migrazione concordata, non un cambio silenzioso: fuori da questa PR.suggested_read.yml: resta il fallback legacy inclean/read_config.py(0 file presenti su 640 dataset, nessun writer nel codice). Tocca il payload MCP (suggested_read_path/exists): candidato a una PR di pulizia separata.