pyobs-core 2.0.0.dev17__tar.gz → 2.0.0.dev19__tar.gz

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyobs-core
-Version: 2.0.0.dev17
+Version: 2.0.0.dev19
 Summary: robotic telescope software
 Author-email: Tim-Oliver Husser <thusser@uni-goettingen.de>
 License-Expression: MIT

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/cli/pyobsd.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 import glob
 import json
 import logging
@@ -49,9 +50,9 @@ class PyobsDaemonCLI(CLI):
         )
         self._parser.add_argument(
             "--syslog",
-            action="store_true",
-            help="send module logs to systemd journal",
-            default=self._config.get("syslog", False),
+            action=argparse.BooleanOptionalAction,
+            help="send module logs to systemd journal (use --no-syslog to disable)",
+            default=self._config.get("syslog", True),
         )
         self._parser.add_argument("--chuid", type=str, default=self._config.get("chuid", "pyobs:pyobs"))
         self._parser.add_argument("-v", "--verbose", action="store_true")
@@ -63,6 +64,9 @@ class PyobsDaemonCLI(CLI):
         sp.add_parser("restart", help="restart modules").add_argument("modules", type=str, nargs="*")
         sp.add_parser("status", help="status of modules").add_argument("--json", action="store_true")
         sp.add_parser("list", help="list of modules")
+        sp.add_parser("logs", help="show/follow module logs via journalctl").add_argument(
+            "args", nargs=argparse.REMAINDER, help="[module] [journalctl arguments...]"
+        )
 
     def run(self) -> None:
         # init daemon
@@ -87,7 +91,9 @@ class PyobsDaemonCLI(CLI):
             case "status":
                 daemon.status(print_json=self._config["json"])
             case "list":
-                daemon.list()
+                daemon.list_modules()
+            case "logs":
+                daemon.logs(self._config["args"])
 
 
 class PyobsDaemon:
@@ -289,9 +295,24 @@ class PyobsDaemon:
                 else:
                     print(f"{module:<30}  {'stopped':<8}")
 
-    def list(self) -> None:
+    def list_modules(self) -> None:
         print("\n".join(self._list_configs()))
 
+    def logs(self, args: list[str]) -> None:
+        """Show/follow module logs by exec'ing into journalctl."""
+        match_args = ["SYSLOG_IDENTIFIER=pyobs"]
+        remainder = list(args)
+        # "--" may have been auto-inserted by main() to work around argparse.REMAINDER
+        # refusing to swallow a leading flag (e.g. "pyobsd logs -f") — drop it here.
+        if remainder and remainder[0] == "--":
+            remainder.pop(0)
+        if remainder and remainder[0] in self._list_configs():
+            match_args.append(f"PYOBS_MODULE={remainder.pop(0)}")
+        cmd = ["journalctl", *match_args, *remainder]
+        if self._verbose:
+            print(f"[DEBUG] Executing: {' '.join(cmd)}")
+        os.execvp("journalctl", cmd)
+
     # ── process management ────────────────────────────────────────────────────
 
     def _start_service(self, module: str) -> None:
@@ -388,6 +409,14 @@ class PyobsDaemon:
 
 
 def main() -> None:
+    # argparse.REMAINDER can't swallow a leading flag (e.g. "pyobsd logs -f")
+    # unless a "--" already precedes it — insert one automatically so users
+    # don't need to type it themselves.
+    if "logs" in sys.argv:
+        idx = sys.argv.index("logs") + 1
+        if idx < len(sys.argv) and sys.argv[idx].startswith("-") and sys.argv[idx] != "--":
+            sys.argv.insert(idx, "--")
+
     cli = PyobsDaemonCLI()
     cli()
 

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/comm/comm.py

@@ -7,9 +7,9 @@ import logging
 from collections.abc import Callable, Coroutine
 from typing import TYPE_CHECKING, Any, overload
 
-import pyobs.interfaces
 from pyobs.events import Event, LogEvent, ModuleClosedEvent
 from pyobs.interfaces import Interface
+from pyobs.interfaces.interface import get_registered_interface
 from pyobs.utils.enums import ModuleState
 
 from .commlogging import CommLoggingHandler
@@ -337,28 +337,13 @@ class Comm:
             list of interface classes.
         """
 
-        # get interface classes
-        inspection = inspect.getmembers(pyobs.interfaces, predicate=inspect.isclass)
-
         # loop interfaces
         interface_classes = []
         for interface_name in interfaces:
-            # loop all classes
-            found = False
-            for cls_name, cls in inspection:
-                # class needs to face same name and implement Interface
-                if interface_name == cls_name and issubclass(cls, Interface):
-                    # found it!
-                    found = True
-
-                    # then add it to the list of all interfaces
-                    interface_classes.append(cls)
-
-                    # there can only be one...
-                    break
-
-            # not found?
-            if not found:
+            cls = get_registered_interface(interface_name)
+            if cls is not None:
+                interface_classes.append(cls)
+            else:
                 log.error('Could not find interface "%s" for client.', interface_name)
         return interface_classes
 
@@ -541,6 +526,13 @@ class Comm:
     def _get_own_state(self, interface: type[Interface]) -> Any:
         return None
 
+    def get_own_capabilities(self, interface: type[Interface]) -> Any:
+        """Return the capabilities published by this module for the given interface, or None."""
+        return self._get_own_capabilities(interface)
+
+    def _get_own_capabilities(self, interface: type[Interface]) -> Any:
+        return None
+
     async def subscribe_state(
         self,
         module: str,

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/comm/local/localcomm.py

@@ -117,6 +117,10 @@ class LocalComm(Comm):
         """Store capabilities locally."""
         self._capabilities[interface] = capabilities
 
+    def _get_own_capabilities(self, interface: type[Interface]) -> Any:
+        """Return this client's own published capabilities."""
+        return self._capabilities.get(interface)
+
     async def _get_capabilities(self, module: str, interface: type[Interface]) -> Any | None:
         """Fetch capabilities from a remote module."""
         if interface.capabilities is None:

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/comm/xmpp/serializer.py

@@ -32,6 +32,7 @@ import types as _builtin_types
 from enum import StrEnum
 from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints
 
+import numpy as np
 from slixmpp.xmlstream import ET
 
 from ...interfaces.interface import Interface as _Interface
@@ -65,6 +66,13 @@ def value_to_xml(value: Any, type_hint: Any) -> ET.Element:
     if get_origin(type_hint) is Annotated:
         type_hint = get_args(type_hint)[0]
 
+    # Normalize numpy scalars (np.float64, np.int64, np.bool_, ...) to native
+    # Python types. np.float64 subclasses float but repr()s as "np.float64(x)"
+    # since numpy 2.0, which corrupts <double> text; numpy integer types don't
+    # subclass int at all and would otherwise fall through to <string>.
+    if isinstance(value, np.generic):
+        value = value.item()
+
     # None / void
     if value is None:
         elem = ET.Element("nil")

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/comm/xmpp/xmppcomm.py

@@ -18,11 +18,11 @@ from slixmpp.xmlstream import ET
 from slixmpp.xmlstream.handler import Callback
 from slixmpp.xmlstream.matcher import MatchXMLMask
 
-import pyobs.interfaces
 from pyobs.comm import Comm
 from pyobs.events import Event, LogEvent, ModuleClosedEvent, ModuleOpenedEvent
 from pyobs.events.event import EventFactory
 from pyobs.interfaces import Interface
+from pyobs.interfaces.interface import get_registered_interface
 from pyobs.utils import exceptions as exc
 from pyobs.utils.enums import ModuleState
 
@@ -406,8 +406,8 @@ class XmppComm(Comm):
         interface_names = []
         for feature in features:
             name, _, version = feature[len(prefix) :].rpartition(":")
-            local_cls = getattr(pyobs.interfaces, name, None)
-            if local_cls is not None and issubclass(local_cls, Interface) and str(local_cls.version) == version:
+            local_cls = get_registered_interface(name)
+            if local_cls is not None and str(local_cls.version) == version:
                 interface_names.append(name)
 
         # IModule not in list?
@@ -896,6 +896,10 @@ class XmppComm(Comm):
         self._capabilities[interface] = capabilities
         log.info("Published capabilities for %s", interface.__name__)
 
+    def _get_own_capabilities(self, interface: type[Interface]) -> Any:
+        """Return this client's own published capabilities."""
+        return self._capabilities.get(interface)
+
     async def _get_capabilities(self, module: str, interface: type[Interface]) -> Any | None:
         """Fetch and deserialize capabilities for a remote module's interface."""
         if interface.capabilities is None:

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/interfaces/IModule.py

@@ -7,10 +7,19 @@ from typing import Any
 from .interface import Interface
 
 
+@dataclass
+class ModuleLocation:
+    longitude: float = 0.0
+    latitude: float = 0.0
+    elevation: float = 0.0
+    timezone: str = "utc"
+
+
 @dataclass
 class ModuleCapabilities:
     label: str = ""
     version: str = ""
+    location: ModuleLocation | None = None
 
 
 class IModule(Interface, metaclass=ABCMeta):
@@ -31,4 +40,4 @@ class IModule(Interface, metaclass=ABCMeta):
         ...
 
 
-__all__ = ["IModule", "ModuleCapabilities"]
+__all__ = ["IModule", "ModuleCapabilities", "ModuleLocation"]

pyobs_core-2.0.0.dev19/pyobs/interfaces/IPointingBody.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from typing import Any
+
+from .interface import Interface
+
+
+class IPointingBody(Interface, metaclass=ABCMeta):
+    """Points at and tracks a named solar-system body."""
+
+    __module__ = "pyobs.interfaces"
+
+    @abstractmethod
+    async def track_body(self, body: str, **kwargs: Any) -> None:
+        """Starts tracking a named solar-system body.
+
+        Args:
+            body: Name resolvable to an ephemeris (e.g. 'moon', 'mars', 'jupiter', or an
+                  asteroid/comet designation known to JPL Horizons).
+
+        Raises:
+            MoveError: If telescope could not be moved.
+            ValueError: If body name is not resolvable.
+        """
+        ...
+
+
+__all__ = ["IPointingBody"]

pyobs_core-2.0.0.dev19/pyobs/interfaces/IPointingHeliocentricPolar.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass, field
+from typing import Annotated, Any
+
+from ..utils.enums import Unit
+from ..utils.time import Time
+from .interface import Interface
+
+
+@dataclass
+class HeliocentricPolarState:
+    mu: float
+    psi: Annotated[float, Unit.DEGREES]
+    time: Time = field(default_factory=Time.now)
+
+
+class IPointingHeliocentricPolar(Interface, metaclass=ABCMeta):
+    """The module can move to Heliocentric Polar (Mu/Psi) coordinates, usually combined with
+    :class:`~pyobs.interfaces.ITelescope`."""
+
+    __module__ = "pyobs.interfaces"
+
+    state = HeliocentricPolarState
+
+    @abstractmethod
+    async def move_heliocentric_polar(self, mu: float, psi: Annotated[float, Unit.DEGREES], **kwargs: Any) -> None:
+        """Moves on given coordinates.
+
+        Args:
+            mu: Cosine of the angular distance from Sun centre, dimensionless (0..1).
+            psi: Position angle around the solar disk, in degrees.
+
+        Raises:
+            MoveError: If device could not be moved.
+        """
+        ...
+
+
+__all__ = ["IPointingHeliocentricPolar", "HeliocentricPolarState"]

pyobs_core-2.0.0.dev17/pyobs/interfaces/IPointingHGS.py → pyobs_core-2.0.0.dev19/pyobs/interfaces/IPointingHeliographicStonyhurst.py

@@ -10,21 +10,22 @@ from .interface import Interface
 
 
 @dataclass
-class HGSState:
+class HeliographicStonyhurstState:
     lon: Annotated[float, Unit.DEGREES]
     lat: Annotated[float, Unit.DEGREES]
     time: Time = field(default_factory=Time.now)
 
 
-class IPointingHGS(Interface, metaclass=ABCMeta):
-    """The module can move to Mu/Psi coordinates, usually combined with :class:`~pyobs.interfaces.ITelescope`."""
+class IPointingHeliographicStonyhurst(Interface, metaclass=ABCMeta):
+    """The module can move to Heliographic Stonyhurst (lon/lat) coordinates, a frame fixed to the Sun's
+    rotating surface, usually combined with :class:`~pyobs.interfaces.ITelescope`."""
 
     __module__ = "pyobs.interfaces"
 
