Barcode Generation

The barcode generation pipeline in Aspose.BarCode FOSS for Python follows a three-stage architecture: parse → encode → render. The high-level API (generate() and per-symbology helpers) orchestrates these stages through BarcodeService.

High-Level Generation API

The simplest way to generate a barcode is through the per-symbology helper functions:

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

Each helper returns a Barcode object. Call to_svg() for SVG output or to_png() for PNG output.

The generic generate() function accepts a symbology name string:

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

Valid symbology names: "code128", "code39", "ean13", "ean8", "qr", "upca", "upce".

BarcodeService

BarcodeService coordinates the three pipeline stages. It holds a SymbologyRegistry and an 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")

The generate() method:

Looks up the SymbologyDefinition from the registry
Calls the InputParser.parse() to validate and normalize input
Calls the SymbologyEncoder.encode() to produce an EncodedSymbol
Returns a Barcode wrapping the symbol and its profile

SymbologyRegistry

SymbologyRegistry stores SymbologyDefinition objects keyed by canonical names and aliases:

Method	Description
`get_definition(name)`	Retrieve a complete symbology definition
`get_parser(name)`	Get the `InputParser` for a symbology
`get_encoder(name)`	Get the `SymbologyEncoder` for a symbology
`get_profile(name)`	Get the `SymbologyProfile` with defaults
`get_text_policy(name)`	Get the `TextLayoutPolicy` for text rendering
`register(definition)`	Register a new `SymbologyDefinition`

EncoderRegistry is a backward-compatible alias for SymbologyRegistry.

SymbologyDefinition

A SymbologyDefinition bundles all components needed to support one symbology:

Property	Type	Description
`name`	`str`	Canonical symbology identifier
`parser`	`InputParser`	Validates and normalizes input data
`encoder`	`SymbologyEncoder`	Encodes data into a module matrix
`profile`	`SymbologyProfile`	Defaults, capabilities, and text policy
`aliases`	`tuple[str, ...]`	Alternative names for lookup

EncodedSymbol

The EncodedSymbol returned by an encoder contains:

matrix — a ModuleMatrix with the barcode’s logical module grid
metadata — a SymbolMetadata with symbology name, display text, and encoding details

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 provides a get(x, y) method that returns the module value at a given position.

NormalizedPayload

The NormalizedPayload is the intermediate representation between parsing and encoding:

Property	Description
`symbology`	Canonical symbology name
`data`	Validated input data (`str` or `bytes`)
`input_kind`	How the input was classified
`code128_encode_mode`	Resolved Code 128 mode (if applicable)
`code39_encode_mode`	Resolved Code 39 mode (if applicable)
`qr_error_correction_level`	Resolved QR error correction (if applicable)
`qr_version`	Resolved QR version (if applicable)
`qr_encoding_mode`	Resolved QR encoding mode (if applicable)

OptionsResolver

OptionsResolver merges user-supplied render options with symbology defaults:

Method	Description
`resolve(profile, options)`	Produce a `ResolvedRenderOptions` by merging user options with profile defaults
`merge_options(earlier, later)`	Merge two `RenderOptions` (later values override)
`coerce_options(options)`	Normalize raw options into `RenderOptions`

Tips and Best Practices

Use per-symbology helpers (code128(), qr(), etc.) instead of generate() for type safety — they ensure the correct options class is used.
The Barcode.symbol property gives direct access to the EncodedSymbol for custom rendering or analysis.
BarcodeService is stateless — one instance can generate barcodes across multiple threads.
Catch BarcodeError as a base class to handle all barcode-related exceptions in a single block.

Common Issues

Issue	Cause	Fix
`SymbologyNotFoundError`	Name not registered in `SymbologyRegistry`	Check spelling; use canonical names
`InvalidInputError`	Data violates symbology requirements	Check character set and length requirements
Empty SVG output	No modules encoded	Verify data is non-empty and valid for the symbology

Barcode Generation