Repository navigation
feat(ckan): ingest full + delta — split_resources, optional, safe_date, read_by_year - #547
Merged
Merged
Conversation
I dataset ANAC pubblicano un FULL e poi delta mensili. Il Manuale open data (v1.4 §5.1) prescrive che il delta sostituisca il full "per lo specifico CIG", non riga per riga: senza la provenienza la regola non e' implementabile. - `fetch_all(split=True)` / arg `split_resources: true`: invece di concatenare, restituisce uno ZIP con un CSV per risorsa, nominato `00-<nome>.csv`, `01-<nome>.csv`, ... ordinato per `last_modified`. Il nome file diventa l'ordine cronologico della risorsa, e si legge con l'extractor `unzip_all`. - `clean.read.source_file: true`: espone `__source_file` in `raw_input`, cosi' il clean puo' fare `max(__source_file) OVER (PARTITION BY <chiave>)`. Comportamento invariato senza `split_resources` (concatenazione storica): gli altri dataset che usano `download_all` non cambiano. Test: `test_fetch_all_split_restituisce_uno_zip_ordinato_per_risorsa` (il portale elenca il delta prima del full: vince comunque l'ordine cronologico). Suite completa: 1381 passed.
`raw.sources[].optional: true`: se il download fallisce il run prosegue con un warning invece di interrompersi. Serve ai dataset ANAC dove il pacchetto annuale non esiste per l'anno corrente (es. `cig-2026`) ed e' coperto da una sorgente delta. Il flag va anche serializzato in `RawSourceConfig.to_dict()`: senza, il config lo dichiarava ma il runner non lo vedeva (bug trovato sul campo). Test: `test_sorgente_optional_non_fa_fallire_il_run`.
Le fonti pubbliche contengono refusi sulle date (ANAC: anno 4202 al posto di 2024, 9202 al posto di 2022, 2806). `TRY_CAST` li accetta, quindi `max(data)` diventa 4202 e ogni metrica temporale e' rotta senza che nessuno se ne accorga (il valore non e' NULL). `safe_date(val)` e' `TRY_CAST(val AS DATE)` con scarto degli anni fuori da 1990-2100: la data impossibile diventa NULL, la riga resta. Test: set atteso di `test_macro_reader` aggiornato (9 macro).
Due difetti visti su un run interrotto del compose: - clean e mart scrivevano il parquet direttamente in place: uccidendo il processo restava un `anac_cross_2026_clean.parquet` troncato al posto di quello buono. Ora si scrive su `.<nome>.tmp` e si fa `replace` (stesso pattern gia' usato per i JSON). - il run record restava `RUNNING` per sempre. All'avvio di un nuovo `RunContext` i record RUNNING piu' vecchi di un'ora vengono chiusi come `ABORTED` (soglia per non toccare un run concorrente legittimo). `ABORTED` aggiunto a VALID_RUN_STATUSES. Test: `test_run_orfano_chiuso_come_aborted`.
Un dataset multi-anno puo' avere un anno con file sporchi e gli altri puliti.
Senza override si paga su tutti la config peggiore: su ANAC bandi
`parallel: false` (necessario solo al delta 2026, che ha newline dentro le
virgolette) rallentava di ~3x i 19 anni storici.
```yaml
clean:
read: {delim: ";"}
read_by_year:
2026: {strict_mode: false, parallel: false}
```
Le chiavi sono validate contro le opzioni ammesse (`unknown` -> ValueError).
Test: `test_read_by_year_override`.
…altate Due difetti trovati in review sulla PR di ingest full + delta. 1. `split_resources` numerava le risorse a due cifre (`00-`, `01-`). ANAC pubblica ~12 risorse all'anno: superate le 99, l'ordinamento lessicografico mette `100-` prima di `11-` e la sostituzione per chiave (max del nome file per CIG) applicherebbe un delta vecchio al posto del full. Ora tre cifre. 2. Le sorgenti `optional` saltate non lasciavano traccia: un run che aveva perso una fonte risultava identico a uno che aveva caricato tutto. Ora il motivo finisce in `raw.metadata.skipped_sources`, nel run record (metrica del layer `raw`) e nel manifest. In piu' `optional` non ingoia piu' gli errori di programmazione (AttributeError/ImportError/NameError/TypeError): copre la fonte assente, non i bug del plugin. Test: la regressione su `optional` ora verifica metadata e metrica; nuovo test che un errore di programmazione non venga mascherato.
…onal stretto Tre punti chiusi dalla review della PR #547. 1. `split_resources` con una risorsa che fallisce produceva uno ZIP incompleto senza dirlo. Ora: se salta la prima risorsa in ordine cronologico (il full) il fetch fallisce con DownloadError — senza il full il dataset si ridurrebbe ai soli delta, che portano solo novita'. Se saltano dei delta lo ZIP si produce lo stesso ma il warning elenca le risorse perse. Prima il test copriva l'ordine, non il fallimento. 2. `safe_date` scartava gli anni sotto il 1990: limite domain-specific per un macro generico, che avrebbe cancellato in silenzio un atto del 1942. Ora 1800-2100, con un test sul comportamento (1942 valida, 4202 refuso, 1001 non plausibile). Le attese per dominio restano nei controlli di quadratura del consumer. 3. `optional` catturava qualunque eccezione non "di programmazione": un timeout o un 500 produceva un dataset parziale a run verde. Ora copre solo `DownloadError` (fonte assente o irraggiungibile), che e' il caso per cui esiste. Un guasto di rete fa fallire il run. Piu' `split_resources: true` senza `download_all: true` ora e' un ValueError in config: prima veniva ignorato in silenzio. La validazione sta prima di `registry.create`, cosi' esce anche quando il tipo non e' registrato.
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
I dataset ANAC pubblicano un full fermo a gennaio 2026 piu' delta mensili: senza leggere entrambi, i dati si fermano alla data del full. Il toolkit non aveva modo di ingerirli correttamente. Questa PR aggiunge i quattro pezzi che mancavano, restando backward compatible (tutti i nuovi campi hanno default off).
ckan.split_resources: un file raw per risorsa, in ordine cronologico (00-…,01-…), cosi' il clean puo' applicare la regola di sostituzione per chiave applicativa (ANAC: il delta sostituisce il full per CIG) e non per rigaraw.sources[].optional: una sorgente che non esiste per un dato anno non fa fallire il run (cig-2026non esiste, il 2026 arriva dai delta)safe_date: scarta le date con anno impossibile (refusi tipo 4202 al posto di 2024) invece di lasciarle passare come valori validiclean.read_by_year: override di lettura per singolo anno (solo il 2026 ANAC ha virgolette escapate male e newline nei campi)RUNNINGper sempreContesto collegato
Consumato da
dataciviclab/appalti-pubblici(branchfeat/anac-copertura-full-delta): 12 dataset, 31,3M → 36,0M righe, bandi 6,1M → 12,08M. Quella PR va mergiata dopo questa: usasafe_date,split_resources,optionaleread_by_year. Il repo installa il toolkit dagit+https://github.com/dataciviclab/toolkit.git, quindi il merge sumainbasta (nessuna release).Cosa cambia
Impatto su contratti pubblici
dataset.yml(nuovo campo, cambio obbligatorietà)Dettaglio, tutto additivo:
raw.sources[].optionalfalseraw.sources[].args.split_resourcesfalseclean.read.source_filefalse__source_fileclean.read_by_yearreadsafe_dateCkanSource.fetch_all(..., split=False)falseABORTEDstatus_filterDocumentato in
docs/config-schema.md(sezionedownload_all/split_resources, tabella opzioniclean.read).docs/aggiornatodataset-incubator— non consuma questi campiVerifica
End-to-end reale:
dataciviclab/appalti-pubbliciha ri-scaricato 12 dataset ANAC in full + delta. Effetti misurati: aggiudicazioni 4,82M → 5,79M righe, SAL 2026 929 → 149.666, bandi 2017 leggibili (prima ilsample_sizefalliva), validateprimary_keyverde su tutti i 12.pytest -m corepassaruff check .passamypy toolkit/passaadapterper il plugin CKAN,pure_unitper raw,contractper run_context/macro)Checklist PR
Note per chi revisiona
Tre giri di correzione, tutti dopo la review (commit separati, storia leggibile):
1. Numerazione a 3 cifre (
e52543d). Con due cifre, oltre le 99 risorse l'ordine lessicografico mette100-prima di11-: il clean che sostituisce per chiave prenderebbe un delta vecchio al posto del full. ANAC pubblica ~12 risorse all'anno, quindi non e' teorico.2.
optionalvisibile e non onnivoro (e52543d,91c2c74). La sorgente saltata ora finisce inmetadata.skipped_sourcese nella metrica del layerraw: prima un run che aveva perso una fonte era indistinguibile da uno completo. In piu' copre soloDownloadError— un timeout o un 500 fa fallire il run invece di pubblicare un dataset parziale a run verde.3.
splitsenza full = errore (91c2c74). Se salta la prima risorsa in ordine cronologico (il full) il fetch fallisce: senza full il dataset si ridurrebbe ai soli delta, che portano solo novita'. Se saltano dei delta lo ZIP si produce, ma il warning elenca le risorse perse. Il test precedente copriva l'ordine, non il fallimento.4.
safe_dategenerica (91c2c74). Era 1990-2100: un limite domain-specific per una macro del toolkit, che avrebbe cancellato in silenzio un atto del 1942. Ora 1800-2100, con test sul comportamento (1942 valida, 4202 refuso, 1001 non plausibile). Le attese strette per dominio restano nei controlli di quadratura del consumer — inappalti-pubblicila finestra resta 1990 con un commento che spiega perche'.5.
split_resourcessenzadownload_all(91c2c74). Era ignorato in silenzio, ora e' unValueErrorin config, sollevato prima di istanziare il plugin.Restano aperti, dichiarati e non nascosti:
core/run_context.py:_close_orphan_runse' chiamato senzalogger, quindi il warning non viene mai emesso (il record si chiude lo stesso); la riscrittura non usa il retry suPermissionErrordiwrite_run_record.clean/sql_execute.pyemart/run.py: se ilCOPYfallisce a meta', il.tmpresta orfano. Non corrompe, accumula.last_modified: una risorsa senza il campo finisce prima (documentato da un test). Se un portale pubblicasse date non ISO, l'ordine non sarebbe piu' cronologico.