Lo strumento condiviso separa la scelta delle colonne e dei tipi dalla scrittura nel formato richiesto. Il 10 ottobre 2026 l’API e l’adattatore di creazione locale XLSX/CSV sono integrati in main; le prove sintetiche registrate hanno superato 158 casi (138 del modulo e 20 di regressione), senza errori né esclusioni. L’adozione sul server è stata verificata nella release 164, con readback autenticato. Restano separati il collaudo live R-019, l’adozione Google e la verifica del pacchetto caricato sul PC.
L'API interna write_table(source, spec, destination, mode="create") riceve record oppure righe di una matrice. Uno schema esplicito dichiara per ogni colonna intestazione, campo sorgente esatto, trasformazione ammessa e tipo. Il compilatore produce un contratto versionato Workbook / Sheet / Column / Cell; gli adattatori scrivono soltanto quel contratto. La risoluzione delle vecchie intestazioni resta al confine del runtime e usa la proiezione condivisa esistente, su tutte le righe pubbliche.
Nel contratto condiviso ogni riga della matrice è un dato, anche se uguale all’intestazione. L’adattatore di creazione locale consuma un’intestazione soltanto quando il chiamante l’ha dichiarata o la proiezione dei record l’ha prodotta; una matrice senza colonne dichiarate conserva la prima riga come dato. Nessuna riga viene eliminata come duplicata. I campi privati e quelli dichiarati sensibili dal runtime vengono esclusi anche dai valori strutturati e dai metadati annidati.
from tabular.api import write_table
receipt = write_table(
[{"observed": "2027-04-12", "amount": "12,50 EUR"}],
{"locale": "it", "name": "Dati", "column_specs": [
{"header": "Data", "source": "observed", "type": "date"},
{"header": "Importo", "source": "amount", "type": "currency", "currency": "EUR"}]},
{"backend": "local_xlsx", "path": "sintetico.xlsx"})column_specs separa source, la chiave esatta dei record, da header, il testo da mostrare in qualsiasi lingua o alfabeto. Il planner, l’extractor o l’executor che conosce lo schema deve fornire questa mappa: per esempio {"source":"amount","header":"Montant"}. L’ordine delle chiavi nei record non conta. Il writer non traduce le chiavi, non deduce equivalenze dai valori o dalla posizione e non richiama Frontier. Non vengono aggiunti alias per ogni lingua; una mappa esplicita funziona anche senza un lessico di intestazioni.
Il normale piano può dichiarare la mappa usando lo schema che ha già a disposizione, senza un’ulteriore chiamata al modello. La risoluzione storica delle sole intestazioni resta disponibile al confine esistente; se manca una mappa e la corrispondenza non è univoca, restituisce un errore con intestazioni e campi disponibili. Due date con ruoli distinti non vengono fuse: occorre dichiarare quale campo usare.
I numeri e i booleani nativi conservano il tipo. Le stringhe diventano numeri o importi soltanto quando lo schema lo richiede, con grammatica deterministica e lingua esplicita per i separatori locali. La valuta deve essere dichiarata. Oltre 15 cifre significative, valori non finiti e conversioni che perdono precisione restano testo con un avviso. Una stringa di codice come 00123 resta testo senza una richiesta esplicita di conversione.
Le date complete diventano date effettive; mese/anno, anno solo, anno assunto con * e date impossibili restano testo. Gli istanti con fuso orario e i valori con precisione superiore al millisecondo restano testo finché non viene dichiarata una conversione adeguata. Il sistema non aggiunge giorno, anno o mezzanotte mancanti. La lingua numerica non sceglie una grammatica regionale delle date: le date con barre seguono il helper esistente giorno/mese/anno; per una interfaccia univoca usare ISO.
Il contratto iniziale non accetta formule. Né un campo type="formula" né un valore estratto da un sito possono autorizzarle. Gli XLSX mantengono come testo le nuove celle attive; Google usa valori stringa espliciti. Il CSV aggiunge un apostrofo visibile ai testi attivi, compresi intestazioni e Note; la ricevuta segnala questa modifica.
| Formato | Modalità dell’API condivisa | Tipi e limiti |
|---|---|---|
| XLSX locale | creazione, sovrascrittura di schede richieste, aggiunta | più schede; numeri, date e booleani; 1.048.576 righe, 16.384 colonne, 32.767 caratteri per cella; limite operativo 5 milioni di celle |
| CSV locale | creazione, sovrascrittura, aggiunta | una scheda dati, testo; stessi limiti operativi locali; Note in un secondo CSV |
| Google Sheets | creazione con tutti i dati | più schede e tipi; 1 milione di righe, 18.278 colonne, 50.000 caratteri per cella e 10 milioni di celle |
| Dispositivo | creazione locale prevista dal pacchetto aggiornato | creazione XLSX con sola libreria standard; occorrono consegna e verifica del pacchetto effettivamente caricato. Il backend esplicito device dell’API resta rifiutato |
I limiti fisici sulle righe comprendono l’intestazione; max_rows del chiamante conta invece le righe dati. La lingua numerica è spec.locale globale: una lingua diversa per scheda viene rifiutata. Un limite del chiamante pari a zero non aggiunge un vincolo; restano i limiti fisici e operativi. Ogni riduzione dichiarata riporta nella ricevuta il campo limitante, la quantità usata e quella disponibile quando nota. Le Note devono rientrare nei limiti; altrimenti la scrittura si ferma prima di modificare la destinazione.
I flag dichiarati dalla sorgente, come truncated e collection_partial, il totale available_total, la quantità used e i metadati del limite restano in source_metadata, separati per scheda e ripuliti dai campi privati o sensibili. Un totale ignoto resta null. I soli conteggi non autorizzano a dichiarare la raccolta completa o incompleta.
source_partial e source_truncated descrivono la dichiarazione della sorgente; writer_truncated e truncations descrivono invece le riduzioni applicate alla scrittura. Il totale generale della ricevuta conta le righe ricevute dal writer, non sostituisce il totale dichiarato dalla sorgente. Un flag di raccolta parziale produce l’avviso localizzato WARN_TABLE_PARTIAL_SOURCE in chat e nelle Note anche senza una ragione testuale. Un file riletto e verificato non dimostra che siano state raccolte tutte le pagine del sito.
Il broker del browser produce un involucro tipizzato con il produttore e uno scope proprio della raccolta. I metadati seguono act_sites → read_sites → extract_entries → filter_entries → write_table attraverso l’adattatore locale, come argomento risolto dal runtime: il testo delle pagine, le righe e il modello non possono dichiararne la completezza. Un’estrazione o un filtro riusciti conservano l’incompletezza a monte. La causa nota genera una spiegazione localizzata nelle Note e in chat; una causa sconosciuta mantiene l’avviso generico senza esporre il codice tecnico. La provenienza conserva solo origine e percorso HTTP(S), senza credenziali, query o frammento. Produttore e scope non identificano fatture e non autorizzano nuove associazioni o eliminazioni di righe.
L’anteprima testuale dopo la navigazione è separata dai dati conservati: il taglio visivo a 4.000 caratteri espone presentation_truncated, preview_used e preview_available_total, senza dichiarare un taglio della raccolta né modificarne i limiti. Un arresto reale della raccolta conserva invece il proprio stato parziale e la causa fino al foglio; la verifica del file non li annulla.
Avvisi e provenienza compaiono sia nella ricevuta destinata alla chat sia nella scheda Note; in caso di collisione tra nuove schede viene dichiarato il nome assegnato, per esempio Note_2. Una scheda Note preesistente dell'utente viene preservata: la scrittura che la sovrascriverebbe viene rifiutata. Le Note generate sono riconoscibili da un marcatore interno; l'aggiornamento non lascia silenziosamente vecchie Note incoerenti.
Nel CSV le Note sono <nome>_note.csv. La ricevuta elenca entrambi i file e l'annullamento di ciascuno. Per aggiornare una coppia esistente occorre dichiarare anche destination.notes_path; un file di Note estraneo non viene sovrascritto implicitamente. La pubblicazione della coppia non è atomica: se fallisce il secondo file, la ricevuta conserva il primo come risultato parziale.
La ricevuta distingue righe compilate, righe verificate e artefatti effettivamente creati o modificati. XLSX e CSV vengono riletti prima della pubblicazione; Google viene riletto confrontando valori tipizzati e formati. Un identificatore Google creato resta nella ricevuta con il relativo annullamento anche quando la rilettura fallisce. Un errore di creazione senza identificatore ha esito sconosciuto e non viene ritentato automaticamente.
Il codice integrato instrada la creazione locale di backends.files.local.create_spreadsheet verso write_table, mantenendo il confine di consenso del chiamante, la proiezione condivisa e l’annullamento ordinario di tutti i file creati, comprese le Note CSV. La creazione XLSX e la sua rilettura usano il writer della libreria standard; sovrascrittura e aggiunta XLSX continuano a richiedere openpyxl. Il normalizzatore di date osservate è anch’esso puro e usa nomi dei mesi forniti esplicitamente; la facciata server conserva il lookup del catalogo.
La distribuzione deve includere i supporti del writer e del normalizzatore. Il codice di creazione aggiornato su un pacchetto privo di questi supporti restituisce un errore senza attestare un file verificato; un pacchetto interamente precedente continua a usare il proprio codice precedente. L’offerta server non prova quale pacchetto abbia caricato un dispositivo: serve un riscontro effettivo prima di attestare l’adozione.
I percorsi Google esistenti non sono adottati da questa modifica: l’API condivisa riusa il client OAuth Python, ma consenso, ripresa con gli input originali e adozione Google richiedono verifiche separate. L’adozione locale ha superato i casi registrati 1012/22366 e 1013/22367; il riscontro del pacchetto effettivamente caricato sul PC resta da eseguire. R-019 rimane aperta: la verifica di scrittura non dimostra la completezza della raccolta né un collaudo live riuscito.