MATE-runtime 1.0.0__py3-none-any.whl

MATE/run/declarations.py

@@ -0,0 +1,240 @@
+"""Load-time checks of what a module declares about itself.
+
+These are the checks of [K] §10 that need only the constructed module: its capabilities, the
+methods its flags announce, its reserved names and the names of its observables. Each refusal
+code is produced here by one function.
+"""
+
+from collections.abc import Mapping
+from dataclasses import fields
+
+from MATE_contract import Capabilities, Method, System
+
+from MATE.errors import Refusal
+from MATE.run.specs import NormalisedSpecs
+
+__all__ = ["check_system", "check_method", "check_observable_names"]
+
+_DEFAULT = Capabilities()
+_EXECUTION = ("batched", "threadsafe", "picklable", "backends", "deterministic_given_seed")
+_SYSTEM_ONLY = ("interruptible", "cost_hint", "owns_loop", "clock", "stateful")
+_METHOD_ONLY = tuple(
+    f.name for f in fields(Capabilities) if f.name not in _EXECUTION + _SYSTEM_ONLY
+)
+_LOOP_KINDS = ("generational", "continuous")
+# Level-2 flags that announce the method of the same name ([K] CP3).
+_FLAG_METHODS = ("recommend", "parents", "distance", "split", "generation")
+_METHOD_LEVEL_1 = (
+    "configure", "init", "ask", "decode", "tell", "genome_id",
+    "genome_to_data", "genome_from_data", "state_to_data", "state_from_data",
+)  # fmt: skip
+# Prefixes of the series and summaries MATE publishes itself ([K] OB7).
+_SYSTEM_PREFIXES = ("method.", "performance.", "genome.", "invalid.", "time.")
+_METHOD_PREFIXES = ("method.",)
+
+
+def _implements(module: object, base: type, method: str) -> bool:
+    """Tell whether a module's class overrides a base method ([K] §9.5)."""
+    found = getattr(type(module), method, None)
+    return found is not None and found is not getattr(base, method)
+
+
+def _foreign_fields(
+    caps: Capabilities, foreign: tuple[str, ...], kind: str, name: str
+) -> list[Refusal]:
+    """``P-CAPABILITY-FIELD`` for each foreign field that differs from its default ([K] CP1)."""
+    other = "method" if kind == "system" else "system"
+    return [
+        Refusal("P-CAPABILITY-FIELD", f"{kind} '{name}'",
+                f"{kind} '{name}': Capabilities field '{f}' does not concern a {kind}",
+                fix=f"remove '{f}' from the capabilities (it is a {other} field)")
+        for f in foreign
+        if getattr(caps, f) != getattr(_DEFAULT, f)
+    ]
+
+
+def _backends(caps: Capabilities, kind: str, name: str) -> list[Refusal]:
+    """``P-CAPABILITIES`` for an empty backend list or an empty backend name ([K] CP4)."""
+    if caps.backends and all(caps.backends):
+        return []
+    return [Refusal("P-CAPABILITIES", f"{kind} '{name}'",
+                    f"{kind} '{name}': Capabilities.backends = {caps.backends!r} must be a "
+                    "non-empty tuple of non-empty names")]
+
+
+def _reserved(
+    declared: Mapping[str, object], reserved: tuple[str, ...], kind: str, name: str, what: str
+) -> list[Refusal]:
+    """``P-RESERVED-NAME`` for each declared name MATE reserves ([C] R6.12)."""
+    return [
+        Refusal("P-RESERVED-NAME", f"{kind} '{name}'",
+                f"{kind} '{name}': {what} '{key}' uses a name reserved by MATE "
+                f"({', '.join(reserved)})")
+        for key in declared
+        if key in reserved
+    ]
+
+
+def _prefixed(
+    declared: Mapping[str, object], prefixes: tuple[str, ...], kind: str, name: str
+) -> list[Refusal]:
+    """``P-RESERVED-PREFIX`` for each observable name under a reserved prefix ([K] OB7)."""
+    out = []
+    for s in declared:
+        for p in prefixes:
+            if s.startswith(p):
+                out.append(Refusal("P-RESERVED-PREFIX", f"{kind} '{name}'",
+                                   f"{kind} '{name}': observable name '{s}' uses the reserved "
+                                   f"prefix '{p}'"))
+                break
+    return out
+
+
+def check_system(system: System, *, name: str) -> list[Refusal]:
+    """Check what a system declares about itself.
+
+    Parameters
+    ----------
+    system : System
+        The constructed system.
+    name : str
+        Its entry-point name.
+
+    Returns
+    -------
+    list of Refusal
+        ``P-CAPABILITIES-MISSING`` without a ``Capabilities``; ``P-CAPABILITY-FIELD`` for a
+        method-only field set; ``P-CAPABILITIES`` for a [K] CP4 failure (backends,
+        ``cost_hint``, ``owns_loop`` without ``clock`` or the reverse, ``stateful`` without
+        ``save_state``/``load_state``, ``owns_loop`` without ``evolve``);
+        ``P-RESERVED-NAME`` for a setting named ``module``; ``P-CAPABILITY-METHOD`` for
+        ``spec()`` or ``evaluate()`` not implemented by a system that does not own its loop.
+
+    Notes
+    -----
+    [K] SY2, CP1, CP4, §10 R3, R16, R18; [C] R6.12.
+    """
+    where = f"system '{name}'"
+    out = _reserved(getattr(system, "settings", {}) or {}, ("module",), "system", name,
+                    "setting")
+    caps = getattr(system, "capabilities", None)
+    if not isinstance(caps, Capabilities):
+        out.insert(0, Refusal("P-CAPABILITIES-MISSING", where,
+                              f"system '{name}' declares no Capabilities",
+                              fix="set the class attribute capabilities = Capabilities(...)"))
+        return out
+    out[:0] = _foreign_fields(caps, _METHOD_ONLY, "system", name) + _backends(caps, "system", name)
+    if caps.cost_hint <= 0:
+        out.append(Refusal("P-CAPABILITIES", where,
+                           f"system '{name}': Capabilities.cost_hint = {caps.cost_hint} must be "
+                           "> 0"))
+    if caps.owns_loop and not caps.clock:
+        out.append(Refusal("P-CAPABILITIES", where,
+                           f"system '{name}': Capabilities.owns_loop is True but clock is empty; "
+                           "a system that owns its loop names the unit of its dates"))
+    if caps.clock and not caps.owns_loop:
+        out.append(Refusal("P-CAPABILITIES", where,
+                           f"system '{name}': Capabilities.clock = '{caps.clock}' but owns_loop "
+                           "is False; only a system that owns its loop has a clock"))
+    if caps.stateful:
+        missing = [m for m in ("save_state", "load_state") if not _implements(system, System, m)]
+        if missing:
+            out.append(Refusal("P-CAPABILITIES", where,
+                               f"system '{name}': Capabilities.stateful is True but "
+                               f"{' and '.join(m + '()' for m in missing)} not implemented"))
+    if caps.owns_loop and not _implements(system, System, "evolve"):
+        out.append(Refusal("P-CAPABILITIES", where,
+                           f"system '{name}': Capabilities.owns_loop is True but evolve() is not "
+                           "implemented"))
+    if not caps.owns_loop:
+        for m in ("spec", "evaluate"):
+            if not _implements(system, System, m):
+                out.append(Refusal("P-CAPABILITY-METHOD", where,
+                                   f"system '{name}': {m}() is not implemented; it is required "
+                                   "of a system that does not own its loop"))
+    return out
+
+
+def check_method(method: Method, *, name: str) -> list[Refusal]:
+    """Check what a method declares about itself.
+
+    Parameters
+    ----------
+    method : Method
+        The constructed method.
+    name : str
+        Its entry-point name.
+
+    Returns
+    -------
+    list of Refusal
+        ``P-CAPABILITY-FIELD`` for a system-only field set; ``P-CAPABILITIES`` for a [K] CP4
+        failure (``loop_kinds``, backends, ``rereadable`` outside a declared ``meta``);
+        ``P-CAPABILITY-METHOD`` for a level-2 flag without its method, or a level-1 method not
+        implemented; ``P-ALLOCATION`` for ``allocation = True``; ``P-RESERVED-NAME`` for a
+        meta-parameter named ``module`` or ``role``; ``P-RESERVED-PREFIX`` for a series or
+        summary named ``method.<...>``.
+
+    Notes
+    -----
+    [K] CP1, CP3, CP4, CP5, OB7, §10 R3, R14, R16, R17; [C] R6.12. ``P-ALLOCATION`` is
+    produced here only (design §3.5).
+    """
+    where = f"method '{name}'"
+    caps = getattr(method, "capabilities", _DEFAULT)
+    meta = getattr(method, "meta", {}) or {}
+    out = _foreign_fields(caps, _SYSTEM_ONLY, "method", name) + _backends(caps, "method", name)
+    kinds = caps.loop_kinds
+    if not kinds or any(k not in _LOOP_KINDS for k in kinds):
+        out.append(Refusal("P-CAPABILITIES", where,
+                           f"method '{name}': Capabilities.loop_kinds = {kinds!r} must be a "
+                           f"non-empty subset of {_LOOP_KINDS!r}"))
+    stray = [r for r in caps.rereadable if r not in meta]
+    if meta and stray:
+        out.append(Refusal("P-CAPABILITIES", where,
+                           f"method '{name}': Capabilities.rereadable names {', '.join(stray)}, "
+                           f"which are not meta-parameters (meta: {', '.join(meta)})"))
+    for flag in _FLAG_METHODS:
+        if getattr(caps, flag) and not _implements(method, Method, flag):
+            out.append(Refusal("P-CAPABILITY-METHOD", where,
+                               f"method '{name}': Capabilities.{flag} is True but {flag}() is "
+                               "not implemented"))
+    for m in _METHOD_LEVEL_1:
+        if not _implements(method, Method, m):
+            out.append(Refusal("P-CAPABILITY-METHOD", where,
+                               f"method '{name}': {m}() is not implemented; every method "
+                               "implements it (level 1)"))
+    if caps.allocation:
+        out.append(Refusal("P-ALLOCATION", where,
+                           f"method '{name}' declares Capabilities.allocation; budget allocation "
+                           "by the method is not available in MATE 1.0.0: its interface is not "
+                           "yet specified"))
+    out += _reserved(meta, ("module", "role"), "method", name, "meta-parameter")
+    out += _prefixed(getattr(method, "series", {}) or {}, _METHOD_PREFIXES, "method", name)
+    out += _prefixed(getattr(method, "summaries", {}) or {}, _METHOD_PREFIXES, "method", name)
+    return out
+
+
+def check_observable_names(specs: NormalisedSpecs, *, system: str) -> list[Refusal]:
+    """Check the names of a system's series and summaries.
+
+    Parameters
+    ----------
+    specs : NormalisedSpecs
+        The system's normalised specs.
+    system : str
+        The system's entry-point name.
+
+    Returns
+    -------
+    list of Refusal
+        ``P-RESERVED-PREFIX`` for each name starting with ``method.``, ``performance.``,
+        ``genome.``, ``invalid.`` or ``time.``.
+
+    Notes
+    -----
+    [K] OB7, §10 R17.
+    """
+    obs = specs.observables
+    return (_prefixed(obs.series, _SYSTEM_PREFIXES, "system", system)
+            + _prefixed(obs.summaries, _SYSTEM_PREFIXES, "system", system))