openpectus.lang.exec.runlog

Attributes

logger

Classes

RuntimeInfo

Provides a log of the actions that take place during interpretation.

RuntimeRecord

RuntimeRecordState

RuntimeRecordStateEnum

Defines the states runtime records can take

RunLog

RunLogItem

RunLogItemState

Defines the states that commands in the run log can take

Functions

assert_Runlog_HasItem(runtimeinfo, name)

assert_Runlog_HasNoItem(runtimeinfo, name)

assert_Runlog_HasItem_Started(runtimeinfo, name)

assert_Runlog_HasItem_Completed(runtimeinfo, name[, ...])

assert_Runtime_HasRecord(runtimeinfo, name)

assert_Runtime_HasRecord_Started(runtimeinfo, name)

assert_Runtime_HasRecord_Completed(runtimeinfo, name)

Module Contents

openpectus.lang.exec.runlog.logger
class openpectus.lang.exec.runlog.RuntimeInfo

Provides a log of the actions that take place during interpretation.

It consists of a list of records. Each record has a name and a list of states. The record state contain a state name, time and the tag values at the time the state was created.

As interpretation progresses, the program AST nodes (subclasses of p.Node) are visited and their semantics are executed. The records added are:

  • For all visited nodes, a record is added. The name of the record is provided by p.Node.runlog_name if overwritten by the particular subclass. When a record is created, its exec_id is given a random UUID.

  • Instructions that are interpreted via an interrupt, reuse the record that was created when the node was first visited.

    Alarms too?

  • Engine commands are currently not contained in records.

  • Uod commands are executed via context.schedule_execution(). The interpreter does not know what happens after that. The engine updates the record as these commands are executed, cancelled etc. The record states are provided with the command instance as well as a command_exec_id that tracks a particular command instance. This means that one record may hold states for different invocations (and instances) of the same command.

__str__()
Return type:

str

_records: list[RuntimeRecord] = []
_record_index: Dict[uuid.UUID, int]
property records: list[RuntimeRecord]
Return type:

list[RuntimeRecord]

get_runlog()

Transmogrify the runtime records into the RunLog shape that clients understand.

Notably, it removes records with no name and unscrambles uod states such that each invocation gets its own runlog item. This allows the client to force or cancel a particular command instance.

Return type:

RunLog

_get_runlog_id()
Return type:

str | None

_get_record_runlog_items(r)
Parameters:

r (RuntimeRecord)

Return type:

list[RunLogItem]

_split_states(r, include_prestart_states)

Split a record’s states into those of distint invocations.

Parameters:
Return type:

list[list[RuntimeRecordState]]

_split_states_by_state_name(states, state_name, include_prestart_states)
Parameters:
Return type:

list[list[RuntimeRecordState]]

_check_record_states_ordered(states)
Parameters:

states (list[RuntimeRecordState])

_update_item_progress(item, source)
Parameters:
get_exec_record(exec_id)

Return record for the given exec_id or None if not found.

Parameters:

exec_id (uuid.UUID)

Return type:

RuntimeRecord | None

get_command_and_record(command_exec_id)

Return (command, record) pair for the given command_exec_id or None if (both) not found.

Parameters:

command_exec_id (uuid.UUID)

Return type:

tuple[openpectus.engine.commands.EngineCommand, RuntimeRecord] | None

get_last_node_record_or_none(node)

Get last record by node id

Parameters:

node (openpectus.lang.model.ast.Node)

Return type:

RuntimeRecord | None

get_last_node_record(node)

Get last record by node id. Raise if no record is found

Parameters:

node (openpectus.lang.model.ast.Node)

Return type:

RuntimeRecord

get_node_records(node, test_by_instance=False)

Get the records that references the node.

If test_by_instance is False (the default) references are tested by node id, otherwise references are tested by object reference. This is relevant when a method is edited while it runs, where nodes are replaced with new instances and these new instances must also be propagated to record node references.

Parameters:

node (openpectus.lang.model.ast.Node)

Return type:

list[RuntimeRecord]

_add_record(record, exec_id)
Parameters:
begin_visit(node, time, tick, start_values)
Parameters:
Return type:

RuntimeRecord

find_instruction(instruction_name, arguments, start_index, instruction_state)

Find the first record with the given instruction name and state starting from start_index (incl).

Return the index of the found record or None if record is not found.

Use get_record_by_index to obtain the record of the index.

Parameters:

  • instruction_name (str)

  • arguments (str | None)

  • start_index (int)

  • instruction_state (RuntimeRecordStateEnum | None)

Return type:

int | None

get_record_by_index(index)
Parameters:

index (int)

Return type:

RuntimeRecord | None

get_as_table(description='')
Parameters:

description (str)

Return type:

str

print_as_table(description='')
Parameters:

description (str)

with_edited_program(program)

Return a deep copy with node references set to nodes in program. Does not modify any existing records.

Note: Uses RuntimeRecordState.clone() which does not change command and command_exec_id.

Parameters:

program (openpectus.lang.model.ast.ProgramNode)

Return type:

RuntimeInfo

