TraceReader

class osi_utilities.tracefile.readers.base.TraceReader[source]

Bases: ABC

Abstract base class for reading OSI trace files.

Supports context manager protocol and iteration.

Read contract:

  • read_message() returns None on EOF.

  • read_message() returns ReadResult(status=ReadStatus.OK, ...) for valid messages.

  • read_message() returns ReadResult(status=ReadStatus.INCOMPATIBLE, ...) for incompatible schema/encoding/message-type cases.

  • read_message() returns ReadResult(status=ReadStatus.ERROR, ...) for actual runtime read/decode/parse failures.

Iterator contract (for ... in reader):

  • raises ValueError for ReadStatus.INCOMPATIBLE

  • raises RuntimeError for ReadStatus.ERROR

abstractmethod open(path)[source]

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()[source]

Read the next message from the trace file.

Returns:

A ReadResult for message/status outcomes, or None if no more messages.

Return type:

ReadResult | None

abstractmethod has_next()[source]

Check if there are more messages to read.

Return type:

bool

abstractmethod close()[source]

Close the trace file and release resources.

Return type:

None

osi_utilities.tracefile.configure.create_reader(path)[source]

Create a trace file reader appropriate for the given file.

Parameters:

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

Returns:

An unopened TraceReader instance.

Raises:

ValueError – If the file extension is not supported.

Return type:

TraceReader