Skip to content

feat(ckan): ingest full + delta — split_resources, optional, safe_date, read_by_year - #547

Merged
Gabrymi93 merged 7 commits into
mainfrom
feat/ckan-split-resources
Nov 15, 2026
Merged

Gabrymi93 merged 7 commits into
mainfrom
feat/ckan-split-resources

Conversation

@Gabrymi93

@Gabrymi93 Gabrymi93 commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

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 riga
  • raw.sources[].optional: una sorgente che non esiste per un dato anno non fa fallire il run (cig-2026 non esiste, il 2026 arriva dai delta)
  • macro safe_date: scarta le date con anno impossibile (refusi tipo 4202 al posto di 2024) invece di lasciarle passare come valori validi
  • clean.read_by_year: override di lettura per singolo anno (solo il 2026 ANAC ha virgolette escapate male e newline nei campi)
  • scritture atomiche di clean/mart e chiusura dei run record orfani: un run interrotto lasciava un parquet troncato al posto di quello buono e un record RUNNING per sempre

Contesto collegato

Consumato da dataciviclab/appalti-pubblici (branch feat/anac-copertura-full-delta): 12 dataset, 31,3M → 36,0M righe, bandi 6,1M → 12,08M. Quella PR va mergiata dopo questa: usa safe_date, split_resources, optional e read_by_year. Il repo installa il toolkit da git+https://github.com/dataciviclab/toolkit.git, quindi il merge su main basta (nessuna release).

Cosa cambia

  • Bug fix
  • Nuova funzionalità del motore
  • Nuovo plugin sorgente
  • Modifica contratto pubblico (dataset.yml, path output, schema parquet)
  • Refactor / performance
  • Documentazione
  • Dipendenze o CI

Impatto su contratti pubblici

  • Struttura dataset.yml (nuovo campo, cambio obbligatorietà)
  • Path output (nuovo layer, cambio percorso artifact)
  • Schema parquet (nuova colonna, rename, cambio tipo)
  • CLI o MCP tool (nuovo comando, cambio parametro)
  • API pubblica del toolkit (firma funzione, classe, eccezione)

Dettaglio, tutto additivo:

superficie aggiunta default effetto se assente
raw.sources[].optional bool false comportamento invariato (errore)
raw.sources[].args.split_resources bool false unico CSV concatenato, come prima
clean.read.source_file bool false nessuna colonna __source_file
clean.read_by_year mappa anno → opzioni read assente nessun override
macro SQL safe_date — —
CkanSource.fetch_all(..., split=False) kwarg false firma compatibile
run status ABORTED — solo filtro status_filter

Documentato in docs/config-schema.md (sezione download_all / split_resources, tabella opzioni clean.read).

  • docs/ aggiornato
  • dataset-incubator — non consuma questi campi

Verifica

pytest -q                                  # 1390 passed
pytest -q -m "core or contract or policy or regression"   # 912 passed
ruff check .                               # All checks passed
mypy toolkit/                              # Success: no issues found in 127 source files

End-to-end reale: dataciviclab/appalti-pubblici ha 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 il sample_size falliva), validate primary_key verde su tutti i 12.

  • pytest -m core passa
  • ruff check . passa
  • mypy toolkit/ passa
  • Test aggiunti con marker (adapter per il plugin CKAN, pure_unit per raw, contract per run_context/macro)

Checklist PR

  • Perimetro stretto: una PR = un layer o un fix mirato
  • Se nuovo plugin: N/A
  • Issue collegata o motivazione dell'assenza → da collegare
  • Nessuna funzione/modulo pubblico rimosso (solo aggiunte con default off)

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 mette 100- prima di 11-: 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. optional visibile e non onnivoro (e52543d, 91c2c74). La sorgente saltata ora finisce in metadata.skipped_sources e nella metrica del layer raw: prima un run che aveva perso una fonte era indistinguibile da uno completo. In piu' copre solo DownloadError — un timeout o un 500 fa fallire il run invece di pubblicare un dataset parziale a run verde.

3. split senza 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_date generica (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 — in appalti-pubblici la finestra resta 1990 con un commento che spiega perche'.

5. split_resources senza download_all (91c2c74). Era ignorato in silenzio, ora e' un ValueError in config, sollevato prima di istanziare il plugin.

Restano aperti, dichiarati e non nascosti:

  1. core/run_context.py: _close_orphan_runs e' chiamato senza logger, quindi il warning non viene mai emesso (il record si chiude lo stesso); la riscrittura non usa il retry su PermissionError di write_run_record.
  2. clean/sql_execute.py e mart/run.py: se il COPY fallisce a meta', il .tmp resta orfano. Non corrompe, accumula.
  3. Soglia 1h dei run orfani: euristica. Un run legittimo piu' lungo, con un secondo run concorrente sullo stesso dataset/anno, verrebbe marcato ABORTED.
  4. L'ordine dello split e' un sort di stringa su 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.

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.
@Gabrymi93
Gabrymi93 merged commit 0dc9b33 into main Nov 15, 2026
3 checks passed
@Gabrymi93
Gabrymi93 deleted the feat/ckan-split-resources branch November 15, 2026 20:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant