monitor module#

Callbacks on changes to a runtime design’s layout.

Reached through RuntimeDesign.layout.monitor. Changes are reported however they were made: by requests, in the UI, or by other clients. User events, subclasses of UserEvent, are application-defined events sent with RuntimeDesign.layout.emit or by other clients (such as UI hooks).

type JSON = str | int | float | bool | None | list[JSON] | dict[str, JSON]#: A JSON-compatible value.

class UserEvent(data=None, objects=())[source]#

Bases: object

Base for application-defined layout events.

Subclass it to define a kind of event; the subclass’s fully qualified name identifies the kind on the wire, so events of different applications do not collide. An event carries JSON-compatible data and a sequence of layout objects (components, ports, routes, vias, …), which data may refer to by index. A subclass may parse both into its own fields, and may override the data and objects properties, which are what is sent.

A received event is constructed as cls(data, objects), so a subclass must accept those two arguments positionally, and call this __init__.

>>> class Highlight(UserEvent):
...     def __init__(self, data: Mapping[str, JSON], objects: Sequence[object | None]):
...         super().__init__(data, objects)
...         self.color = data["color"]
>>> await design.layout.emit(Highlight({"color": "red"}, [c.u1]))

Parameters:

data (Mapping[str, JSON] | None) – JSON-compatible values. Numbers that are whole are received as int, so they can index objects.
objects (Sequence[object | None]) – Layout objects. A received object the design does not have is None; see resolved.

property data: Mapping[str, JSON]#: The event’s JSON-compatible values.

property objects: Sequence[object | None]#: The event’s layout objects.

property resolved: bool#: Whether every object of a received event was found in the design. Objects not found are None in objects.

class Changes[T](added=(), changed=(), removed=())[source]#

Bases: Generic[T]

Objects of one kind added, changed, or removed by one change to the layout. Removed objects are no longer in the design tree. An object the runtime replaces when it changes (a via, a control point, an area region’s feature) is reported as removed, and its replacement as added.

Parameters:

added (Sequence)
changed (Sequence)
removed (Sequence)

added: Sequence[T] = ()#

changed: Sequence[T] = ()#

removed: Sequence[T] = ()#

class Monitor(remove)[source]#

Bases: object

A registered callback. Unregister it with close(), or by using it as a context manager.

>>> with design.layout.monitor.placements(moved):
...     ...

Parameters:: remove (Callable[[], None])

close()[source]#

Unregister the callback. Calling it again is a no-op.

Return type:: None

class LayoutMonitor(monitors)[source]#

Bases: object

Registers callbacks run on changes to a runtime design’s layout.

Callbacks run on the runtime’s event loop as changes arrive, after the whole change has been applied to design.root, and receive objects of the current tree (a capture replaces it). A callback returning an awaitable has it run as a task. A callback must not block: blocking calls on a sync design (requests, capture) raise when made from one. Exceptions raised by a callback are logged.

Parameters:: monitors (_Monitors)

placements(callback)[source]#

Run callback with the instances whose placement changed.

Each moved instance is reported, including those anchored to a moved one; circuits are reported when they move as a whole.

Return type:: Monitor
Returns:: The registration; close it to stop.
Parameters:: callback (Callable[[Sequence[Component | Circuit]], object])

routes(callback)[source]#

Run callback with the routes the runtime made, rerouted (routed or blocked), or removed.

Return type:: Monitor
Returns:: The registration; close it to stop.
Parameters:: callback (Callable[[Changes[Route]], object])

vias(callback)[source]#

Run callback with the vias the runtime added, moved, or removed. A via placed in code is not reported.

Return type:: Monitor
Returns:: The registration; close it to stop.
Parameters:: callback (Callable[[Changes[Via]], object])

controls(callback)[source]#

Run callback with the control points the runtime added, changed, or removed. A control point placed in code is not reported.

Return type:: Monitor
Returns:: The registration; close it to stop.
Parameters:: callback (Callable[[Changes[ControlPoint]], object])

regions(callback)[source]#

Run callback with the area regions the runtime added, changed, or removed: a feature per region, and for a copper pour region a Pour per layer (changed when its rank changes; see pours() for its copper).

Return type:: Monitor
Returns:: The registration; close it to stop.
Parameters:: callback (Callable[[Changes[Feature | Pour]], object])

pours(callback)[source]#

Run callback with the pours whose copper the runtime computed (changed, or added for a pour the design did not have), or removed. A pour removed with its area region is reported by regions().

Return type:: Monitor
Returns:: The registration; close it to stop.
Parameters:: callback (Callable[[Changes[Pour]], object])

user[E: UserEvent](event, callback)[source]#

Run callback with each received user event of type event.

Parameters:

event (type[E]) – The event class. Only events sent as exactly this class are received.
callback (Callable[[E], object]) – Receives the event, constructed as event(data, objects).

Return type:

Monitor

Returns:

The registration; close it to stop.

user_event_name(event)[source]#

The wire name of a user event class.

Return type:: str
Parameters:: event (type[UserEvent])

user_event_proto(event, rmap)[source]#

The wire form of event.

Raises:

TypeError – if data is not JSON-compatible.
ValueError – if an object has no runtime ID.

Return type:

UserEvent

Parameters:

event (UserEvent)
rmap (ReverseMapper)