Validación de Entrada y Manejo de Errores

Validación de Entrada y Manejo de Errores

Aspose.BarCode FOSS para Python valida todos los datos de entrada antes de codificar. Cada simbología tiene una subclase InputParser dedicada que verifica los conjuntos de caracteres, las restricciones de longitud y las reglas de formato. Cuando la validación falla, la biblioteca lanza excepciones tipadas de la jerarquía BarcodeError para que los llamadores puedan distinguir entre problemas de entrada, fallos de codificación y problemas de renderizado.

La capa InputParser

Cada simbología registra una implementación InputParser. Cuando llamas a BarcodeService.generate(), el analizador se ejecuta primero, produciendo un NormalizedPayload o generando InvalidInputError si los datos no son válidos para esa simbología.

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)

Cada analizador de simbología valida reglas diferentes:

• Code128InputParser — verifica que todos los caracteres estén en el rango ASCII admitido por los conjuntos de caracteres Code 128
• Code39InputParser — valida los caracteres contra la base Code 39 o el alfabeto ASCII completo dependiendo de Code39Options.full_ascii
• Ean13InputParser — requiere exactamente 12 o 13 dígitos numéricos (el 13.º es el dígito de control)
• Ean8InputParser — requiere exactamente 7 u 8 dígitos numéricos
• QrInputParser — valida los datos contra el QrEncodeMode seleccionado (NUMERIC, ALPHANUMERIC, BYTE, o KANJI)
• UpcaInputParser — requiere exactamente 11 o 12 dígitos numéricos
• UpceInputParser — requiere exactamente 6, 7 u 8 dígitos numéricos con un patrón UPC-E válido

La jerarquía BarcodeError

Todas las excepciones heredan de BarcodeError, que extiende el Exception incorporado de Python. La jerarquía permite bloques catch en diferentes niveles de especificidad:

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}")

Validación de nombres de simbología

SymbologyNotFoundError se lanza cuando BarcodeService.generate() recibe un nombre de simbología que no está registrado. El SymbologyRegistry resuelve nombres por nombre canónico o alias, por lo que "code128", "Code128" y "CODE128" se resuelven a la misma definición.

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}")

Validación del Dígito de Control

Las simbologías EAN-13, EAN-8, UPC-A y UPC-E calculan los dígitos de control automáticamente. Si pasas los datos completos, incluido un dígito de control, el analizador lo verifica contra el valor calculado. La propiedad allow_check_digit_input en Ean13Options y Ean8Options controla este comportamiento.

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),
)

Consejos y Mejores Prácticas

• Captura InvalidInputError en formularios de entrada dirigidos al usuario donde los datos podrían no cumplir con los requisitos de la simbología
• Utiliza BarcodeError como captura general solo cuando no necesites distinguir entre tipos de error
• Verifica el nombre de la simbología contra las siete simbologías admitidas (code128, code39, ean13, ean8, qrcode, upca, upce) antes de llamar a generate() para evitar SymbologyNotFoundError
• Para códigos QR, establece encoding_mode explícitamente a través de QrOptions cuando los datos contengan caracteres no ASCII
• Deje que la biblioteca calcule los dígitos de control en lugar de suministrarlos manualmente — esto evita desajustes

Problemas comunes

FAQ

¿Cómo verifico si un nombre de simbología es válido antes de generar?

Use BarcodeService.registry para acceder al SymbologyRegistry. Llame a get_definition() y capture SymbologyNotFoundError si el nombre no está registrado.

¿Puedo desactivar la validación del dígito de control para códigos de barras EAN?

El analizador siempre valida los dígitos de control cuando proporciona la entrada de longitud completa (13 dígitos para EAN-13, 8 para EAN-8). Para evitar la validación, proporcione solo los dígitos de datos (12 para EAN-13, 7 para EAN-8) y deje que la biblioteca calcule el dígito de control.

¿Qué ocurre si paso datos binarios a una simbología de código de barras 1D?

InvalidInputError se lanza. Las simbologías Code 128, Code 39, EAN y UPC solo aceptan datos de texto. Para datos binarios, use QR Code con QrEncodeMode.BYTE.

¿La biblioteca valida la longitud de los datos para los códigos QR?

QrInputParser valida que los datos caben dentro de la capacidad de la versión QR solicitada. Si no se especifica una versión, la biblioteca selecciona la versión más pequeña que acomoda los datos.

Resumen de API Reference

Ver también

• Aspose.BarCode for Python — Enterprise Documentation