Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nokia/moler/llms.txt

Use this file to discover all available pages before exploring further.

An Event in Moler is a ConnectionObserver that runs continuously in the background, scanning connection output for a specific pattern. Unlike a Command, an event never writes anything to the connection — it only observes. This makes events ideal for catching asynchronous, unsolicited output: device reboots, alarm messages, prompt changes, or any other condition that can appear at any time.

​
How events differ from commands

CommandEvent
Sends data to connection?YesNo (passive)
LifecycleShort-lived: start → parse output → doneLong-lived: start → keep watching → cancel
Default timeoutSet by caller~100 years (effectively infinite)
ResultSingle structured dict/listList of all occurrences seen
Primary APIstart() / () / await_done()start() / callback / cancel()

​
Event lifecycle

Events are started explicitly with start() and run until they are cancelled, or until they have matched till_occurs_times times (if set). 
event = my_device.get_event(
    event_name="wait4prompt",
    event_params={"prompt": r"^myhost:.*#"},
)
event.start()       # begin watching
# ... do other work ...
event.cancel()      # stop watching
Events have a default timeout of approximately 100 years. They are designed to run for the duration of a test, not to expire on their own.

​
Reacting with callbacks

The primary way to use events is to register a callback via add_event_occurred_callback(). Every time the event’s pattern matches a line on the connection, the callback is called. 
from moler.device import DeviceFactory

def on_prompt_seen(occurrence):
    print("Prompt appeared:", occurrence)

my_unix = DeviceFactory.get_device(name='MyMachine')
prompt_event = my_unix.get_event(
    event_name="wait4prompt",
    event_params={"prompt": r"^moler_bash#"},
)
prompt_event.add_event_occurred_callback(
    callback=on_prompt_seen,
    callback_params={"occurrence": prompt_event.get_last_occurrence},
)
prompt_event.start()
Only one callback may be registered at a time. To remove it: 
prompt_event.remove_event_occurred_callback()

​
The Wait4prompt event

Wait4prompt (moler.events.unix.wait4prompt) is the most commonly used built-in event. Devices use it internally to detect state transitions by watching for shell prompts. It extends the generic Wait4 event with a single prompt regex parameter. 
from moler.events.unix.wait4prompt import Wait4prompt

# Detect a prompt exactly once, then stop
prompt_event = Wait4prompt(
    connection=terminal.moler_connection,
    prompt=r'host:.*#',
    till_occurs_times=1,
)
prompt_event.start()
result = prompt_event.await_done(timeout=30)
# result is a list of occurrence dicts:
# [{'line': 'host:~ #', 'groups': (), 'named_groups': {}, 'matched': 'host:~ #', 'time': datetime(...)}]
Each element in the result list is a dict with these keys:
KeyDescription
lineThe full line that matched
matchedThe substring that matched the pattern
groupsTuple of captured groups from the regex
named_groupsDict of named captured groups
timedatetime of the match

​
Limiting occurrences with till_occurs_times

Pass till_occurs_times=N to make the event finish automatically after it has matched N times. Once it has seen that many matches, it calls set_result() with the list of all occurrences and marks itself done — just like a command. 
# Stop after 3 matches
alarm_event = my_device.get_event(
    event_name="wait4prompt",
    event_params={"prompt": r"ALARM", "till_occurs_times": 3},
)
alarm_event.start()
result = alarm_event.await_done(timeout=60)  # blocks until 3 alarms seen
With the default till_occurs_times=-1 the event runs indefinitely; you must cancel it explicitly.

​
Pause and resume

All events implement pause() and resume(). Devices call these internally during state transitions (when pause_prompts_event_on_state_change is enabled) to avoid spurious prompt matches while a transition command is running. 
prompt_event.pause()   # stop processing incoming data
# ... sensitive section ...
prompt_event.resume()  # resume processing

​
Retrieving occurrences

At any point you can inspect what the event has seen so far: 
# Last single occurrence
last = prompt_event.get_last_occurrence()

# All occurrences (only available after break_event / cancel)
all_occurrences = prompt_event.result()

​
Logging

Each occurrence is logged at INFO level by default. Call disable_log_occurrence() to suppress this if the event fires very frequently. 
frequent_event.disable_log_occurrence()
frequent_event.start()

Commands

Active observers that send data and parse output

Devices

State machines that manufacture events for the current state

Build docs developers (and LLMs) love

Get started for freeTalk to us