Configuration#

pyA2L works out-of-the-box with sensible defaults. This section describes all available knobs for tuning import, export, and runtime behaviour.

Import options#

import_a2l() (and DB.import_a2l()) accept these parameters:

Parameter	Default	Description
`file_name`	(required)	Path to the `.a2l` file.
`encoding`	`"latin-1"`	Character encoding of the A2L source. Common alternatives: `"utf-8"`, `"ascii"`, `"iso-8859-1"`. Use `chardetect file.a2l` on the command line to auto-detect.
`in_memory`	`False`	If `True`, the SQLite database is created in RAM (no `.a2ldb` file on disk). Faster, but the data is lost when the session closes.
`remove_existing`	`False`	If `True`, an existing `.a2ldb` file with the same name is deleted before importing.
`local`	`False`	If `True`, the `.a2ldb` is created in the current working directory instead of next to the source file.
`loglevel`	`"INFO"`	Python logging level. Set to `"ERROR"` or `"WARNING"` to suppress progress messages; `"DEBUG"` for verbose output.
`progress_bar`	`True`	Show a Rich progress bar during import. Disable with `False` for batch/CI usage.
`debug`	`False`	Enable parser-level debug output.

Example:

from pya2l import DB

session = DB().import_a2l(
    "my_ecu.a2l",
    encoding="utf-8",
    local=True,
    progress_bar=False,
    loglevel="WARNING",
)

Export options#

export_a2l() parameters:

Parameter	Default	Description
`db_name`	(required)	Path to the `.a2ldb` database (extension implied if omitted).
`output`	`sys.stdout`	Output file path (string) or a writable file-like object.
`encoding`	`"latin1"`	Encoding for the output A2L text file.

Example:

from pya2l import export_a2l

# Export to file
export_a2l("my_ecu", "exported.a2l")

# Export to stdout
export_a2l("my_ecu")

Environment variables#

Variable	Description
`ASAP_INCLUDE`	Platform-style separated list of directories used for resolving `/INCLUDE` file references in A2L files. Works like `PATH` on your operating system.

Example (Windows):

set ASAP_INCLUDE=C:\a2l\includes;D:\shared\a2l_libs
a2ldb-imex -i my_ecu.a2l

Example (Linux/macOS):

export ASAP_INCLUDE=/opt/a2l/includes:/shared/a2l_libs
a2ldb-imex -i my_ecu.a2l

CLI options (a2ldb-imex)#

The a2ldb-imex console script provides quick command-line access:

a2ldb-imex -h            # show help
a2ldb-imex -V            # show version

# Import
a2ldb-imex -i file.a2l              # import (creates .a2ldb next to file)
a2ldb-imex -i file.a2l -L           # create .a2ldb in current directory
a2ldb-imex -i file.a2l -E utf-8     # specify encoding
a2ldb-imex -i file.a2l -p           # silence progress bar

# Export
a2ldb-imex -e file.a2ldb -o out.a2l # export to file
a2ldb-imex -e file.a2ldb            # export to stdout

# JSON export
a2ldb-imex -e file.a2ldb --json -o out.json       # export as JSON
a2ldb-imex -e file.a2ldb --json --pretty -o out.json  # pretty-printed JSON
a2ldb-imex -e file.a2ldb --json                    # JSON to stdout

Database pragmas#

pyA2L configures SQLite for optimal performance. These settings are applied automatically and normally do not need to be changed:

Pragma	Effect
`journal_mode=WAL`	Write-Ahead Logging — allows concurrent readers during writes
`FOREIGN_KEYS=ON`	Enforce foreign key constraints
`SYNCHRONOUS=OFF`	Faster writes (safe with WAL mode)
`busy_timeout=5000`	Wait up to 5 seconds when the database is locked

Logging#

pyA2L uses Python’s logging module. The main loggers are:

pya2l — general library messages
pya2l.ifdata — IF_DATA parsing diagnostics

Adjust verbosity:

import logging
logging.getLogger("pya2l").setLevel(logging.DEBUG)
logging.getLogger("pya2l.ifdata").setLevel(logging.WARNING)