Source code for osprey_connectors.simulation.status
"""A served physics model's status, read from a connector.
:func:`model_status` answers from the composite a connector serves in process.
:func:`read_model_status` reads a model's status channel through any
connector, the way a target served by a separate process reports it.
:data:`STATUS_OK` and :data:`STATUS_NO_DECK` are the two texts that are not
an error; :func:`is_error` is the one test of that. The module imports nothing beyond
the standard library, so a status lookup loads no model: the composite is
reached through the connector when asked.
"""
from __future__ import annotations
from typing import Any, Protocol, runtime_checkable
__all__ = [
"STATUS_NO_DECK",
"STATUS_OK",
"is_error",
"model_status",
"read_model_status",
]
#: A physics model's status while its engine serves it.
STATUS_OK = "ok"
#: The status of a model that names no deck and wires no channel. Nothing is
#: built for it, by design: the facility describes the machine, and every
#: channel of it is the texture's.
STATUS_NO_DECK = "no deck"
_COMPOSITE_ATTRIBUTE = "_composite"
@runtime_checkable
class _StatusSource(Protocol):
"""What a status lookup reads: the composite a connector serves in process."""
def status(self, model: str) -> str: ...
[docs]
def is_error(status: str) -> bool:
"""Whether a model's status text is an error.
Args:
status: A model's status, as :func:`model_status` or
:func:`read_model_status` returns it.
Returns:
False for :data:`STATUS_OK` and :data:`STATUS_NO_DECK`, a model built
on purpose from nothing; True for any other text, which is the error
the model failed with.
"""
return status not in (STATUS_OK, STATUS_NO_DECK)
[docs]
def model_status(connector: object, model: str) -> str:
"""A served physics model's status: ``ok`` or its engine's error text.
Args:
connector: A connected control system connector serving a composite
in process.
model: The name of a served physics model.
Returns:
``ok`` while the model's engine serves it, ``no deck`` for a model
built on purpose from nothing; otherwise the engine's error text,
capped by the composite.
Raises:
ValueError: ``model`` is not a served physics model, the message naming
the served ones; or the connector serves no composite in process.
"""
composite: object = getattr(connector, _COMPOSITE_ATTRIBUTE, None)
if not isinstance(composite, _StatusSource):
raise ValueError(f"{type(connector).__name__} serves no simulator in process")
return composite.status(model)
[docs]
async def read_model_status(connector: Any, address: str) -> str:
"""A served physics model's status, read from its status channel.
Args:
connector: A connected control system connector.
address: The model's status address, ``<code>:SIM:<model>:STATUS``.
Returns:
The text the channel holds: ``ok`` or the model's error text.
"""
from osprey_connectors.simulation import decode_char_waveform
reading = await connector.read_channel(address)
return decode_char_waveform(reading.value)