-    state = HGSState
+    state = HeliographicStonyhurstState
 
     @abstractmethod
-    async def move_hgs_lon_lat(
+    async def move_heliographic_stonyhurst(
         self, lon: Annotated[float, Unit.DEGREES], lat: Annotated[float, Unit.DEGREES], **kwargs: Any
     ) -> None:
         """Moves on given coordinates.
@@ -39,4 +40,4 @@ class IPointingHGS(Interface, metaclass=ABCMeta):
         ...
 
 
-__all__ = ["IPointingHGS", "HGSState"]
+__all__ = ["IPointingHeliographicStonyhurst", "HeliographicStonyhurstState"]

pyobs_core-2.0.0.dev19/pyobs/interfaces/IPointingOrbitalElements.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+from ..utils.enums import Unit
+from ..utils.time import Time
+from .interface import Interface
+
+
+@dataclass
+class OrbitalElements:
+    epoch: Time
+    semi_major_axis: Annotated[float, Unit.AU]
+    eccentricity: float
+    inclination: Annotated[float, Unit.DEGREES]
+    longitude_ascending_node: Annotated[float, Unit.DEGREES]
+    argument_of_periapsis: Annotated[float, Unit.DEGREES]
+    mean_anomaly: Annotated[float, Unit.DEGREES] | None = None
+    """Mean anomaly at epoch, in degrees. Required for elliptical orbits (eccentricity < 1)."""
+    perihelion_time: Time | None = None
+    """Time of perihelion passage. Required for near-parabolic/cometary orbits
+    (eccentricity close to or at 1), where mean anomaly is not well-defined."""
+
+
+class IPointingOrbitalElements(Interface, metaclass=ABCMeta):
+    """Points at and tracks a body defined by orbital elements (asteroid, comet, NEO)."""
+
+    __module__ = "pyobs.interfaces"
+
+    @abstractmethod
+    async def track_orbital_elements(self, elements: OrbitalElements, **kwargs: Any) -> None:
+        """Starts tracking a body defined by orbital elements.
+
+        Args:
+            elements: Orbital elements of the body to track.
+
+        Raises:
+            MoveError: If telescope could not be moved.
+            ValueError: If elements are incomplete or inconsistent (neither mean_anomaly
+                nor perihelion_time given).
+        """
+        ...
+
+
+__all__ = ["IPointingOrbitalElements", "OrbitalElements"]

pyobs_core-2.0.0.dev19/pyobs/interfaces/ITrackingMode.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from ..utils.time import Time
+from .interface import Interface
+
+
+class TrackingMode(StrEnum):
+    """Discrete, hardware-native tracking rate."""
+
+    SIDEREAL = "sidereal"
+    SOLAR = "solar"
+    LUNAR = "lunar"
+    OFF = "off"
+
+
+@dataclass
+class TrackingModeState:
+    mode: TrackingMode
+    time: Time = field(default_factory=Time.now)
+
+
+@dataclass
+class TrackingModeCapabilities:
+    modes: list[TrackingMode]
+
+
+class ITrackingMode(Interface, metaclass=ABCMeta):
+    """The module supports switching between discrete, hardware-native tracking rates."""
+
+    __module__ = "pyobs.interfaces"
+
+    state = TrackingModeState
+    capabilities = TrackingModeCapabilities
+
+    @abstractmethod
+    async def set_tracking_mode(self, mode: TrackingMode, **kwargs: Any) -> None:
+        """Switches to the given tracking mode.
+
+        Args:
+            mode: Tracking mode to switch to.
+
+        Raises:
+            MoveError: If mode could not be set.
+            ValueError: If mode is not in this module's capabilities.
+        """
+        ...
+
+
+__all__ = ["ITrackingMode", "TrackingMode", "TrackingModeState", "TrackingModeCapabilities"]

pyobs_core-2.0.0.dev19/pyobs/interfaces/ITrackingRate.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass, field
+from typing import Annotated, Any
+
+from ..utils.enums import Unit
+from ..utils.time import Time
+from .interface import Interface
+
+
+@dataclass
+class TrackingRateState:
+    ra_rate: Annotated[float, Unit.ARCSEC_PER_SEC]
+    dec_rate: Annotated[float, Unit.ARCSEC_PER_SEC]
+    time: Time = field(default_factory=Time.now)
+
+
+@dataclass
+class TrackingRateCapabilities:
+    min_update_interval: Annotated[float, Unit.SECONDS]
+    """Minimum time between successive set_tracking_rate calls this hardware/protocol accepts,
+    independent of whether the value actually changed. Populated per-driver from whatever its
+    protocol allows; 0 if the hardware has no such floor."""
+
+
+class ITrackingRate(Interface, metaclass=ABCMeta):
+    """The module accepts an arbitrary non-sidereal tracking rate as an absolute RA/Dec offset."""
+
+    __module__ = "pyobs.interfaces"
+
+    state = TrackingRateState
+    capabilities = TrackingRateCapabilities
+
+    @abstractmethod
+    async def set_tracking_rate(
+        self,
+        ra_rate: Annotated[float, Unit.ARCSEC_PER_SEC],
+        dec_rate: Annotated[float, Unit.ARCSEC_PER_SEC],
+        **kwargs: Any,
+    ) -> None:
+        """Sets an absolute tracking rate on the sky, in arcsec/sec.
+
+        Args:
+            ra_rate: Rate in RA, arcsec/sec on the sky.
+            dec_rate: Rate in Dec, arcsec/sec on the sky.
+
+        Raises:
+            MoveError: If rate could not be set.
+        """
+        ...
+
+
+__all__ = ["ITrackingRate", "TrackingRateState", "TrackingRateCapabilities"]

{pyobs_core-2.0.0.dev17 → pyobs_core-2.0.0.dev19}/pyobs/interfaces/__init__.py

@@ -36,15 +36,18 @@ from .IGain import GainState, IGain
 from .IImageFormat import IImageFormat, ImageFormatCapabilities, ImageFormatState
 from .IImageType import IImageType, ImageTypeState
 from .IMode import IMode, ModeCapabilities, ModeState
-from .IModule import IModule, ModuleCapabilities
+from .IModule import IModule, ModuleCapabilities, ModuleLocation
 from .IMotion import DeviceMotionStatus, IMotion, MotionState
 from .IMultiFiber import IMultiFiber, MultiFiberCapabilities, MultiFiberState
 from .interface import Interface
 from .IOffsetsAltAz import AltAzOffsetState, IOffsetsAltAz
 from .IOffsetsRaDec import IOffsetsRaDec, RaDecOffsetState
 from .IPointingAltAz import AltAzState, IPointingAltAz
+from .IPointingBody import IPointingBody
+from .IPointingHeliocentricPolar import HeliocentricPolarState, IPointingHeliocentricPolar
+from .IPointingHeliographicStonyhurst import HeliographicStonyhurstState, IPointingHeliographicStonyhurst
 from .IPointingHelioprojective import HelioprojectiveState, IPointingHelioprojective
-from .IPointingHGS import HGSState, IPointingHGS
+from .IPointingOrbitalElements import IPointingOrbitalElements, OrbitalElements
 from .IPointingRaDec import IPointingRaDec, RaDecState
 from .IPointingSeries import IPointingSeries
 from .IReady import IReady, ReadyState
@@ -59,6 +62,8 @@ from .IStructuredConfig import ConfigAppliedState, ConfigFieldSchema, ConfigSche
 from .ISyncTarget import ISyncTarget
 from .ITelescope import ITelescope
 from .ITemperatures import ITemperatures, SensorReading, TemperaturesState
+from .ITrackingMode import ITrackingMode, TrackingMode, TrackingModeCapabilities, TrackingModeState
+from .ITrackingRate import ITrackingRate, TrackingRateCapabilities, TrackingRateState
 from .IVideo import IVideo, VideoCapabilities
 from .IWeather import IWeather, WeatherSensorReading, WeatherState
 from .IWindow import IWindow, WindowCapabilities, WindowState
@@ -118,6 +123,7 @@ __all__ = [
     "ModeState",
     "IModule",
     "ModuleCapabilities",
+    "ModuleLocation",
     "IMotion",
     "DeviceMotionStatus",
     "MotionState",
@@ -126,10 +132,15 @@ __all__ = [
     "MultiFiberState",
     "IPointingAltAz",
     "AltAzState",
+    "IPointingBody",
+    "IPointingHeliocentricPolar",
+    "HeliocentricPolarState",
+    "IPointingHeliographicStonyhurst",
+    "HeliographicStonyhurstState",
     "IPointingHelioprojective",
     "HelioprojectiveState",
-    "IPointingHGS",
-    "HGSState",
+    "IPointingOrbitalElements",
+    "OrbitalElements",
     "IPointingRaDec",
     "RaDecState",
     "IPointingSeries",
@@ -152,6 +163,13 @@ __all__ = [
     "ITemperatures",
     "SensorReading",
     "TemperaturesState",
+    "ITrackingMode",
+    "TrackingMode",
+    "TrackingModeState",
+    "TrackingModeCapabilities",
+    "ITrackingRate",
+    "TrackingRateState",
+    "TrackingRateCapabilities",
     "IOffsetsAltAz",
     "AltAzOffsetState",
     "IOffsetsRaDec",

pyobs_core-2.0.0.dev19/pyobs/interfaces/interface.py

@@ -0,0 +1,77 @@
+from abc import ABCMeta
+from typing import Any, ClassVar
+
+_REGISTRY: dict[str, "type[Interface]"] = {}
+
+
+class Interface(metaclass=ABCMeta):
+    """Base class for all interfaces in pyobs."""
+
+    version: int = 1
+    state: ClassVar[type | None] = None
+    capabilities: ClassVar[type | None] = None
+
+    __module__ = "pyobs.interfaces"
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+
+        # only genuine interface definitions get registered. Concrete module
+        # classes (e.g. `class BaseCamera(Module, ICamera, IExposureTime,
+        # IImageType)`) also transitively subclass Interface, but always mix
+        # in at least one base that isn't itself an Interface subclass
+        # (Module, a FITS-header mixin, ...). A base only counts as "pure"
+        # if it's Interface itself or is already registered -- issubclass(
+        # base, Interface) alone isn't enough, since e.g. BaseCamera
+        # transitively satisfies that (via ICamera) despite mixing in
+        # Module, which would let DummyCamera(BaseCamera, ...) register
+        # too. Checking registry membership instead propagates purity down
+        # the whole chain, since BaseCamera itself never gets registered.
+        def _is_pure(base: type) -> bool:
+            return base is Interface or _REGISTRY.get(base.__name__) is base
+
+        if not all(_is_pure(base) for base in cls.__bases__):
+            return
+
+        existing = _REGISTRY.get(cls.__name__)
+        if existing is not None and existing is not cls:
+            raise TypeError(
+                f"Interface name '{cls.__name__}' is already registered by "
+                f"{existing.__module__}.{existing.__qualname__}; "
+                f"choose a distinct name for {cls.__module__}.{cls.__qualname__}."
+            )
+        _REGISTRY[cls.__name__] = cls
+
+    def get_state(self, interface: "type[Interface]") -> Any | None:
+        """Return the last received state for the given interface, or None."""
+        return None
+
+    def get_capabilities(self, interface: "type[Interface]") -> Any | None:
+        """Return the capabilities for the given interface, or None."""
+        return None
+
+    async def wait_for_state(self, interface: "type[Interface]", timeout: float = 10.0) -> Any | None:
+        """Return state immediately if available, otherwise wait for the first update."""
+        return None
+
+    @classmethod
+    def has_own_state(cls) -> bool:
+        """True if this interface defines its own state, as opposed to merely inheriting
+        one from a component interface it combines (e.g. ICamera inheriting IExposure's
+        state). Modules publish state under the interface that actually defines it, so
+        composite interfaces would otherwise be (wrongly) treated as publishing state too.
+        """
+        return "state" in cls.__dict__
+
+
+def get_registered_interface(name: str) -> "type[Interface] | None":
+    """Look up a registered interface class by name, or None if unknown."""
+    return _REGISTRY.get(name)
+
+
+def registered_interfaces() -> "dict[str, type[Interface]]":
+    """All currently-registered interface classes, keyed by name."""
+    return dict(_REGISTRY)
+
+
+__all__ = ["Interface", "get_registered_interface", "registered_interfaces"]