simple-module-core 0.0.1__py3-none-any.whl

simple_module_core/events.py

@@ -0,0 +1,91 @@
+"""Async in-process event bus backed by pyee for inter-module communication."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
+from typing import Any
+
+from pyee.asyncio import AsyncIOEventEmitter
+
+logger = logging.getLogger(__name__)
+
+EventHandler = Callable[..., Coroutine[Any, Any, None]]
+
+
+@dataclass
+class Event:
+    """Base class for all domain events.
+
+    Subclass this in your module's contracts:
+
+        @dataclass
+        class ProductCreated(Event):
+            product_id: int
+            name: str
+    """
+
+
+class EventBus:
+    """Async event bus backed by pyee's ``AsyncIOEventEmitter``.
+
+    Modules subscribe to event types in ``register_event_handlers``.
+    Publishing dispatches to all subscribers concurrently.
+
+    * ``publish``      — awaits all handlers via ``asyncio.gather`` (error-isolated).
+    * ``publish_nowait`` — fire-and-forget via pyee's event-loop scheduling.
+    """
+
+    def __init__(self) -> None:
+        self._emitter = AsyncIOEventEmitter()
+        self._emitter.on("error", self._on_emitter_error)
+
+    @staticmethod
+    def _on_emitter_error(error: Exception) -> None:
+        logger.error("EventBus background handler error: %s", error, exc_info=error)
+
+    @staticmethod
+    def _event_key(event_type: type[Event]) -> str:
+        return f"{event_type.__module__}.{event_type.__qualname__}"
+
+    def subscribe(self, event_type: type[Event], handler: EventHandler) -> None:
+        """Register a handler for an event type."""
+        self._emitter.on(self._event_key(event_type), handler)
+        logger.debug(
+            "Subscribed %s to %s",
+            getattr(handler, "__qualname__", repr(handler)),
+            event_type.__name__,
+        )
+
+    async def publish(self, event: Event) -> None:
+        """Dispatch event to all registered handlers (awaited).
+
+        All handlers run concurrently via ``asyncio.gather``.
+        Individual handler failures are logged but do not propagate.
+        """
+        handlers = self._emitter.listeners(self._event_key(type(event)))
+        if not handlers:
+            return
+        results = await asyncio.gather(
+            *(h(event) for h in handlers),
+            return_exceptions=True,
+        )
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                logger.error(
+                    "Event handler %s failed for %s: %s",
+                    getattr(handlers[i], "__qualname__", repr(handlers[i])),
+                    type(event).__name__,
+                    result,
+                    exc_info=result,
+                )
+
+    def publish_nowait(self, event: Event) -> None:
+        """Fire-and-forget: schedule event dispatch on the current event loop.
+
+        Uses pyee's ``AsyncIOEventEmitter.emit`` which schedules async
+        handlers as tasks on the running loop.
+        """
+        self._emitter.emit(self._event_key(type(event)), event)

simple_module_core/exceptions.py

@@ -0,0 +1,56 @@
+"""Framework exceptions."""
+
+
+class ModuleError(Exception):
+    """Base exception for module-related errors."""
+
+
+class InvalidModuleError(ModuleError):
+    """Raised when a discovered module fails structural validation.
+
+    Used by strict discovery (production) to turn "missing ``meta``",
+    "not a ``ModuleBase``", and entry-point load failures into boot-time
+    errors rather than silently-skipped modules.
+    """
+
+
+class CircularDependencyError(ModuleError):
+    """Raised when a circular dependency is detected between modules."""
+
+    def __init__(self, cycle: list[str]) -> None:
+        self.cycle = cycle
+        path = " -> ".join(cycle)
+        super().__init__(f"Circular dependency detected: {path}")
+
+
+class NotFoundError(Exception):
+    """Raised when a requested resource is not found."""
+
+    def __init__(self, resource: str, identifier: str | int) -> None:
+        self.resource = resource
+        self.identifier = identifier
+        super().__init__(f"{resource} with id '{identifier}' not found")
+
+
+class ValidationError(Exception):
+    """Raised when input validation fails."""
+
+    def __init__(self, errors: dict[str, list[str]]) -> None:
+        self.errors = errors
+        super().__init__(f"Validation failed: {errors}")
+
+
+class FrameworkVersionError(ModuleError):
+    """Raised when installed modules are incompatible with the framework API version."""
+
+    def __init__(self, framework_version: str, failures: list[tuple[str, str, str]]) -> None:
+        # failures: list of (module_name, requires_framework, reason)
+        self.framework_version = framework_version
+        self.failures = failures
+        lines = [f"  - {name}: requires '{spec}' — {reason}" for name, spec, reason in failures]
+        super().__init__(
+            f"Installed module(s) incompatible with framework API version {framework_version}:\n"
+            + "\n".join(lines)
+            + "\n\nResolution: upgrade the module(s), upgrade simple_module_core, "
+            "or remove the incompatible module."
+        )

simple_module_core/feature_flags.py

@@ -0,0 +1,187 @@
+"""Feature flag registry — modules declare toggleable features.
+
+Overrides live at two scopes:
+
+* **system** — applies to every request unless a tenant override exists
+* **tenant** — applies only when ``is_enabled`` is called with a matching
+  ``tenant_id``; a per-tenant value beats the system override
+
+Resolution order: tenant override > system override > definition default.
+
+Consumers check a flag inside a FastAPI endpoint via ``is_flag_enabled``,
+``flag_enabled``, ``require_flag``, or the ``@feature_flag`` decorator —
+all tenant-aware using ``request.state.tenant_id`` set by
+``TenantMiddleware``. Every helper accepts either a
+``FeatureFlagDefinition`` (preferred: pass the constant you registered) or
+the raw flag name.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import HTTPException, Request
+
+
+@dataclass(frozen=True)
+class FeatureFlagDefinition:
+    """A feature that can be toggled on/off at runtime."""
+
+    name: str
+    description: str = ""
+    default_enabled: bool = False
+
+
+class FeatureFlagRegistry:
+    """In-memory registry of flag definitions and their resolved overrides."""
+
+    def __init__(self) -> None:
+        self._flags: dict[str, FeatureFlagDefinition] = {}
+        self._system_overrides: dict[str, bool] = {}
+        self._tenant_overrides: dict[tuple[str, str], bool] = {}
+
+    def add(self, flag: FeatureFlagDefinition) -> None:
+        self._flags[flag.name] = flag
+
+    def is_enabled(self, name: str, tenant_id: str | None = None) -> bool:
+        if tenant_id is not None:
+            tenant_value = self._tenant_overrides.get((name, tenant_id))
+            if tenant_value is not None:
+                return tenant_value
+        if name in self._system_overrides:
+            return self._system_overrides[name]
+        flag = self._flags.get(name)
+        return flag.default_enabled if flag else False
+
+    def set_override(self, name: str, enabled: bool, tenant_id: str | None = None) -> None:
+        if tenant_id is None:
+            self._system_overrides[name] = enabled
+        else:
+            self._tenant_overrides[(name, tenant_id)] = enabled
+
+    def clear_override(self, name: str, tenant_id: str | None = None) -> None:
+        if tenant_id is None:
+            self._system_overrides.pop(name, None)
+        else:
+            self._tenant_overrides.pop((name, tenant_id), None)
+
+    def tenant_override(self, name: str, tenant_id: str) -> bool | None:
+        """Return the per-tenant override for ``(name, tenant_id)`` if set, else None."""
+        return self._tenant_overrides.get((name, tenant_id))
+
+    def system_override(self, name: str) -> bool | None:
+        """Return the system-level override for ``name`` if set, else None."""
+        return self._system_overrides.get(name)
+
+    @property
+    def all_flags(self) -> list[FeatureFlagDefinition]:
+        return list(self._flags.values())
+
+
+def _flag_name(flag: FeatureFlagDefinition | str) -> str:
+    return flag.name if isinstance(flag, FeatureFlagDefinition) else flag
+
+
+def is_flag_enabled(request: Request, flag: FeatureFlagDefinition | str) -> bool:
+    """Return whether ``flag`` is enabled for this request's tenant context.
+
+    Reads the registry from ``request.app.state.sm.feature_flags`` and the
+    tenant from ``request.state.tenant_id`` (set by ``TenantMiddleware``).
+    Without a tenant on the request, falls back to the system value or the
+    definition default.
+    """
+    registry: FeatureFlagRegistry = request.app.state.sm.feature_flags
+    tenant_id: str | None = getattr(request.state, "tenant_id", None)
+    return registry.is_enabled(_flag_name(flag), tenant_id=tenant_id)
+
+
+def flag_enabled(flag: FeatureFlagDefinition | str) -> Callable[[Request], bool]:
+    """FastAPI dep factory — yields ``True`` when the flag is on.
+
+    Usage::
+
+        async def handler(
+            on: Annotated[bool, Depends(flag_enabled(FLAG_NEW_UI))],
+        ) -> ...:
+            if on: ...
+    """
+
+    def _dep(request: Request) -> bool:
+        return is_flag_enabled(request, flag)
+
+    return _dep
+
+
+def require_flag(flag: FeatureFlagDefinition | str) -> Callable[[Request], None]:
+    """FastAPI dep factory — raises 404 when the flag is off.
+
+    Gate an entire endpoint behind a flag::
+
+        @router.post(
+            "/bulk",
+            dependencies=[Depends(require_flag(FLAG_BULK_IMPORT))],
+        )
+        async def bulk_import(...): ...
+    """
+
+    def _dep(request: Request) -> None:
+        if not is_flag_enabled(request, flag):
+            raise HTTPException(status_code=404, detail="Feature not available")
+
+    return _dep
+
+
+def feature_flag(
+    flag: FeatureFlagDefinition | str,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator — gates an endpoint behind a flag, 404s when off.
+
+    Attribute-style alternative to ``Depends(require_flag(...))``: apply
+    directly to the handler. The decorated function must accept a
+    ``request: Request`` parameter (FastAPI injects it automatically).
+
+    Usage::
+
+        @router.post("/bulk")
+        @feature_flag(FLAG_BULK_IMPORT)
+        async def bulk_import(request: Request, payload: Payload): ...
+    """
+    name = _flag_name(flag)
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        sig = inspect.signature(fn, eval_str=True)
+        request_param = next(
+            (p.name for p in sig.parameters.values() if p.annotation is Request),
+            None,
+        )
+        if request_param is None:
+            raise TypeError(
+                f"@feature_flag({name!r}): {fn.__qualname__} must declare a "
+                f"'request: Request' parameter for the decorator to read tenant state"
+            )
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                request = sig.bind(*args, **kwargs).arguments[request_param]
+                if not is_flag_enabled(request, name):
+                    raise HTTPException(status_code=404, detail="Feature not available")
+                return await fn(*args, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            request = sig.bind(*args, **kwargs).arguments[request_param]
+            if not is_flag_enabled(request, name):
+                raise HTTPException(status_code=404, detail="Feature not available")
+            return fn(*args, **kwargs)
+
+        return sync_wrapper
+
+    return decorator

simple_module_core/health.py

@@ -0,0 +1,46 @@
+"""Health check registry for module-contributed health checks."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class HealthStatus(StrEnum):
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a single health check."""
+
+    status: HealthStatus
+    detail: str | None = None
+
+
+HealthCheckFn = Callable[[], Awaitable[HealthCheckResult]]
+
+
+@dataclass
+class HealthCheck:
+    """A named health check with an async callable."""
+
+    name: str
+    check: HealthCheckFn
+
+
+class HealthRegistry:
+    """Collects health checks contributed by modules."""
+
+    def __init__(self) -> None:
+        self._checks: list[HealthCheck] = []
+
+    def add(self, check: HealthCheck) -> None:
+        self._checks.append(check)
+
+    @property
+    def all_checks(self) -> list[HealthCheck]:
+        return list(self._checks)

simple_module_core/i18n.py

@@ -0,0 +1,258 @@
+"""Internationalization registry and translator."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from functools import lru_cache
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from babel import Locale
+
+logger = logging.getLogger(__name__)
+
+#: CLDR plural categories, in spec order. Used both for runtime resolution and
+#: as the exhaustive suffix set when tools (e.g. the frontend-types emitter)
+#: need to detect plural-variant keys.
+PLURAL_CATEGORIES: tuple[str, ...] = ("zero", "one", "two", "few", "many", "other")
+
+
+@lru_cache(maxsize=64)
+def _plural_rule(locale: str):  # type: ignore[no-untyped-def]
+    """Cached CLDR plural rule for a locale tag (e.g. 'en', 'ru', 'pt_BR')."""
+    return Locale.parse(locale).plural_form
+
+
+def _plural_form(locale: str, count: float) -> str:
+    """Return CLDR plural category ('one', 'few', 'many', 'other', ...).
+
+    Falls back to 'other' if the locale cannot be parsed by Babel.
+    """
+    try:
+        rule = _plural_rule(locale)
+    except Exception:
+        return "other"
+    return rule(count)
+
+
+def flatten_messages(
+    nested: dict[str, Any],
+    *,
+    prefix: str = "",
+) -> dict[str, str]:
+    """Flatten a nested dict of string leaves to dotted keys.
+
+    {"browse": {"title": "X"}} -> {"browse.title": "X"}
+
+    Raises ValueError if any leaf is not a string.
+    """
+    out: dict[str, str] = {}
+    for key, value in nested.items():
+        composed = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict):
+            out.update(flatten_messages(value, prefix=composed))
+        elif isinstance(value, str):
+            out[composed] = value
+        else:
+            raise ValueError(
+                f"Locale value at '{composed}' must be string or nested dict, "
+                f"got {type(value).__name__}"
+            )
+    return out
+
+
+class I18nRegistry:
+    """Merged view of all module locale JSON files, keyed by locale.
+
+    Usage::
+
+        registry = I18nRegistry(default_locale="en", supported_locales=["en", "es"])
+        registry.add_source("products", Path("modules/products/products/locales"))
+        registry.load()
+        registry.messages("en")  # {"products.browse.title": "Products", ...}
+    """
+
+    def __init__(self, default_locale: str, supported_locales: list[str]) -> None:
+        self.default_locale = default_locale
+        self.supported_locales = list(supported_locales)
+        self._sources: list[tuple[str, Path]] = []
+        self._messages: dict[str, dict[str, str]] = {}
+        # Immutable views into ``_messages`` — handed out by ``messages()`` to
+        # avoid a per-call dict copy. Rebuilt whenever ``load()`` runs.
+        self._message_views: dict[str, MappingProxyType[str, str]] = {}
+        # Plain-dict snapshots for JSON-serializing callers (e.g. Inertia shared
+        # props). Built once per load; handing the same dict out on every request
+        # avoids per-request dict copies that used to dominate allocations on the
+        # Inertia render path.
+        self._message_snapshots: dict[str, dict[str, str]] = {}
+        self._available_locales: tuple[str, ...] = ()
+        self._available_locales_list: list[str] = []
+        self._empty_view: MappingProxyType[str, str] = MappingProxyType({})
+        self._empty_snapshot: dict[str, str] = {}
+        self._loaded = False
+
+    def add_source(self, namespace: str, locale_dir: Path) -> None:
+        """Queue a module's locale directory for loading under a namespace."""
+        self._sources.append((namespace, Path(locale_dir)))
+
+    def load(self) -> None:
+        """Read and flatten all registered JSON files.
+
+        Missing <locale>.json files for declared supported_locales log a
+        warning but do not raise. Malformed JSON raises ValueError.
+        """
+        self._messages = {locale: {} for locale in self.supported_locales}
+
+        for namespace, locale_dir in self._sources:
+            for locale in self.supported_locales:
+                path = locale_dir / f"{locale}.json"
+                if not path.is_file():
+                    logger.warning(
+                        "Missing locale file for namespace '%s': %s",
+                        namespace,
+                        path,
+                    )
+                    continue
+                try:
+                    raw = json.loads(path.read_text(encoding="utf-8"))
+                except json.JSONDecodeError as exc:
+                    raise ValueError(f"invalid JSON in {path}: {exc}") from exc
+                if not isinstance(raw, dict):
+                    raise ValueError(f"{path} must contain a JSON object at the top level")
+                flat = flatten_messages(raw, prefix=namespace)
+                self._messages[locale].update(flat)
+
+        # Cache the derived views now that loading is complete. Downstream
+        # (middleware, translator, switcher) reads these on every request.
+        self._message_views = {
+            locale: MappingProxyType(msgs) for locale, msgs in self._messages.items()
+        }
+        # Plain-dict snapshots for serialization callers. ``dict(msgs)`` runs
+        # once here rather than on every Inertia render.
+        self._message_snapshots = {locale: dict(msgs) for locale, msgs in self._messages.items()}
+        self._available_locales = tuple(locale for locale, msgs in self._messages.items() if msgs)
+        self._available_locales_list = list(self._available_locales)
+        self._loaded = True
+
+    def available_locales(self) -> list[str]:
+        """Locales that have at least one loaded message.
+
+        The list is cached at ``load()`` time; if ``load()`` hasn't run but
+        tests populated ``_messages`` directly, a one-off scan returns the
+        derived list without caching it (the test is outside the normal flow).
+        """
+        if self._loaded:
+            return self._available_locales_list
+        return [locale for locale, msgs in self._messages.items() if msgs]
+
+    def messages(self, locale: str) -> Mapping[str, str]:
+        """Flat dotted-key map for the given locale. Empty mapping if unknown.
+
+        Returns an immutable view (``MappingProxyType``) into the cached
+        message dict — zero-copy. Callers that JSON-serialize the result
+        should use :meth:`messages_snapshot` instead.
+        """
+        view = self._message_views.get(locale)
+        if view is not None:
+            return view
+        # Fallback: ``load()`` wasn't called (tests may populate _messages
+        # directly). Expose the raw dict as a proxy so Translator still works.
+        raw = self._messages.get(locale)
+        if raw is None:
+            return self._empty_view
+        return MappingProxyType(raw)
+
+    def messages_snapshot(self, locale: str) -> dict[str, str]:
+        """Plain-dict snapshot for callers that JSON-serialize the result.
+
+        Built once at :meth:`load` time and handed out by reference on every
+        call. Callers must treat it as read-only — mutating the returned dict
+        corrupts subsequent responses. Used by the Inertia shared-props builder
+        where it sits on the request hot path; prior to this method,
+        ``dict(messages(locale))`` per request was the top own-code allocator.
+        """
+        snapshot = self._message_snapshots.get(locale)
+        if snapshot is not None:
+            return snapshot
+        # Fallback for tests that skip ``load()``: synthesize the snapshot on
+        # demand from whatever ``_messages`` holds.
+        raw = self._messages.get(locale)
+        if raw is None:
+            return self._empty_snapshot
+        return dict(raw)
+
+
+class _SafeFormatDict(dict):
+    """Dict that returns ``{key}`` for missing keys so str.format_map doesn't raise."""
+
+    def __missing__(self, key: str) -> str:
+        return "{" + key + "}"
+
+
+class Translator:
+    """Request-scoped translator bound to a specific locale.
+
+    Construct via::
+
+        Translator(registry, locale=request.state.locale, default_locale="en")
+
+    Resolution order for :meth:`t`:
+
+    1. Look up key in ``locale``; if missing, fall back to ``default_locale``.
+    2. If still missing, return the key itself (with a debug log).
+    3. Interpolate ``{name}``-style placeholders using supplied kwargs.
+       Missing placeholders are left as ``{name}`` (not raised).
+    """
+
+    def __init__(
+        self,
+        registry: I18nRegistry,
+        locale: str,
+        default_locale: str,
+    ) -> None:
+        self._registry = registry
+        self.locale = locale
+        self.default_locale = default_locale
+
+    def t(self, key: str, **params: Any) -> str:
+        """Translate ``key`` with optional interpolation and plural resolution.
+
+        When ``count`` is in params, look up ``<key>_<plural_form>`` using
+        Babel's CLDR plural rule for the active locale, falling back to
+        ``<key>_other`` and finally ``<key>``.
+        """
+        resolved_key = self._resolve_plural_key(key, params)
+        template = self._lookup(resolved_key)
+        if template is None and resolved_key != key:
+            template = self._lookup(key)
+        if template is None:
+            logger.debug("i18n: missing key '%s' in locale '%s'", key, self.locale)
+            return key
+        return template.format_map(_SafeFormatDict(params))
+
+    def _resolve_plural_key(self, key: str, params: dict[str, Any]) -> str:
+        count = params.get("count")
+        if count is None:
+            return key
+        form = _plural_form(self.locale, count)
+        # Prefer the exact form; fall back to _other if that form has no entry.
+        candidate = f"{key}_{form}"
+        if self._lookup(candidate) is not None:
+            return candidate
+        other = f"{key}_other"
+        if self._lookup(other) is not None:
+            return other
+        return key
+
+    def _lookup(self, key: str) -> str | None:
+        msgs = self._registry.messages(self.locale)
+        if key in msgs:
+            return msgs[key]
+        if self.locale != self.default_locale:
+            default = self._registry.messages(self.default_locale)
+            if key in default:
+                return default[key]
+        return None