class openpectus.lang.exec.runlog.RuntimeRecord(node, exec_id)
Parameters:
exec_id: uuid.UUID
node
name
visit_start_time: float = -1.0
visit_start_tick: int = -1
visit_end_time: float = -1.0
visit_end_tick: int = -1
states: list[RuntimeRecordState] = []
start_values: openpectus.lang.exec.tags.TagValueCollection | None = None
end_values: openpectus.lang.exec.tags.TagValueCollection | None = None
progress: float | None = None

Used for progress for interpreter commands that don’t have an command instance

__str__()
Return type:

str

static null_record()
Return type:

RuntimeRecord

__repr__()
Return type:

str

has_state(state)
Parameters:

state (RuntimeRecordStateEnum)

Return type:

bool

get_state(state, first=True)
Parameters:

state (RuntimeRecordStateEnum)

Return type:

RuntimeRecordState

add_state(state, time, tick, state_values)
Parameters:
Return type:

RuntimeRecordState

add_state_awaiting_threshold(time, tick, state_values)
Parameters:
add_state_awaiting_condition(time, tick, state_values)
Parameters:
add_state_started(time, tick, start_values)
Parameters:
add_state_completed(time, tick, end_values)
Parameters:
add_state_failed(time, tick, end_values)
Parameters:
add_state_cancelled(time, tick, state_values)
Parameters:
add_state_forced(time, tick, state_values)
Parameters:
set_end_visit(time, tick, end_values)
Parameters:
add_state_uod_command_set(uod_command, time, tick, state_values)
Parameters:
Return type:

uuid.UUID

add_state_internal_engine_command_set(command, time, tick, state_values)
Parameters:
Return type:

uuid.UUID

add_command_state_cancelled(command_exec_id, time, tick, end_values)
Parameters:
add_command_state_started(command_exec_id, time, tick, end_values)
Parameters:
add_command_state_completed(command_exec_id, time, tick, end_values)
Parameters:
add_command_state_failed(command_exec_id, time, tick, end_values)
Parameters:
clone()
Return type:

RuntimeRecord

with_edited_node(program)

Clones the record, updates the node to the matching node in the new program and returns the clone

Parameters:

program (openpectus.lang.model.ast.ProgramNode)

Return type:

RuntimeRecord

class openpectus.lang.exec.runlog.RuntimeRecordState(state, time, tick, values)
Parameters:
state_name: RuntimeRecordStateEnum
state_time: float
state_tick: int
values: openpectus.lang.exec.tags.TagValueCollection | None
command: openpectus.engine.commands.EngineCommand | None = None
command_exec_id: uuid.UUID | None = None
__str__()
Return type:

str

__repr__()
clone()

Note: command and command_exec_id are copied from existing state. These reference command objects outside or RuntimeInfo.

Return type:

RuntimeRecordState

class openpectus.lang.exec.runlog.RuntimeRecordStateEnum

Bases: enum.StrEnum

Defines the states runtime records can take

Visited

Instruction node was visited

UodCommandSet

Uod command was set

InternalEngineCommandSet

Internal engine command was set

AwaitingThreshold

Waiting for threshold

AwaitingCondition

Waiting for condition

Started

Command has started

Cancelled

Command was cancelled. Either by overlapping command or explicitly by user

Forced

Waiting command was forcibly started by user

Completed

Command has completed

Failed

Command has failed

static has_value(value)

Determine if enum has this string value defined. Case sensitive.

Parameters:

value (str)

class openpectus.lang.exec.runlog.RunLog
id: str = ''
items: list[RunLogItem] = []
__str__()
Return type:

str

size()
Return type:

int

class openpectus.lang.exec.runlog.RunLogItem
id: str = ''

Exec_id of the command

name: str = ''
start: float = 0
end: float | None = None
state: RunLogItemState
progress: float | None = None
start_values: openpectus.lang.exec.tags.TagValueCollection
end_values: openpectus.lang.exec.tags.TagValueCollection
forcible: bool = False
forced: bool = False
cancellable: bool = False
cancelled: bool = False
__str__()
Return type:

str

class openpectus.lang.exec.runlog.RunLogItemState

Bases: enum.StrEnum

Defines the states that commands in the run log can take

Unknown

State unknown. Items in this state are not rendered.

AwaitingThreshold

Waiting for threshold. Items in this state are not rendered

Started

Command has started

Cancelled

Command was cancelled. Either by overlapping command or explicitly by user

Forced

Waiting command was forcibly started by user

Completed

Command has completed

Failed

Command failed

static has_value(value)

Determine if enum has this string value defined. Case sensitive.

Parameters:

value (str)

openpectus.lang.exec.runlog.assert_Runlog_HasItem(runtimeinfo, name)
Parameters:
openpectus.lang.exec.runlog.assert_Runlog_HasNoItem(runtimeinfo, name)
Parameters:
openpectus.lang.exec.runlog.assert_Runlog_HasItem_Started(runtimeinfo, name)
Parameters:
openpectus.lang.exec.runlog.assert_Runlog_HasItem_Completed(runtimeinfo, name, min_times=1)
Parameters:
openpectus.lang.exec.runlog.assert_Runtime_HasRecord(runtimeinfo, name)
Parameters:
openpectus.lang.exec.runlog.assert_Runtime_HasRecord_Started(runtimeinfo, name)
Parameters:
openpectus.lang.exec.runlog.assert_Runtime_HasRecord_Completed(runtimeinfo, name)
Parameters: