led-ticker-core 2.0.0__py3-none-any.whl

led_ticker/__init__.py

@@ -0,0 +1,3 @@
+"""led-ticker: Asyncio LED matrix display for news, weather, crypto, and more."""
+
+__version__ = "2.0.0"

led_ticker/_coerce.py

@@ -0,0 +1,125 @@
+"""Pure coercion helpers for config load.
+
+Each helper returns `(coerced_value, warning_or_None)`. The caller
+decides whether to surface the warning via `led-ticker validate`
+output, runtime `logging.warning`, or both.
+
+Bool is rejected explicitly in `coerce_int` / `coerce_float` because
+bool is a subclass of `int` in Python. Silently coercing `true → 1`
+would reopen the hole that the existing `bottom_text_loops` and
+`font_threshold` validators close.
+"""
+
+import attrs
+
+
+@attrs.frozen
+class CoercionWarning:
+    field: str
+    original: object
+    coerced: object
+    message: str
+
+
+def coerce_int(value: object, *, field: str) -> tuple[int, CoercionWarning | None]:
+    """Coerce string-of-digits → int. Raise ValueError otherwise.
+
+    Rejects: bool, float, non-numeric strings, None.
+    """
+    if isinstance(value, bool):
+        raise ValueError(
+            f"{field} must be an int; got bool ({value!r}). "
+            f"TOML has native true/false — if you meant a number, drop the "
+            f"true/false and write 0 or 1 explicitly."
+        )
+    if isinstance(value, int):
+        return value, None
+    if isinstance(value, str):
+        try:
+            coerced = int(value)
+        except ValueError:
+            raise ValueError(
+                f'{field} must be an int; got str ("{value}"). '
+                f"Drop the quotes around the number (e.g. {field} = 25 "
+                f'instead of {field} = "25").'
+            ) from None
+        return coerced, CoercionWarning(
+            field=field,
+            original=value,
+            coerced=coerced,
+            message=(
+                f'{field} was a string ("{value}"); coerced to int {coerced}. '
+                f"Drop the quotes around the number to silence this warning."
+            ),
+        )
+    raise ValueError(f"{field} must be an int; got {type(value).__name__} ({value!r}).")
+
+
+def coerce_float(value: object, *, field: str) -> tuple[float, CoercionWarning | None]:
+    """Coerce string-of-number → float. Accept int passthrough.
+
+    Rejects: bool, non-numeric strings, None.
+    """
+    if isinstance(value, bool):
+        raise ValueError(
+            f"{field} must be a float; got bool ({value!r}). "
+            f"Use a number (e.g. {field} = 3.0)."
+        )
+    if isinstance(value, int):
+        return float(value), None
+    if isinstance(value, float):
+        return value, None
+    if isinstance(value, str):
+        try:
+            coerced = float(value)
+        except ValueError:
+            raise ValueError(
+                f'{field} must be a float; got str ("{value}"). '
+                f"Drop the quotes around the number (e.g. {field} = 3.0 "
+                f'instead of {field} = "3.0").'
+            ) from None
+        return coerced, CoercionWarning(
+            field=field,
+            original=value,
+            coerced=coerced,
+            message=(
+                f'{field} was a string ("{value}"); coerced to float {coerced}. '
+                f"Drop the quotes around the number to silence this warning."
+            ),
+        )
+    raise ValueError(
+        f"{field} must be a float; got {type(value).__name__} ({value!r})."
+    )
+
+
+def coerce_choice(
+    value: object, *, field: str, valid: frozenset[str]
+) -> tuple[str, CoercionWarning | None]:
+    """Normalize a closed-set enum string (lowercase + strip).
+
+    Raise ValueError if the input isn't a string, or if the normalized
+    value still isn't in `valid`.
+    """
+    if not isinstance(value, str):
+        raise ValueError(
+            f"{field} must be a string; got {type(value).__name__} "
+            f"({value!r}). Expected one of {sorted(valid)}."
+        )
+    normalized = value.strip().lower()
+    if normalized not in valid:
+        raise ValueError(
+            f'{field}="{value}" is not a valid choice; expected one of {sorted(valid)}.'
+        )
+    if normalized == value:
+        return normalized, None
+    return normalized, CoercionWarning(
+        field=field,
+        original=value,
+        coerced=normalized,
+        message=(
+            f'{field} was "{value}"; coerced to "{normalized}". Enum '
+            f"values are case-insensitive but the canonical form is "
+            f'lowercase — write {field} = "{normalized}" to silence '
+            f"this warning."
+        ),
+    )

led_ticker/_compat.py

@@ -0,0 +1,42 @@
+"""Compatibility shim for rgbmatrix.
+
+Attempts to import the real rgbmatrix C library (available on Raspberry Pi).
+Falls back to a bundled pure-Python stub of `graphics.*` (Color, Font,
+DrawText) when it isn't installed, so `led-ticker validate` and other
+non-drawing operations work on any machine without PYTHONPATH tricks.
+
+`RGBMatrix` and `RGBMatrixOptions` are NOT stubbed — running the actual
+display requires real hardware. `require_matrix()` raises a clear error
+if you try to construct a matrix without rgbmatrix installed.
+"""
+
+from typing import Any
+
+try:
+    from rgbmatrix import RGBMatrix, RGBMatrixOptions, graphics
+except ImportError:
+    from led_ticker import _rgbmatrix_stub as graphics  # type: ignore[assignment]
+
+    RGBMatrix = None  # type: ignore[assignment]
+    RGBMatrixOptions = None  # type: ignore[assignment]
+
+
+def require_graphics() -> Any:
+    """Return the graphics module (real rgbmatrix or bundled stub)."""
+    return graphics
+
+
+def require_matrix() -> Any:
+    """Return the RGBMatrix class. Raises if rgbmatrix is not installed.
+
+    Use this when actually constructing the display — graphics-only
+    operations (Color, Font, DrawText) should use `require_graphics()`
+    instead, which always returns something usable.
+    """
+    if RGBMatrix is None:
+        raise RuntimeError(
+            "rgbmatrix hardware library not installed. "
+            "Run on a Raspberry Pi with the LED matrix library, "
+            "or use `PYTHONPATH=tests/stubs` for test fixtures."
+        )
+    return RGBMatrix

led_ticker/_plugin_hint.py

@@ -0,0 +1,37 @@
+"""Shared helper for "this name didn't resolve" errors across every
+registry (transitions, widgets, borders, color providers, animations).
+
+A namespaced name (`<plugin>.<name>`) that fails to resolve almost
+always means the owning plugin isn't installed. This helper turns that
+into an actionable hint. It is pure and context-free — it does NOT
+consult the loaded-plugin set, so it works from the bare runtime
+registry lookups that have no `LoadedPlugins` handle.
+
+The fix text suggests `led-ticker plugin install <namespace>` (the plugin
+catalog CLI). This is the one place to update if that command changes.
+"""
+
+
+def plugin_hint(name: str, kind: str) -> str | None:
+    """Return an install hint if `name` looks like a reference to an
+    uninstalled plugin component, else None.
+
+    A hint is returned only when the namespace (segment before the first
+    dot) is a valid Python identifier — real plugin namespaces always are
+    (e.g. ``baseball``, ``pool``, ``crypto``), while dotted non-plugin
+    values like ``"1.5"`` or ``"."`` are not and fall through to None.
+
+    `kind` is the human word for the registry — "transition", "widget",
+    "border", "color provider", "animation".
+    """
+    if "." not in name:
+        return None
+    namespace = name.split(".", 1)[0]
+    if not namespace.isidentifier():
+        return None
+    return (
+        f"{name!r} looks like a plugin {kind}, but no {namespace!r} plugin "
+        f"is loaded. Install it with `led-ticker plugin install {namespace}` "
+        f"(or check the namespace). "
+        f"See https://docs.ledticker.dev/plugins/."
+    )

led_ticker/_plugin_loader.py

@@ -0,0 +1,393 @@
+"""Plugin discovery and loading (internal). Plugins never import this."""
+
+import contextlib
+import importlib.metadata
+import importlib.util
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from led_ticker.animations import _ANIMATION_REGISTRY
+from led_ticker.borders import _BORDER_REGISTRY
+from led_ticker.color_providers import _PROVIDER_REGISTRY
+from led_ticker.config import PluginsConfig, _parse_plugins_block
+from led_ticker.fonts.hires_loader import _PLUGIN_FONTS
+from led_ticker.pixel_emoji import EMOJI_REGISTRY, HIRES_REGISTRY
+from led_ticker.plugin import API_VERSION, PluginAPI
+from led_ticker.transitions import _TRANSITION_REGISTRY, EASING
+from led_ticker.widgets import _WIDGET_REGISTRY
+
+logger = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "led_ticker.plugins"
+
+# surface name (matches PluginAPI._buffers keys) -> the registry it commits into.
+# Later phases extend this map; the commit loop never changes.
+_REGISTRY_MAP: dict[str, dict[str, Any]] = {
+    "widgets": _WIDGET_REGISTRY,
+    "transitions": _TRANSITION_REGISTRY,
+    "color_providers": _PROVIDER_REGISTRY,
+    "animations": _ANIMATION_REGISTRY,
+    "borders": _BORDER_REGISTRY,
+    "easing": EASING,
+    "emojis": EMOJI_REGISTRY,
+    "hires_emojis": HIRES_REGISTRY,
+    "fonts": _PLUGIN_FONTS,
+}
+
+
+@dataclass
+class PluginInfo:
+    namespace: str
+    source: str
+    counts: dict[str, int] = field(default_factory=dict)
+    # Per-surface qualified contribution names (e.g. {"widgets": ["acme.clock"]})
+    # — what an operator references in TOML.
+    names: dict[str, list[str]] = field(default_factory=dict)
+
+
+@dataclass
+class LoadedPlugins:
+    loaded: list[PluginInfo] = field(default_factory=list)
+    failed: list[tuple[str, str]] = field(default_factory=list)
+    # Lifecycle hooks, each tagged with the contributing namespace (for logging
+    # and the overlay guard). Collected only from successfully-loaded plugins.
+    overlays: list[tuple[str, Callable[[Any], None]]] = field(default_factory=list)
+    startup_hooks: list[tuple[str, Callable[..., Any]]] = field(default_factory=list)
+    shutdown_hooks: list[tuple[str, Callable[..., Any]]] = field(default_factory=list)
+
+
+# Load-once guard; assigned by load_plugins() (added in Task A3).
+_LOADED: LoadedPlugins | None = None
+
+
+def reset_plugins() -> None:
+    """Test helper: drop all namespaced (dotted) registry entries + load guard.
+
+    Note: ``pixel_emoji._EMOJI_BUILTINS_LOADED`` is intentionally NOT reset
+    here. Built-in emoji entries are bare slugs (no dot), so they survive the
+    dotted-key deletion and the sentinel stays True — ``_get_registry()`` keeps
+    returning them. A test that needs a pristine un-built emoji registry must
+    also set ``pe._EMOJI_BUILTINS_LOADED = False`` and clear ``pe.EMOJI_REGISTRY``
+    itself.
+    """
+    global _LOADED  # noqa: PLW0603
+    for registry in _REGISTRY_MAP.values():
+        for key in [k for k in registry if "." in k]:
+            del registry[key]
+    _LOADED = None
+    # A plugin font name may have been looked up (and cached as a miss) before
+    # its plugin registered. Drop the hi-res font cache so the next resolve
+    # re-reads _PLUGIN_FONTS instead of returning a stale None.
+    from led_ticker.fonts import hires_loader
+
+    hires_loader.load_hires_font.cache_clear()
+
+
+def _commit(api: PluginAPI, info: PluginInfo) -> None:
+    """Write a cleanly-registered plugin's buffers into the registries.
+
+    Two-pass (validate all, then write all) so a mid-commit collision can't
+    leave a partial registration. Only buffers that map to a registry are
+    committed here (hook surfaces are collected separately — see _load_one).
+    """
+    for surface, buf in api._buffers.items():
+        registry = _REGISTRY_MAP.get(surface)
+        if registry is None:
+            logger.debug(
+                "surface %r not in _REGISTRY_MAP; skipping (hook surface?)", surface
+            )
+            continue
+        for name in buf:
+            if name in registry:
+                raise ValueError(f"{surface} entry {name!r} already registered")
+    for surface, buf in api._buffers.items():
+        registry = _REGISTRY_MAP.get(surface)
+        if registry is None:
+            continue
+        for name, obj in buf.items():
+            registry[name] = obj
+        if buf:
+            info.counts[surface] = len(buf)
+            info.names[surface] = sorted(buf)
+
+
+def _resolve_root(source: str, register: Callable[[PluginAPI], None]) -> Path | None:
+    """Best-effort plugin root for resolving ``api.font()`` relative paths.
+
+    Local plugins: the dir containing the plugin file — a single-file plugin's
+    parent (the plugins dir), or the package dir itself. Entry-point plugins:
+    the dir of the register callable's module. Returns ``None`` when it cannot
+    be determined (e.g. a zip-imported package); ``api.font`` then raises a
+    clear error rather than guessing.
+
+    Uses ``.py`` suffix rather than ``path.is_file()`` to discriminate between
+    a single-file plugin and a package dir, so the check is existence-independent
+    (works even when the source path is hypothetical or in a tmp dir in tests).
+
+    For entry-point plugins, ``inspect.getmodule`` is tried first; if it
+    returns ``None`` (e.g. the module was loaded via ``spec_from_file_location``
+    without being registered in ``sys.modules``), we fall back to
+    ``register.__globals__.get('__file__')`` which Py guarantees is set for
+    any function defined in a source file.
+    """
+    if source.startswith("entry-point:"):
+        module = inspect.getmodule(register)
+        module_file = getattr(module, "__file__", None)
+        if module_file is None:
+            # Fallback: function's own globals dict always has __file__ for
+            # source-file functions, even when the module isn't in sys.modules.
+            module_file = getattr(register, "__globals__", {}).get("__file__")
+        return Path(module_file).parent if module_file else None
+    path = Path(source)
+    return path.parent if path.suffix == ".py" else path
+
+
+def _warn_unpaired_hires(namespace: str, api: PluginAPI) -> None:
+    """Warn when a plugin registers a hi-res emoji with no low-res counterpart.
+
+    Inline ``:ns.slug:`` parsing and unscaled canvases resolve only through the
+    low-res emoji registry, so a hi-res-only slug silently won't render there.
+    Built-in emojis always pair the two; plugins must too for inline use.
+    """
+    lowres = set(api._buffers["emojis"])
+    for slug in api._buffers["hires_emojis"]:
+        if slug not in lowres:
+            bare = slug.split(".", 1)[-1]
+            logger.warning(
+                "plugin %r: hi-res emoji %r has no low-res counterpart; it will "
+                "not render inline (:%s:) or on unscaled canvases. Also register "
+                "api.emoji(%r, ...).",
+                namespace,
+                slug,
+                slug,
+                bare,
+            )
+
+
+def _guarded_overlay(
+    namespace: str, paint: Callable[[Any], None]
+) -> Callable[[Any], None]:
+    """Wrap a plugin overlay so a raise disables it (and logs once) instead of
+    propagating out of ``LedFrame.swap()``.
+
+    Core overlays intentionally have no per-hook try/except (a raising core hook
+    freezes the panel — the documented invariant). Plugin code is less trusted,
+    so its overlays must never be able to freeze the panel.
+    """
+    state = {"disabled": False}
+
+    def wrapped(canvas: Any) -> None:
+        if state["disabled"]:
+            return
+        try:
+            paint(canvas)
+        except Exception:
+            state["disabled"] = True
+            # Never let a logging failure propagate into swap() and freeze
+            # the panel — disabling the overlay is what matters.
+            with contextlib.suppress(Exception):
+                logger.exception(
+                    "plugin %r overlay raised; disabling it for this run", namespace
+                )
+
+    return wrapped
+
+
+async def _run_startup_hooks(
+    hooks: list[tuple[str, Callable[..., Any]]], ctx: Any
+) -> None:
+    """Run each on_startup hook once, isolating failures. Awaits a hook that
+    returns a coroutine."""
+    for namespace, fn in hooks:
+        try:
+            result = fn(ctx)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            logger.exception("plugin %r on_startup hook failed", namespace)
+
+
+async def _run_shutdown_hooks(
+    hooks: list[tuple[str, Callable[..., Any]]],
+) -> None:
+    """Run each on_shutdown hook best-effort, isolating failures. Awaits a hook
+    that returns a coroutine.
+
+    Failure isolation covers ``Exception`` only. A hook that raises or
+    propagates ``CancelledError``/``KeyboardInterrupt`` (both ``BaseException``)
+    interrupts the remaining shutdown sequence — intentional: plugin code must
+    not be able to suppress external cancellation, and this runner is invoked
+    from the run-loop ``finally`` which is itself reached via cancellation.
+    """
+    for namespace, fn in hooks:
+        try:
+            result = fn()
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            logger.exception("plugin %r on_shutdown hook failed", namespace)
+
+
+def _load_one(
+    namespace: str,
+    source: str,
+    register: Callable[[PluginAPI], None] | None,
+    requires_api: int | None,
+    loaded_namespaces: set[str],
+    result: LoadedPlugins,
+) -> None:
+    """Run + commit one plugin's register(), isolating all failures."""
+    if namespace in loaded_namespaces:
+        result.failed.append((namespace, "namespace already claimed by another plugin"))
+        logger.error(
+            "plugin namespace %r already claimed; skipping %s", namespace, source
+        )
+        return
+    if requires_api is not None and requires_api != API_VERSION[0]:
+        msg = f"requires API v{requires_api}, core is v{API_VERSION[0]}"
+        result.failed.append((namespace, msg))
+        logger.error("plugin %r %s; skipping", namespace, msg)
+        return
+    if register is None or not callable(register):
+        result.failed.append((namespace, "no callable register(api) found"))
+        logger.error("plugin %r has no register(api); skipping %s", namespace, source)
+        return
+    root = _resolve_root(source, register)
+    api = PluginAPI(namespace, root=root)
+    info = PluginInfo(namespace=namespace, source=source)
+    try:
+        register(api)
+        _commit(api, info)
+    except Exception as e:  # isolation: a plugin must never crash the app
+        logger.exception("plugin %r (%s) failed to load", namespace, source)
+        result.failed.append((namespace, str(e)))
+        return
+    loaded_namespaces.add(namespace)
+    result.loaded.append(info)
+    _warn_unpaired_hires(namespace, api)
+    for paint in api._overlays:
+        result.overlays.append((namespace, paint))
+    for fn in api._startup_hooks:
+        result.startup_hooks.append((namespace, fn))
+    for fn in api._shutdown_hooks:
+        result.shutdown_hooks.append((namespace, fn))
+    logger.info("plugin %r loaded from %s (%s)", namespace, source, info.counts)
+
+
+def _import_from_path(mod_name: str, init: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(mod_name, init)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load plugin module from {init}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _discover_local(plugin_dir: Path):
+    """Yield (namespace, source, thunk) for each local plugin. The thunk imports
+    the module lazily and returns (register, requires_api)."""
+    if not plugin_dir.is_dir():
+        return
+    for entry in sorted(plugin_dir.iterdir()):
+        if entry.name.startswith("_"):
+            continue
+        if entry.suffix == ".py" and entry.is_file():
+            ns, init = entry.stem, entry
+        elif entry.is_dir() and (entry / "__init__.py").exists():
+            ns, init = entry.name, entry / "__init__.py"
+        else:
+            continue
+
+        def thunk(ns=ns, init=init):
+            mod = _import_from_path(f"led_ticker_plugin_{ns}", init)
+            return getattr(mod, "register", None), getattr(mod, "requires_api", None)
+
+        yield ns, str(entry), thunk
+
+
+def _discover_entry_points():
+    """Yield (namespace, source, thunk) for installed entry-point plugins.
+    Namespace = the entry-point name; the thunk loads the entry point and
+    resolves its register callable."""
+    try:
+        eps = importlib.metadata.entry_points(group=ENTRY_POINT_GROUP)
+    except Exception:  # pragma: no cover - defensive across importlib versions
+        return
+    for ep in eps:
+
+        def thunk(ep=ep):
+            obj = ep.load()
+            if callable(obj) and not isinstance(obj, type):
+                return obj, getattr(obj, "requires_api", None)
+            register = getattr(obj, "register", None)
+            return register, getattr(obj, "requires_api", None)
+
+        yield ep.name, f"entry-point:{ep.value}", thunk
+
+
+def load_plugins(
+    plugin_dir: Path | None,
+    *,
+    entry_points_enabled: bool = True,
+    disable: set[str] | None = None,
+) -> LoadedPlugins:
+    """Discover + load all plugins once. Idempotent (call reset_plugins() in
+    tests to reload). ``disable`` is a set of namespaces to skip + log."""
+    global _LOADED  # noqa: PLW0603
+    if _LOADED is not None:
+        return _LOADED
+    disabled = disable or set()
+    result = LoadedPlugins()
+    loaded_ns: set[str] = set()
+    sources = []
+    if plugin_dir is not None:
+        sources.extend(_discover_local(plugin_dir))
+    if entry_points_enabled:
+        sources.extend(_discover_entry_points())
+    for ns, source, thunk in sources:
+        if ns in disabled:
+            logger.info("plugin %r disabled via [plugins].disable; skipping", ns)
+            continue
+        try:
+            register, requires = thunk()
+        except Exception as e:
+            logger.exception("plugin %r (%s) failed to import", ns, source)
+            result.failed.append((ns, str(e)))
+            continue
+        _load_one(ns, source, register, requires, loaded_ns, result)
+    _LOADED = result
+    return result
+
+
+def read_plugins_config(config_path: Path) -> PluginsConfig:
+    """Lightweight read of just the ``[plugins]`` block, so plugin discovery can
+    run BEFORE full config validation (plugin-provided easings etc. must be
+    registered before load_config validates them). Returns defaults only if the
+    file is missing; a TOML syntax error or a structural ``[plugins]`` error
+    propagates so the caller can report it.
+    """
+    import tomllib
+
+    try:
+        with open(config_path, "rb") as f:
+            raw = tomllib.load(f)
+    except FileNotFoundError:
+        return PluginsConfig()
+    return _parse_plugins_block(raw)
+
+
+def load_plugins_for_config(config_path: Path) -> LoadedPlugins:
+    """Config-driven plugin load: read the ``[plugins]`` block, then load from
+    ``<config dir>/<dir>`` honoring enable/disable. Used by the run loop, the
+    ``validate`` path, and the ``plugins`` CLI command."""
+    pc = read_plugins_config(config_path)
+    if not pc.enabled:
+        logger.info("plugins disabled via [plugins].enabled=false; skipping")
+        return load_plugins(None, entry_points_enabled=False)
+    plugin_dir = config_path.parent / pc.dir
+    return load_plugins(plugin_dir, disable=set(pc.disable))