Formatta, valida e trasforma i dati delle etichette con Python prima della stampa

Un’etichetta prezzo che stampa 35.00 invece di 3.50 non è un problema di design. È un problema di dati — ed è il tipo di problema che sopravvive a ogni revisione visiva perché l’etichetta sembra a posto.

Questo articolo riguarda lo strato che la maggior parte dei flussi di lavoro per etichette salta: cosa succede al valore di un campo tra “il foglio di calcolo ha un valore” e “la stampante lo mette sulla carta”.

La freelancer che stava per consegnare un’etichetta prezzo sbagliata

Immagina una sviluppatrice freelance — chiamiamola Mara — che accetta un piccolo cliente retail: un negozio, quaranta SKU, un foglio di calcolo che la proprietaria gestisce da sola. Mara crea un modello di etichetta, collega il foglio di calcolo come origine dati, stampa un foglio di prova, e la prima etichetta mostra un pacchetto di caffè da 250 g a 35.00.

Il foglio di calcolo diceva 3,50. Una virgola decimale. Il design dell’etichetta si aspettava un punto, e nessuno se n’è accorto finché la bozza non è tornata indietro dalla proprietaria del negozio.

Il resto della colonna non è migliore:

• Prezzi come 3.5, 3,50, € 3.50, e alcune celle vuote.
• SKU che Excel ha silenziosamente trasformato in numeri, mangiandosi gli zeri iniziali che un codice a barre richiede.
• Date di scadenza in tre formati su quaranta righe.
• Codici fornitore con un prefisso SUP- che la proprietaria vuole rimuovere per un’etichetta più pulita.

Il primo istinto di Mara è quello standard: scrivere uno script di esportazione che ripulisce il CSV, poi passare il file ripulito allo strumento di stampa. Funziona — finché la proprietaria del negozio non modifica il foglio di calcolo la settimana dopo, e lo script di esportazione vive sul portatile di Mara, senza documentazione, e nessuno si ricorda di eseguirlo.

Quindi la vera domanda è questa: come si ripuliscono e si modellano i valori dei campi prima che raggiungano la stampante, senza mettere in piedi e mantenere una seconda pipeline di dati?

La risposta in RSJ LPSNG è la Python Field Script API: blocchi di script collegati ai singoli campi dell’etichetta che accedono e modificano i valori dei campi prima della stampa. Lo script viaggia con l’etichetta invece di vivere accanto ad essa.

Per chiarire l’ambito: non si tratta di progettare l’etichetta. Se cerchi il lato layout — posizionare testo, codici a barre e immagini nell’editor del browser — è trattato in How to Design Barcode Labels in a Browser Layout Editor. Questo articolo riguarda i valori che fluiscono dentro quel layout.

Perché il controllo dei dati a livello di campo conta per sviluppatori e utenti finali

La maggior parte dei difetti delle etichette sono difetti dei dati travestiti da design. Decimali sbagliati, date non formattate, zeri iniziali mancanti nei codici a barre, un nome prodotto troncato che non entra più — il layout sta facendo esattamente ciò che gli è stato detto. L’input era sbagliato.

Il controllo a livello di campo conta per due pubblici molto diversi, per la stessa ragione di fondo.

Per gli sviluppatori, elimina un’intera classe di infrastrutture collaterali. Non scrivi e mantieni uno script di pre-elaborazione esterno, un job pianificato che riscrive file CSV, o codice collante che sta tra l’origine dati e il motore di stampa. Formattazione e validazione vivono nella definizione dell’etichetta, che è l’artefatto che ne ha effettivamente bisogno.

Per gli utenti finali e i piccoli team, produce un output coerente senza richiedere a nessuno di capire i dati di origine. La proprietaria del negozio continua a compilare il suo foglio di calcolo come ha sempre fatto. È l’etichetta a decidere come viene visualizzato un prezzo.

La Python Field Script API è lo strato intermedio tra questi due mondi:

• Viene eseguita sul campo, non sul file.
• Può leggere e modificare il valore prima della stampa.
• Vive nella stessa piattaforma che renderizza l’etichetta, quindi non c’è deriva di versione tra “il ripulitore” e “il modello”.

Il riferimento dell’API è su lpsng.rsj.de/api.html.

Un playbook pratico: formattare, validare e trasformare in tre passaggi

Tratta ogni script di campo come tre passaggi sul valore, in questo ordine: formattalo, dimostralo, poi derivane qualcosa. Gli snippet qui sotto sono Python illustrativo — la parte importante è la forma della logica, non i nomi esatti degli helper.

Passaggio 1: Formattare

