simple-module-core 0.0.38__tar.gz → 0.0.40__tar.gz

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.38
+Version: 0.0.40
 Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -21,12 +21,12 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: babel>=2.14
-Requires-Dist: fastapi<0.157,>=0.140
-Requires-Dist: packaging>=23.0
-Requires-Dist: pydantic-settings>=2.0
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pyee>=12.0
+Requires-Dist: babel<3,>=2.14
+Requires-Dist: fastapi<0.159,>=0.140
+Requires-Dist: packaging<27,>=23.0
+Requires-Dist: pydantic-settings<3,>=2.0
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyee<15,>=12.0
 Description-Content-Type: text/markdown
 
 # simple_module_core

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.38"
+version = "0.0.40"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"
@@ -21,12 +21,12 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "babel>=2.14",
-    "fastapi>=0.140,<0.157",
-    "packaging>=23.0",
-    "pydantic>=2.0",
-    "pydantic-settings>=2.0",
-    "pyee>=12.0",
+    "babel>=2.14,<3",
+    "fastapi>=0.140,<0.159",
+    "packaging>=23.0,<27",
+    "pydantic>=2.0,<3",
+    "pydantic-settings>=2.0,<3",
+    "pyee>=12.0,<15",
 ]
 
 [project.urls]

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/_i18n_translator.py

@@ -14,6 +14,7 @@ if TYPE_CHECKING:
 # Logged under the historical ``simple_module_core.i18n`` name so existing log
 # filters keep matching after the split.
 logger = logging.getLogger("simple_module_core.i18n")
+_plural_failure_warned = False
 
 
 @lru_cache(maxsize=64)
@@ -30,6 +31,10 @@ def _plural_form(locale: str, count: float) -> str:
     try:
         rule = _plural_rule(locale)
     except Exception:
+        global _plural_failure_warned
+        if not _plural_failure_warned:
+            _plural_failure_warned = True
+            logger.warning("Plural locale parsing failed; using other", exc_info=True)
         return "other"
     return rule(count)
 

simple_module_core-0.0.40/simple_module_core/app_state.py

