Validação de Entrada e Tratamento de Erros

Validação de Entrada e Tratamento de Erros

Aspose.BarCode FOSS for Python valida todos os dados de entrada antes da codificação. Cada simbologia tem uma subclasse InputParser dedicada que verifica conjuntos de caracteres, restrições de comprimento e regras de formato. Quando a validação falha, a biblioteca lança exceções tipadas da hierarquia BarcodeError para que os chamadores possam distinguir entre problemas de entrada, falhas de codificação e questões de renderização.

A camada InputParser

Cada simbologia registra uma implementação InputParser. Quando você chama BarcodeService.generate(), o analisador é executado primeiro, produzindo um NormalizedPayload ou levantando InvalidInputError se os dados não forem válidos para essa 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)

Cada analisador de simbologia valida regras diferentes:

• Code128InputParser — verifica se todos os caracteres estão no intervalo ASCII suportado pelos conjuntos de caracteres Code 128
• Code39InputParser — valida os caracteres contra a base Code 39 ou o alfabeto ASCII completo, dependendo de Code39Options.full_ascii
• Ean13InputParser — requer exatamente 12 ou 13 dígitos numéricos (o 13º é o dígito verificador)
• Ean8InputParser — requer exatamente 7 ou 8 dígitos numéricos
• QrInputParser — valida os dados contra o QrEncodeMode selecionado (NUMERIC, ALPHANUMERIC, BYTE ou KANJI)
• UpcaInputParser — requer exatamente 11 ou 12 dígitos numéricos
• UpceInputParser — requer exatamente 6, 7 ou 8 dígitos numéricos com um padrão UPC-E válido

A hierarquia BarcodeError

Todas as exceções herdam de BarcodeError, que estende o Exception interno de Python. A hierarquia permite blocos catch em diferentes níveis de especificidade:

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

Validando nomes de simbologia

SymbologyNotFoundError é levantado quando BarcodeService.generate() recebe um nome de simbologia que não está registrado. O SymbologyRegistry resolve nomes por nome canônico ou alias, portanto "code128", "Code128" e "CODE128" resolvem para a mesma definição.

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

Validação de Dígito Verificador

As simbologias EAN-13, EAN-8, UPC-A e UPC-E calculam dígitos verificadores automaticamente. Se você passar os dados completos incluindo um dígito verificador, o analisador verifica-o contra o valor calculado. A propriedade allow_check_digit_input em Ean13Options e Ean8Options controla esse 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),
)

Dicas e Melhores Práticas

• Capture InvalidInputError para formulários de entrada voltados ao usuário onde os dados podem não atender aos requisitos da simbologia
• Use BarcodeError como captura geral somente quando você não precisar distinguir entre tipos de erro
• Verifique o nome da simbologia contra as sete simbologias suportadas (code128, code39, ean13, ean8, qrcode, upca, upce) antes de chamar generate() para evitar SymbologyNotFoundError
• Para códigos QR, defina encoding_mode explicitamente via QrOptions quando os dados contiverem caracteres não-ASCII
• Deixe a biblioteca calcular os dígitos de verificação em vez de fornecê-los manualmente — isso evita incompatibilidades

Problemas comuns

FAQ

Como verificar se um nome de simbologia é válido antes de gerar?

Use BarcodeService.registry para acessar o SymbologyRegistry. Chame get_definition() e capture SymbologyNotFoundError se o nome não estiver registrado.

Posso desativar a validação do dígito de verificação para códigos de barras EAN?

O analisador sempre valida os dígitos de verificação quando você fornece a entrada de comprimento total (13 dígitos para EAN-13, 8 para EAN-8). Para evitar a validação, forneça apenas os dígitos de dados (12 para EAN-13, 7 para EAN-8) e deixe a biblioteca calcular o dígito de verificação.

O que acontece se eu passar dados binários para uma simbologia de código de barras 1D?

InvalidInputError é levantado. Code 128, Code 39, EAN e UPC aceitam apenas dados de texto. Para dados binários, use QR Code com QrEncodeMode.BYTE.

A biblioteca valida o comprimento dos dados para códigos QR?

QrInputParser valida que os dados cabem dentro da capacidade da versão QR solicitada. Se nenhuma versão for especificada, a biblioteca seleciona a menor versão que acomoda os dados.

Resumo API Reference

Ver também

• Aspose.BarCode for Python — Enterprise Documentation