Geração de Código de Barras

O pipeline de geração de códigos de barras em Aspose.BarCode FOSS para Python segue uma arquitetura de três estágios: analisar → codificar → renderizar. O API de alto nível (generate() e auxiliares por simbologia) orquestra essas etapas através de BarcodeService.

Geração de Alto Nível API

A maneira mais simples de gerar um código de barras é através das funções auxiliares por simbologia:

import aspose_barcode_foss as barcode

bc_128 = barcode.code128("ABC123")
bc_qr = barcode.qr("https://example.com")
bc_ean = barcode.ean13("590123412345")
bc_upca = barcode.upca("01234567890")

Cada auxiliar retorna um objeto Barcode. Chame to_svg() para saída SVG ou to_png() para saída PNG.

A função genérica generate() aceita uma string de nome de simbologia:

bc = barcode.generate("code128", "DATA")
svg = bc.to_svg()

Nomes de simbologia válidos: "code128", "code39", "ean13", "ean8", "qr", "upca", "upce".

BarcodeService

BarcodeService coordena as três etapas do pipeline. Ele contém um SymbologyRegistry e um OptionsResolver:

from aspose_barcode_foss import BarcodeService

# The default service is used by all helper functions
# You can create a custom service for testing or extension:
service = BarcodeService(registry=registry, options_resolver=resolver)
result = service.generate("code128", "DATA")

O método generate():

Procura o SymbologyDefinition no registro
Chama o InputParser.parse() para validar e normalizar a entrada
Chama o SymbologyEncoder.encode() para produzir um EncodedSymbol
Retorna um Barcode que envolve o símbolo e seu perfil

SymbologyRegistry

SymbologyRegistry armazena objetos SymbologyDefinition indexados por nomes canônicos e aliases:

Método	Descrição
`get_definition(name)`	Recupere uma definição completa de simbologia
`get_parser(name)`	Obtenha o `InputParser` para uma simbologia
`get_encoder(name)`	Obtenha o `SymbologyEncoder` para uma simbologia
`get_profile(name)`	Obtenha o `SymbologyProfile` com padrões
`get_text_policy(name)`	Obtenha o `TextLayoutPolicy` para renderização de texto
`register(definition)`	Registrar um novo `SymbologyDefinition`

EncoderRegistry é um alias compatível retroativamente com SymbologyRegistry.

SymbologyDefinition

Um SymbologyDefinition reúne todos os componentes necessários para suportar uma simbologia:

Propriedade	Tipo	Descrição
`name`	`str`	Identificador de simbologia canônica
`parser`	`InputParser`	Valida e normaliza dados de entrada
`encoder`	`SymbologyEncoder`	Codifica dados em uma matriz de módulo
`profile`	`SymbologyProfile`	Padrões, capacidades e política de texto
`aliases`	`tuple[str, ...]`	Nomes alternativos para lookup

EncodedSymbol

O EncodedSymbol retornado por um codificador contém:

matrix — um ModuleMatrix com a grade de módulos lógicos do código de barras
metadata — um SymbolMetadata com o nome da simbologia, texto de exibição e detalhes de codificação

bc = barcode.code128("TEST")
symbol = bc.symbol

print(f"Matrix: {symbol.matrix.width}x{symbol.matrix.height}")
print(f"Display text: {symbol.metadata.display_text}")
print(f"Symbology: {symbol.metadata.symbology}")

ModuleMatrix fornece um método get(x, y) que retorna o valor do módulo em uma posição dada.

NormalizedPayload

O NormalizedPayload é a representação intermediária entre a análise e a codificação:

Propriedade	Descrição
`symbology`	Nome canônico da simbologia
`data`	Dados de entrada validados (`str` ou `bytes`)
`input_kind`	Como a entrada foi classificada
`code128_encode_mode`	Modo Code 128 resolvido (se aplicável)
`code39_encode_mode`	Modo Code 39 resolvido (se aplicável)
`qr_error_correction_level`	Correção de erro QR resolvida (se aplicável)
`qr_version`	Versão QR resolvida (se aplicável)
`qr_encoding_mode`	Modo de codificação QR resolvido (se aplicável)

OptionsResolver

OptionsResolver mescla as opções de renderização fornecidas pelo usuário com os padrões de simbologia:

Método	Descrição
`resolve(profile, options)`	Produza um `ResolvedRenderOptions` mesclando as opções do usuário com os padrões do perfil
`merge_options(earlier, later)`	Mescle dois `RenderOptions` (valores posteriores sobrescrevem)
`coerce_options(options)`	Normalize as opções brutas em `RenderOptions`

Dicas e Melhores Práticas

Use auxiliares por simbologia (code128(), qr(), etc.) em vez de generate() para segurança de tipos — eles garantem que a classe de opções correta seja usada.
A propriedade Barcode.symbol fornece acesso direto ao EncodedSymbol para renderização ou análise personalizada.
BarcodeService é sem estado — uma instância pode gerar códigos de barras em múltiplas threads.
Capture BarcodeError como classe base para tratar todas as exceções relacionadas a códigos de barras em um único bloco.

Problemas Comuns

Problema	Causa	Corrigir
`SymbologyNotFoundError`	Nome não registrado em `SymbologyRegistry`	Verifique a ortografia; use nomes canônicos
`InvalidInputError`	Os dados violam os requisitos de simbologia	Verifique o conjunto de caracteres e os requisitos de comprimento
Saída SVG vazia	Nenhum módulo codificado	Verifique se os dados não estão vazios e são válidos para a simbologia

Ver também

Aspose.BarCode for Python — Enterprise Documentation