@@ -0,0 +1,199 @@
+"""Typed reads of optional app services, preserving absent-state fallbacks.
+
+Concrete hosting types are imported only for type checking, as in Services:
+core stays usable without hosting or any plugin installed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from asyncio import Lock
+    from collections.abc import Callable
+
+    from simple_module_hosting._host_services import _HostServices
+    from simple_module_hosting._tenant import TenantResolver
+    from simple_module_hosting.middleware import PrincipalSerializer
+    from simple_module_hosting.shared_props import SharedPropsProvider
+    from simple_module_inertia import Inertia
+    from starlette.requests import Request
+
+    from simple_module_core.body_limits import BodyLimitRegistry
+    from simple_module_core.design_packs import DesignPackRegistry
+    from simple_module_core.module import ModuleBase
+    from simple_module_core.public_routes import PublicRouteRegistry
+    from simple_module_core.rate_limit import RateLimitRegistry
+    from simple_module_core.services import Services
+    from simple_module_core.tenancy import TenantExists, TenantMembers
+
+
+#: Attribute ``register_inertia_shared_provider`` writes and the renderer reads.
+INERTIA_SHARED_PROVIDERS_STATE_ATTR = "inertia_shared_providers"
+
+
+class AuthProvider(Protocol):
+    """Framework-facing auth extension; installed by users or keycloak."""
+
+    async def resolve_user(self, request: Request) -> Any: ...
+
+    def get_login_url(self, request: Request, next_url: str | None = None) -> str: ...
+
+
+class BrandingState(Protocol):
+    """Optional branding services consumed by the document renderer."""
+
+    @property
+    def settings(self) -> object: ...
+
+    @property
+    def favicon_url(self) -> str | None: ...
+
+
+def get_auth_provider(app: Any) -> AuthProvider | None:
+    """Auth.register_settings installs auth; users/keycloak install its provider."""
+    return getattr(getattr(app.state, "auth", None), "auth_provider", None)
+
+
+def get_services(app: Any) -> Services | None:
+    """create_app installs the framework service container.
+
+    Returns None when absent.
+    """
+    return getattr(getattr(app, "state", None), "sm", None)
+
+
+def get_host_services(app: Any) -> _HostServices | None:
+    """Host settings registration installs the host service container.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "host", None)
+
+
+def get_public_routes(app: Any) -> PublicRouteRegistry | None:
+    """create_app installs the public-route registry.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "public_routes", None)
+
+
+def get_body_limits(app: Any) -> BodyLimitRegistry | None:
+    """create_app installs the request-body limit registry.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "body_limits", None)
+
+
+def get_rate_limit_rules(app: Any) -> RateLimitRegistry | None:
+    """create_app installs the per-route rate-limit registry.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "rate_limit_rules", None)
+
+
+def get_design_packs(app: Any) -> DesignPackRegistry | None:
+    """create_app installs the design-pack registry.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "design_packs", None)
+
+
+def get_migration_status(app: Any) -> dict[str, Any] | None:
+    """The hosting lifespan and setup wizard install the migration snapshot.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "migration", None)
+
+
+def get_openapi_url(app: Any) -> str | None:
+    """Hosting boot records the served OpenAPI URL, or None when disabled.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "openapi_url", None)
+
+
+def get_spa_prefixes(app: Any) -> tuple[str, ...]:
+    """SPA mounting records the mounted prefixes; absent means no mounts.
+
+    Returns () when absent.
+    """
+    return getattr(app.state, "spa_prefixes", ())
+
+
+def get_deferred_startup(app: Any) -> list[ModuleBase] | None:
+    """The hosting lifespan records modules awaiting migrations.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "deferred_startup", None)
+
+
+def get_deferred_startup_lock(app: Any) -> Lock | None:
+    """Deferred startup replay lazily installs its per-app lock.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "deferred_startup_lock", None)
+
+
+def get_principal_serializer(app: Any) -> PrincipalSerializer | None:
+    """The auth module installs the principal-to-Inertia serializer.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "principal_serializer", None)
+
+
+def get_tenant_resolver(app: Any) -> TenantResolver | None:
+    """The tenants module installs request tenant resolution.
+
+    Returns None when absent.
+    """
+    return getattr(getattr(app, "state", None), "tenant_resolver", None)
+
+
+def get_tenant_exists(app: Any) -> TenantExists | None:
+    """The tenants module installs the tenant-existence callback.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "tenant_exists", None)
+
+
+def get_tenant_members(app: Any) -> TenantMembers | None:
+    """The tenants module installs the membership lookup callback.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "tenant_members", None)
+
+
+def get_inertia_dependency(app: Any) -> Callable[..., Inertia] | None:
+    """Hosting Inertia setup installs the configured dependency factory.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "inertia_dependency", None)
+
+
+def get_inertia_shared_providers(app: Any) -> list[SharedPropsProvider] | None:
+    """register_inertia_shared_provider lazily installs the provider list.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, INERTIA_SHARED_PROVIDERS_STATE_ATTR, None)
+
+
+def get_branding(app: Any) -> BrandingState | None:
+    """The branding module installs the optional application theme services.
+
+    Returns None when absent.
+    """
+    return getattr(app.state, "branding", None)

simple_module_core-0.0.40/simple_module_core/datetimes.py

@@ -0,0 +1,12 @@
+"""UTC timestamps and normalization of legacy naive database values."""
+
+from datetime import UTC, datetime
+
+
+def utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+def aware(value: datetime) -> datetime:
+    """Interpret a naive value as UTC; preserve an existing timezone."""
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/events.py

@@ -11,6 +11,7 @@ from typing import Any
 from pyee.asyncio import AsyncIOEventEmitter
 
 from simple_module_core.durable_events import (
+    DurableContext,
     DurableDeliveryUnavailable,
     DurableHandler,
     DurableRegistry,
@@ -141,3 +142,22 @@ class EventBus:
         if not names:
             return
         await transport.enqueue(event, names, db)
+
+    async def publish_durable_or_inline(self, event: Event, db: Any) -> None:
+        """Enqueue with a transport, otherwise run durable handlers in *db*.
+
+        Inline handlers run sequentially in subscription order on the caller's
+        transaction with attempt=1. They must flush rather than commit; errors
+        propagate so the caller can roll back. Ordinary subscribers are not run.
+        External effects must be deferred to the caller's post-commit hooks.
+        """
+        if self.durable_transport is not None:
+            await self.publish_durable(event, db)
+            return
+        ctx = DurableContext(db=db, attempt=1)
+        key = self._event_key(type(event))
+        for name in self.durable.handler_names(type(event)):
+            subscription = self.durable.lookup(key, name)
+            if subscription is None:
+                continue
+            await subscription.handler(event, ctx)

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/feature_flags.py

@@ -71,6 +71,13 @@ class FeatureFlagRegistry:
         else:
             self._tenant_overrides.pop((name, tenant_id), None)
 
+    def replace_overrides(
+        self, system: dict[str, bool], tenants: dict[tuple[str, str], bool]
+    ) -> None:
+        """Replace a complete DB snapshot, removing overrides absent from it."""
+        self._system_overrides = dict(system)
+        self._tenant_overrides = dict(tenants)
+
     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))

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/invalidation.py

@@ -9,11 +9,9 @@ share one failure shape: the worker that performed the write drops its own entry
 immediately, and **every other worker keeps serving the stale value until its own
 entry expires**.
 
-``settings`` has the same shape without the TTL — ``apply_changes_and_reload``
-hot-swaps the settings object in the worker that handled the save and announces it
-on the in-process :class:`~simple_module_core.events.EventBus`, so the others serve
-the old configuration until restart. It needs a re-read rather than an eviction, so
-it is a consumer this bus makes *possible* rather than one it already serves.
+``settings``, role overlays and feature-flag overrides had it too (#621); they now
+re-read the committed DB state on invalidation (and every 30 s as a fallback, see
+:mod:`simple_module_core.invalidation_refresh`) rather than evicting an entry.
 
 The obvious fix — publish the write on Redis pub/sub so every worker drops its
 entry at once — was not reachable from any of those modules. Redis belongs to
@@ -48,6 +46,7 @@ from dataclasses import dataclass
 from typing import Protocol, runtime_checkable
 
 logger = logging.getLogger(__name__)
+_decode_failure_warned = False
 
 __all__ = [
     "WIRE_VERSION",
@@ -108,8 +107,8 @@ class Invalidation:
         routinely shared — with another app, with a stray ``redis-cli publish``,
         with the previous version of this code — and a listener loop that dies
         on one malformed payload takes cross-process invalidation down for the
-        life of the process. Logged at debug: on a shared database this is
-        normal traffic, not a fault.
+        life of the process. Decode exceptions warn once per process with a
+        traceback; unsupported shapes remain ordinary shared-database traffic.
         """
         try:
             data = json.loads(message)
@@ -123,7 +122,10 @@ class Invalidation:
                 return None
             return cls(channel=channel, key=key, origin=str(data.get("origin") or ""))
         except Exception:
-            logger.debug("Ignoring undecodable invalidation message: %r", message)
+            global _decode_failure_warned
+            if not _decode_failure_warned:
+                _decode_failure_warned = True
+                logger.warning("Ignoring undecodable invalidation message", exc_info=True)
             return None
 
 

simple_module_core-0.0.40/simple_module_core/invalidation_refresh.py

@@ -0,0 +1,51 @@
+"""Reload DB-backed process state on invalidation and periodically after missed messages."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+
+from simple_module_core.invalidation import Invalidation, InvalidationBus
+
+logger = logging.getLogger(__name__)
+REFRESH_SECONDS = 30
+
+
+class InvalidationRefresh:
+    """Serialize reloads and own the bounded-staleness fallback's lifecycle."""
+
+    def __init__(
+        self, bus: InvalidationBus, channel: str, reload: Callable[[str | None], Awaitable[None]]
+    ) -> None:
+        self._reload = reload
+        self._lock = asyncio.Lock()
+        self._task: asyncio.Task | None = None
+        bus.subscribe(channel, self._receive)
+
+    async def _receive(self, message: Invalidation) -> None:
+        await self.refresh(message.key)
+
+    async def refresh(self, key: str | None = None) -> None:
+        async with self._lock:
+            await self._reload(key)
+
+    def start(self) -> None:
+        if self._task is None:
+            self._task = asyncio.create_task(self._periodic())
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._task
+            self._task = None
+
+    async def _periodic(self) -> None:
+        while True:
+            await asyncio.sleep(REFRESH_SECONDS)
+            try:
+                await self.refresh()
+            except Exception:
+                logger.exception("Periodic state reload failed; retrying on the next interval")

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/leases.py

@@ -43,6 +43,7 @@ __all__ = [
     "configure_leases",
     "get_leases",
     "lease",
+    "reset_lease_backend",
     "semaphore",
 ]
 
@@ -153,6 +154,11 @@ def configure_leases(backend: LeaseBackend | None) -> None:
     _backend = backend if backend is not None else InProcessLeaseBackend()
 
 
+def reset_lease_backend() -> None:
+    """Discard process lease configuration and held in-process leases."""
+    configure_leases(None)
+
+
 def get_leases() -> LeaseBackend:
     """The process-wide backend :func:`lease` and :func:`semaphore` use."""
     return _backend

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/mail.py

@@ -93,6 +93,12 @@ def install_mail_resolver(resolver: MailSenderResolver | None) -> None:
     _resolver = resolver
 
 
+def reset_mail_sender() -> None:
+    """Clear the process sender and resolver between isolated app/test runs."""
+    install_mail_sender(None)
+    install_mail_resolver(None)
+
+
 def mail_transport_installed() -> bool:
     """Whether a transport (sender or resolver) is installed in this process.
 

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/menu.py

@@ -85,6 +85,7 @@ class MenuRegistry:
         self._items: list[MenuItem] = []
         self._sorted: list[MenuItem] | None = None
         self._providers: list[MenuProvider] = []
+        self._failed_providers: set[int] = set()
 
     def _invalidate(self) -> None:
         self._sorted = None
@@ -125,7 +126,11 @@ class MenuRegistry:
                 # Materialise first: a generator failing midway must add nothing.
                 items.extend(list(result))
             except Exception:
-                logger.exception("Menu provider %r failed; contributing nothing", provider)
+                if id(provider) not in self._failed_providers:
+                    self._failed_providers.add(id(provider))
+                    logger.warning(
+                        "Menu provider %r failed; contributing nothing", provider, exc_info=True
+                    )
         return items
 
     @property

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/module.py

@@ -25,6 +25,9 @@ if TYPE_CHECKING:
     from simple_module_core.spa_mount import SpaMount
 
 
+EVENT_HANDLERS_OPTIONAL_APP_REMOVE_IN = "0.1.0"
+
+
 class ModuleBase(RequestHooksMixin, ABC):
     """Base class for all modules.
 
@@ -75,7 +78,9 @@ class ModuleBase(RequestHooksMixin, ABC):
     def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) -> None:
         """Subscribe to events published by other modules.
 
-        ``app`` is optional for back-compat; pass it through to handlers
+        The optional ``app=None`` compatibility default has
+        ``remove_in="0.1.0"``. Overrides own the call, so the base class cannot
+        reliably warn when callers omit it. Pass ``app`` through to handlers
         that need ``app.state.sm.db.session_factory`` to persist on the
         framework's engine instead of building their own.
         """

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/module_meta.py

@@ -50,7 +50,9 @@ class ModuleMeta:
 
     Example: ``">=1.0,<2.0"``. When set, the module is rejected at boot if the
     installed ``simple_module_core.FRAMEWORK_API_VERSION`` does not satisfy it.
-    When ``None``, no compatibility check is performed (legacy modules).
+    When ``None``, no compatibility check is performed (legacy modules);
+    this bypass is deprecated with ``remove_in="0.1.0"`` (tracked by the
+    deprecation-expiry test; it does not warn at boot).
     """
     i18n_audience: str = "public"
     """Who this module's locale catalog is shipped to: ``"public"`` or ``"admin"``.

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/permissions.py

@@ -208,6 +208,14 @@ class PermissionRegistry:
         self._role_overlay[role] = set(permissions)
         self._invalidate()
 
+    def replace_role_overlays(self, overlays: dict[str, list[str]]) -> None:
+        """Replace the complete persisted snapshot, including removed grants."""
+        snapshot = {role: set(keys) for role, keys in overlays.items()}
+        if snapshot == self._role_overlay:  # periodic reloads: keep derived caches warm
+            return
+        self._role_overlay = snapshot
+        self._invalidate()
+
     @property
     def role_map(self) -> dict[str, list[str]]:
         """Merged role→permission mapping (``DEFAULT_ROLE_PERMISSIONS`` + module maps)."""

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/tenancy.py