Normalizza il valore grezzo esattamente in ciò che il design dell’etichetta si aspetta. Prezzi a un pattern decimale fisso, date a un unico formato di visualizzazione, testo al casing attorno a cui è stato progettato il layout.

import re

CURRENCY = re.compile(r"[^\d,.\-]")

def format_price(raw):
    """'€ 3,50' -> '3.50'; returns None when nothing usable is left."""
    if raw is None:
        return None
    cleaned = CURRENCY.sub("", str(raw)).strip()
    if not cleaned:
        return None
    if "," in cleaned and "." in cleaned:
        cleaned = cleaned.replace(".", "").replace(",", ".")   # 1.234,56
    elif "," in cleaned:
        cleaned = cleaned.replace(",", ".")                    # 3,50
    return f"{float(cleaned):.2f}"

from datetime import datetime

DATE_FORMATS = ("%Y-%m-%d", "%d.%m.%Y", "%d/%m/%Y")

def format_date(raw, out="%d.%m.%Y"):
    text = str(raw or "").strip()
    for fmt in DATE_FORMATS:
        try:
            return datetime.strptime(text, fmt).strftime(out)
        except ValueError:
            continue
    return None   # unparseable beats guessed

def label_case(raw, style="upper"):
    text = " ".join(str(raw or "").split())   # collapse stray whitespace
    return text.upper() if style == "upper" else text.title()

Nota i ritorni None deliberati. Un valore non formattabile dovrebbe fallire in modo visibile nel passaggio successivo, non diventare uno 0.00 dall’aria plausibile.

Passaggio 2: Validare

La validazione è ciò che impedisce a un prezzo sbagliato di raggiungere silenziosamente la stampante. Verifica che i campi da cui dipendi esistano e siano ben formati, e rendi ogni messaggio abbastanza specifico da localizzare il record.

def validate_record(record):
    """Return a list of 'field: reason' strings. Empty list means OK."""
    errors = []

    sku = (record.get("sku") or "").strip()
    if not sku:
        errors.append("sku: missing")
    elif len(sku) < 8:
        errors.append(f"sku: shorter than 8 characters ({sku!r})")

    price = record.get("price")
    if price is None:
        errors.append("price: not parseable")
    elif not (0.01 <= price <= 9999.99):
        errors.append(f"price: out of range ({price!r})")

    if record.get("best_before") is None:
        errors.append("best_before: unparseable date")

    return errors

Un messaggio come price: not parseable ('0,00') dice a un operatore quale campo guardare e quale valore l’ha causato. Un messaggio come invalid data gli dice di chiamarti.

price: not parseable ('0,00')
sku: shorter than 8 characters ('4711')
best_before: unparseable date (row: Espresso 250g)

Passaggio 3: Trasformare

Solo dopo che il valore è formattato e validato dovresti derivarne valori di visualizzazione — un codice prodotto combinato, un prefisso fornitore rimosso, un nome breve per un campo stretto.

def product_code(record, prefix="SUP-"):
    supplier = (record.get("supplier_code") or "").strip()
    if supplier.startswith(prefix):
        supplier = supplier[len(prefix):]
    sku = (record.get("sku") or "").strip()
    return f"{supplier}-{sku}".strip("-")

Dove vive lo script nel flusso di lavoro

In RSJ LPSNG colleghi il blocco di script a un campo dell’etichetta nel layout. La piattaforma lo esegue come parte del normale job di stampa o rendering — la stessa esecuzione che gestisce anche l’output PDF o PNG e la stampa diretta tramite l’interfaccia web service. Non c’è alcun processo sidecar da avviare e nessun problema di ordinamento da ragionare.

Questo conta per il passaggio di consegne. La regola di formattazione fa parte della definizione dell’etichetta, quindi si sposta con il modello invece di restare sulla macchina di chi l’ha scritta.

Il modo difficile vs. il modo gestito

Il modo difficile è quello che Mara ha quasi scelto: uno script separato che riscrive file CSV o Excel prima che vengano passati a uno strumento di stampa. Ha la sua storia di deployment, le sue modalità di fallimento, e la sua silenziosa assunzione che tutti si ricordino di eseguirlo prima di stampare.

Il modo gestito mette il blocco di script Python sul campo stesso in RSJ LPSNG. Formattazione e validazione viaggiano con l’etichetta. La stessa etichetta può essere renderizzata come PDF o PNG, o inviata alla stampa diretta tramite l’interfaccia web service, e la logica del campo è la stessa in ogni caso perché appartiene all’etichetta, non a un passaggio esterno.

Checklist per il tuo primo script di campo

