TraceFileReader

class osi_utilities.tracefile.reader.TraceFileReader

Bases: ABC

Abstract base class for reading OSI trace files.

Supports context manager protocol and iteration.

Usage:

with TraceFileReaderFactory.create_reader("trace.mcap") as reader:
    for result in reader:
        print(result.message_type, result.message)

abstractmethod open(path)

Open a trace file for reading.

Parameters:

path (Path) – Path to the trace file.

Returns:

True if the file was opened successfully, False otherwise.

Return type:

bool

abstractmethod read_message()

Read the next message from the trace file.

Returns:

A ReadResult containing the deserialized message, or None if no more messages.

Raises:

RuntimeError – If deserialization fails.

Return type:

ReadResult | None

abstractmethod has_next()

Check if there are more messages to read.

Return type:

bool

abstractmethod close()

Close the trace file and release resources.

Return type:

None

class osi_utilities.tracefile.reader.TraceFileReaderFactory

Bases: object

Factory for creating trace file readers based on file extension.

static create_reader(path, *, message_type=None)

Create a trace file reader appropriate for the given file.

Parameters:

• path (str | Path) – Path to the trace file. Extension determines the reader type.

• message_type (MessageType | None) – Explicit message type for binary/txth files. If provided, overrides filename-based inference. Ignored for MCAP files (which store the schema in the file itself).

Returns:

An opened TraceFileReader instance.

Raises:

• ValueError – If the file extension is not supported.

• RuntimeError – If the file cannot be opened.

Return type:

TraceFileReader

osi_utilities.tracefile.reader.open_trace_file(path, *, message_type=None)

Convenience function to open a trace file for reading.

Equivalent to TraceFileReaderFactory.create_reader(path).

Parameters:

• path (str | Path) – Path to the trace file.

• message_type (MessageType | None) – Explicit message type for binary/txth files.

Returns:

An opened TraceFileReader instance (use as context manager).

Return type:

TraceFileReader