Validazione dell'Input e Gestione degli Errori

Validazione dell’Input e Gestione degli Errori

Aspose.BarCode FOSS for Python valida tutti i dati di input prima della codifica. Ogni simbologia ha una sottoclasse InputParser dedicata che controlla i set di caratteri, i vincoli di lunghezza e le regole di formato. Quando la convalida fallisce, la libreria solleva eccezioni tipizzate dalla gerarchia BarcodeError così i chiamanti possono distinguere tra problemi di input, errori di codifica e problemi di rendering.

Il Livello InputParser

Ogni simbologia registra un’implementazione InputParser. Quando chiami BarcodeService.generate(), il parser viene eseguito per primo, producendo un NormalizedPayload o sollevando InvalidInputError se i dati non sono validi per quella simbologia.

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# Valid Code 128 input — passes the Code128InputParser
barcode = service.generate("code128", "VALID-DATA-001")

# Invalid EAN-13 input — too few digits
try:
    barcode = service.generate("ean13", "123")
except Exception as e:
    print(type(e).__name__, e)

Ogni parser di simbologia valida regole diverse:

• Code128InputParser — verifica che tutti i caratteri siano nell’intervallo ASCII supportato dai set di caratteri Code 128
• Code39InputParser — valida i caratteri rispetto all’alfabeto base Code 39 o all’alfabeto ASCII completo a seconda di Code39Options.full_ascii
• Ean13InputParser — richiede esattamente 12 o 13 cifre numeriche (la 13ª è la cifra di controllo)
• Ean8InputParser — richiede esattamente 7 o 8 cifre numeriche
• QrInputParser — convalida i dati rispetto al QrEncodeMode selezionato (NUMERIC, ALPHANUMERIC, BYTE o KANJI)
• UpcaInputParser — richiede esattamente 11 o 12 cifre numeriche
• UpceInputParser — richiede esattamente 6, 7 o 8 cifre numeriche con un modello UPC-E valido

La gerarchia BarcodeError

Tutte le eccezioni ereditano da BarcodeError, che estende il Exception integrato di Python. La gerarchia consente blocchi catch a diversi livelli di specificità:

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import (
    BarcodeError,
    InvalidInputError,
    EncodingError,
    SymbologyNotFoundError,
)

service = BarcodeService()

try:
    barcode = service.generate("code128", "TEST-001")
    svg = barcode.to_svg()
except InvalidInputError as e:
    print(f"Input rejected: {e}")
except EncodingError as e:
    print(f"Encoding failed: {e}")
except SymbologyNotFoundError as e:
    print(f"Unknown symbology: {e}")
except BarcodeError as e:
    print(f"Barcode error: {e}")

Validazione dei nomi di simbologia

SymbologyNotFoundError viene sollevato quando BarcodeService.generate() riceve un nome di simbologia che non è registrato. Il SymbologyRegistry risolve i nomi per nome canonico o alias, quindi "code128", "Code128" e "CODE128" si risolvono tutti nella stessa definizione.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import SymbologyNotFoundError

service = BarcodeService()

try:
    barcode = service.generate("invalid_type", "data")
except SymbologyNotFoundError as e:
    print(f"Not found: {e}")

Validazione della cifra di controllo

EAN-13, EAN-8, UPC-A e UPC-E le simbologie calcolano automaticamente le cifre di controllo. Se fornisci i dati completi includendo una cifra di controllo, il parser la verifica rispetto al valore calcolato. La proprietà allow_check_digit_input su Ean13Options e Ean8Options controlla questo comportamento.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss import Ean13Options

service = BarcodeService()

# 12 digits — check digit computed automatically
barcode = service.generate("ean13", "590123412345")

# 13 digits — parser verifies the 13th digit matches the computed value
barcode = service.generate(
    "ean13", "5901234123457",
    encode=Ean13Options(allow_check_digit_input=True),
)

Suggerimenti e migliori pratiche

• Gestisci InvalidInputError per i moduli di input rivolti agli utenti dove i dati potrebbero non soddisfare i requisiti della simbologia
• Utilizza BarcodeError come cattura generale solo quando non è necessario distinguere tra i tipi di errore
• Verifica il nome della simbologia rispetto alle sette simbologie supportate (code128, code39, ean13, ean8, qrcode, upca, upce) prima di chiamare generate() per evitare SymbologyNotFoundError
• Per i codici QR, imposta encoding_mode esplicitamente tramite QrOptions quando i dati contengono caratteri non ASCII
• Lascia che la libreria calcoli le cifre di controllo anziché fornirle manualmente — questo evita incongruenze

Problemi comuni

FAQ

Come posso verificare se un nome di simbologia è valido prima di generare?

Usa BarcodeService.registry per accedere al SymbologyRegistry. Chiama get_definition() e intercetta SymbologyNotFoundError se il nome non è registrato.

Posso disabilitare la convalida della cifra di controllo per i codici a barre EAN?

Il parser convalida sempre le cifre di controllo quando fornisci l’input a lunghezza completa (13 cifre per EAN-13, 8 per EAN-8). Per evitare la convalida, fornisci solo le cifre dati (12 per EAN-13, 7 per EAN-8) e lascia che la libreria calcoli la cifra di controllo.

Cosa succede se passo dati binari a una simbologia di codice a barre 1D?

InvalidInputError viene sollevato. Le simbologie Code 128, Code 39, EAN e UPC accettano solo dati di testo. Per dati binari, usare QR Code con QrEncodeMode.BYTE.

La libreria valida la lunghezza dei dati per i codici QR?

QrInputParser verifica che i dati rientrino nella capacità della versione QR richiesta. Se non è specificata alcuna versione, la libreria seleziona la versione più piccola che può contenere i dati.

API Reference Riepilogo

Vedi anche

• Aspose.BarCode for Python — Enterprise Documentation