• Inizia con un campo e una regola. Formatta il prezzo, renderizza un PDF di esempio e ispezionalo. Solo allora passa al campo successivo.
• Rendi localizzabili i fallimenti. Ogni messaggio di validazione dovrebbe nominare il campo e mostrare il valore incriminato.
• Testa con input deliberatamente disordinati. Celle vuote, spazi extra, formati di data misti, un prezzo negativo, un prezzo di 0.00, uno SKU di lunghezza sbagliata.
• Decidi tra trasformazione e lookup. I file Excel possono servire sia come file di dati che come file di lookup, quindi un nome fornitore può appartenere a un foglio di riferimento invece di essere derivato nello script. Il lato origine dati è trattato in How to Print Barcoded Labels from Excel.
• Renderizza prima di eseguire. Una bozza PDF di tre record disordinati costa un minuto; una ristampa di quaranta etichette scaffale sbagliate costa una mattina.

Cosa evitare

Non seppellire le regole di business nel layout. Tieni formattazione e validazione nello script di campo e tieni le decisioni di design nell’editor del layout. Mescolarli significa che una modifica al design può cambiare silenziosamente un formato di prezzo.

Non forzare silenziosamente dati errati in un valore plausibile. Un’etichetta che stampa con sicurezza il prezzo sbagliato è peggio di un job che fallisce in modo rumoroso. Restituisci None e lascia che la validazione lo intercetti.

Non duplicare la stessa trasformazione su molti campi. Se sei campi hanno bisogno dello stesso formato di prezzo, un approccio condiviso batte sei blocchi copiati e incollati che divergono. L’incoerenza tra campi sulla stessa etichetta è una delle fonti di errore più comuni.

Non indovinare su input ambigui. 03/04/2026 è o il 4 marzo o il 3 aprile. Fissa il formato alla fonte; uno script che indovina sarà sbagliato per qualcuno.

Non trattare lo script come sostituto del test. Renderizza etichette di esempio e guardale. Gli script di campo riducono il numero di sorprese, non eliminano la necessità di controllare.

FAQ

Dove vengono eseguiti i blocchi di script Python in RSJ LPSNG?

I blocchi di script Python sono collegati ai campi dell’etichetta e accedono e modificano i valori dei campi prima della stampa, come parte della definizione dell’etichetta nella piattaforma.

Devo costruire una pipeline separata di pulizia dei dati?

No. Lo script di campo gestisce formattazione, validazione e trasformazione all’interno dell’etichetta stessa, quindi non hai bisogno di uno script sidecar che riscriva i tuoi file di dati prima che raggiungano il motore di stampa.

Posso comunque inviare job a livello di programmazione?

Sì. L’interfaccia web service ti permette di inviare job di stampa e renderizzare singole etichette come PDF o PNG, e il modello OAuth2 copre la connessione di sistemi esterni con un unico URL di registrazione.

La stessa logica di campo si applica a PDF, PNG e stampa diretta?

Il rendering PDF/PNG e la stampa diretta sono percorsi di output documentati dell’interfaccia web service, e la logica di campo appartiene alla definizione dell’etichetta che quei percorsi usano. Le etichette elettroniche da scaffale sono un binario separato con la propria interfaccia JSON neutrale rispetto al fornitore (ESLSEND) — vedi la documentazione dell’interfaccia ESL invece di assumere che il percorso di stampa si applichi invariato.

I non sviluppatori possono usare un’etichetta che contiene script di campo?

Sì. Una volta che lo script è collegato al campo, stampare l’etichetta non richiede di scrivere o leggere Python. Chi esegue il job seleziona i dati e stampa; formattazione e validazione avvengono come parte dell’etichetta.

Questo sostituisce l’editor del layout?

No. L’editor del layout gestisce il design; gli script di campo Python gestiscono i dati che fluiscono in ogni campo. Sono parti complementari della stessa etichetta.

Conclusione

La soluzione di Mara non è stata uno script di esportazione migliore. È stato spostare la regola dove il valore viene effettivamente usato: un campo prezzo che formatta una virgola decimale in 3.50, rifiuta di stampare una cella vuota, e rimuove un prefisso fornitore in uscita. La proprietaria del negozio ha tenuto il suo foglio di calcolo. Le etichette hanno smesso di essere sbagliate.

Next Generation Label Printing System è costruito esattamente attorno a questa separazione — design nell’editor del layout, controllo dei dati negli script di campo, e un’interfaccia web service quando vuoi pilotare i job a livello di programmazione. Inizia con un campo, una regola e un PDF renderizzato. Poi passa la mano.

Post correlati

• What Is Label Merge and How Does It Work?
• How to Design Barcode Labels in a Browser Layout Editor
• Best Label Printing Software for Developers: Buying Guide