@@ -17,6 +17,8 @@ from collections.abc import Awaitable, Callable, Collection
 from enum import StrEnum
 from typing import Any
 
+from simple_module_core.app_state import get_tenant_exists, get_tenant_members
+
 TENANT_ROLE_PREFIX = "tenant:"
 
 
@@ -72,7 +74,7 @@ async def tenant_exists(app: Any, tenant_id: str) -> bool | None:
     URL ask through this, so they can refuse a typo without importing that
     module; with none installed the answer is ``None`` and they accept the id.
     """
-    check: TenantExists | None = getattr(app.state, "tenant_exists", None)
+    check: TenantExists | None = get_tenant_exists(app)
     if check is None:
         return None
     return bool(await check(tenant_id))
@@ -97,7 +99,7 @@ async def tenant_member_ids(
     no membership store is installed; callers on a multi-tenant app treat it
     as "nobody" (fail closed).
     """
-    check: TenantMembers | None = getattr(app.state, "tenant_members", None)
+    check: TenantMembers | None = get_tenant_members(app)
     if check is None:
         return None
     if not user_ids:

simple_module_core-0.0.40/simple_module_core/tenant_events.py

@@ -0,0 +1,20 @@
+"""Tenant lifecycle contracts shared without a dependency on a tenant provider."""
+
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+TENANT_DELETED_CHANNEL = "tenants.deleted"
+
+
+@dataclass
+class TenantDeleted(Event):
+    """The tenant registry row is gone; owners must durably tear down its data.
+
+    Delivery is at least once. Retention stores may keep historical rows,
+    identified by their original tenant id, but must never expose live resources.
+    """
+
+    tenant_id: str
+    slug: str
+    name: str

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/user_directory.py

@@ -45,6 +45,9 @@ class DirectoryUser:
     #: Role names, or ``None`` when the provider does not know them (Keycloak
     #: keeps roles in the IdP). Only filled when ``with_roles=True`` was asked.
     roles: tuple[str, ...] | None = None
+    #: Whether the account's email is proven, or ``None`` when the provider
+    #: does not track it (Keycloak: read the token's ``email_verified``).
+    email_verified: bool | None = None
 
     @property
     def label(self) -> str:

simple_module_core-0.0.40/simple_module_core/user_events.py

@@ -0,0 +1,16 @@
+"""User lifecycle contracts shared without a dependency on the users module."""
+
+import uuid
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class UserDeleted(Event):
+    """The account is gone; owners of per-user rows must durably remove them.
+
+    Delivery is at least once, so handlers must be idempotent.
+    """
+
+    user_id: uuid.UUID

{simple_module_core-0.0.38 → simple_module_core-0.0.40}/simple_module_core/versioning.py

@@ -8,6 +8,7 @@ from collections.abc import Sequence
 from packaging.specifiers import InvalidSpecifier, SpecifierSet
 from packaging.version import Version
 
+from simple_module_core.deprecation import deprecate
 from simple_module_core.exceptions import FrameworkVersionError
 from simple_module_core.module import ModuleBase
 
@@ -28,6 +29,13 @@ registries, the event bus, ``create_module_base``, or the model mixins.
 _FRAMEWORK_VERSION = Version(FRAMEWORK_API_VERSION)
 
 
+_UNVERSIONED_MODULE = deprecate(
+    "ModuleMeta.requires_framework=None compatibility bypass",
+    remove_in="0.1.0",
+    use="ModuleMeta(requires_framework=...) with an explicit compatible range",
+)
+
+
 def check_framework_compatibility(
     modules: Sequence[ModuleBase],
     framework_version: str = FRAMEWORK_API_VERSION,
@@ -48,6 +56,9 @@ def check_framework_compatibility(
     for mod in modules:
         spec_str = mod.meta.requires_framework
         if spec_str is None:
+            # Tracked for removal (``_UNVERSIONED_MODULE``) but not warned per
+            # module: every unversioned module, in-repo ones included, would
+            # warn on each boot.
             continue
         try:
             spec = SpecifierSet(spec_str)