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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.38
+Version: 0.0.39
 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: babel<3,>=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: 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.39}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.38"
+version = "0.0.39"
 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",
+    "babel>=2.14,<3",
     "fastapi>=0.140,<0.157",
-    "packaging>=23.0",
-    "pydantic>=2.0",
-    "pydantic-settings>=2.0",
-    "pyee>=12.0",
+    "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.39}/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.39/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.38 → simple_module_core-0.0.39}/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.39}/simple_module_core/invalidation.py

@@ -48,6 +48,7 @@ from dataclasses import dataclass
 from typing import Protocol, runtime_checkable
 
 logger = logging.getLogger(__name__)
+_decode_failure_warned = False
 
 __all__ = [
     "WIRE_VERSION",
@@ -108,8 +109,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 +124,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.38 → simple_module_core-0.0.39}/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.39}/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.39}/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.39}/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.39}/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.39}/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.39/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.39}/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)

simple_module_core-0.0.39/tests/test_core_app_state.py

@@ -0,0 +1,57 @@
+"""Optional app services retain their defaults and installed object identity."""
+
+from types import SimpleNamespace
+
+import pytest
+from fastapi import FastAPI
+from simple_module_core import app_state
+
+
+@pytest.mark.parametrize(
+    ("attribute", "accessor_name", "default"),
+    [
+        ("sm", "get_services", None),
+        ("host", "get_host_services", None),
+        ("public_routes", "get_public_routes", None),
+        ("body_limits", "get_body_limits", None),
+        ("rate_limit_rules", "get_rate_limit_rules", None),
+        ("design_packs", "get_design_packs", None),
+        ("migration", "get_migration_status", None),
+        ("openapi_url", "get_openapi_url", None),
+        ("spa_prefixes", "get_spa_prefixes", ()),
+        ("deferred_startup", "get_deferred_startup", None),
+        ("deferred_startup_lock", "get_deferred_startup_lock", None),
+        ("principal_serializer", "get_principal_serializer", None),
+        ("tenant_resolver", "get_tenant_resolver", None),
+        ("tenant_exists", "get_tenant_exists", None),
+        ("tenant_members", "get_tenant_members", None),
+        ("inertia_dependency", "get_inertia_dependency", None),
+        ("inertia_shared_providers", "get_inertia_shared_providers", None),
+        ("branding", "get_branding", None),
+        ("auth", "get_auth_provider", None),
+    ],
+)
+def test_core_optional_app_service(attribute, accessor_name, default):
+    app = FastAPI()
+    accessor = getattr(app_state, accessor_name)
+    assert accessor(app) == default
+
+    installed = object()
+    value = SimpleNamespace(auth_provider=installed) if attribute == "auth" else installed
+    setattr(app.state, attribute, value)
+    assert accessor(app) is installed
+
+    setattr(app.state, attribute, None)
+    assert accessor(app) is None
+
+
+def test_core_partial_auth_state_has_no_provider():
+    app = FastAPI()
+    app.state.auth = SimpleNamespace()
+    assert app_state.get_auth_provider(app) is None
+
+
+def test_core_optional_scope_app_can_lack_state():
+    assert app_state.get_services(None) is None
+    assert app_state.get_services(SimpleNamespace()) is None
+    assert app_state.get_tenant_resolver(None) is None

simple_module_core-0.0.39/tests/test_core_lifecycle_docs.py

@@ -0,0 +1,20 @@
+"""Keep the lifecycle reference complete as ModuleBase gains hooks."""
+
+import inspect
+import re
+from pathlib import Path
+
+from simple_module_core.module import ModuleBase
+
+
+def test_every_public_registration_hook_is_documented():
+    root = Path(__file__).resolve().parents[3]
+    document = (root / "docs/framework/lifecycle.md").read_text(encoding="utf-8")
+    hooks = {
+        name
+        for name, _ in inspect.getmembers(ModuleBase, predicate=inspect.isfunction)
+        if name.startswith("register_")
+    }
+    documented = set(re.findall(r"\bregister_\w+\b", document))
+
+    assert not (missing := hooks - documented), f"Undocumented lifecycle hooks: {sorted(missing)}"

simple_module_core-0.0.39/tests/test_events_inline.py

@@ -0,0 +1,38 @@
+"""Explicit inline fallback preserves transaction ownership and error propagation."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+from simple_module_core.durable_events import DurableContext
+from simple_module_core.events import EventBus
+from simple_module_core.tenant_events import TenantDeleted
+
+
+@pytest.mark.parametrize("transport", [False, True])
+async def test_durable_or_inline_dispatch(transport):
+    bus = EventBus()
+    db = object()
+    event = TenantDeleted("id", "slug", "Name")
+    handlers = [AsyncMock(), AsyncMock()]
+    for index, handler in enumerate(handlers):
+        bus.subscribe_durable(TenantDeleted, handler, name=str(index))
+    ordinary = AsyncMock()
+    bus.subscribe(TenantDeleted, ordinary)
+    if transport:
+        bus.durable_transport = AsyncMock()
+    await bus.publish_durable_or_inline(event, db)
+    for handler in handlers:
+        if transport:
+            handler.assert_not_awaited()
+        else:
+            handler.assert_awaited_once_with(event, DurableContext(db=db, attempt=1))
+    ordinary.assert_not_awaited()
+    if transport:
+        bus.durable_transport.enqueue.assert_awaited_once_with(event, ["0", "1"], db)
+
+
+async def test_inline_failure_propagates():
+    bus = EventBus()
+    bus.subscribe_durable(TenantDeleted, AsyncMock(side_effect=ValueError("failed")), name="fail")
+    with pytest.raises(ValueError, match="failed"):
+        await bus.publish_durable_or_inline(TenantDeleted("id", "slug", "Name"), object())