Pkg Python API

Extract tracing tags and activities from .pkg and .ta files generated by ecu.test and write them to a LOBSTER interchange file.

API

from lobster.tools.pkg.pkg import lobster_pkg
lobster_pkg(config: PkgToolConfig)

First, prepare a configuration:

Configuration Dataclass

from lobster.tools.pkg.pkg import PkgToolConfig, lobster_pkg
from pathlib import Path

config = PkgToolConfig(
      files=[Path("tests/pkg/"), Path("specific_test.pkg")],
      out=Path("pkg.lobster"),   # optional; defaults to "pkg.lobster"
)

PkgToolConfig fields (dataclass):

  • files: Sequence[Path] - List of .pkg / .ta files or directories to process. Directories are scanned recursively for matching extensions.

  • out: Optional[Path] - Destination .lobster file. If None, output is written to pkg.lobster in the current directory.

Stable API Function

lobster_pkg(config: PkgToolConfig) -> None

Runs end-to-end: scan input files, parse tracing tags from XML content, write LOBSTER output.

Example (Scanning a Directory)

from lobster.tools.pkg.pkg import PkgToolConfig, lobster_pkg
from pathlib import Path

lobster_pkg(PkgToolConfig(
   files=[Path("tests/pkg/"), Path("tests/ta/")],
   out=Path("tracing.lobster"),
))

Behavioral Notes

  • Only packages with a TESTCASE tag in INFORMATION/TAGS are processed; others are silently skipped.

  • In .pkg files, lobster-trace: values are read from VALUE elements inside TsBlock TESTSTEP nodes at the first or second nesting level under TESTSTEPS. Tags placed deeper are treated as misplaced and raise a LOBSTER_Exception.

  • In .ta files, lobster-trace: values are read from DESCRIPTION elements that are direct children of top-level episode ANALYSISITEM nodes inside TRACE-ANALYSIS. Tags found at deeper levels emit a warning but do not stop processing.

  • Multiple requirements can be listed in a single trace tag using comma separation (e.g. lobster-trace: REQ-001, REQ-002).

  • XML parse errors raise xml.etree.ElementTree.ParseError.

Core Goals

  • Parse .pkg and .ta files from ecu.test and convert them to LOBSTER activities.

  • Support both standard TsBlock-based tracing and TRACE-ANALYSIS episode tracing.

  • Produce a single .lobster artifact for use by downstream LOBSTER tools.

Error Conditions

  • No input files found after scan → ValueError.

  • Misplaced lobster-trace tag in a .pkg file → LOBSTER_Exception.

  • Malformed XML → xml.etree.ElementTree.ParseError.