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

{simple_module_core-0.0.37 → simple_module_core-0.0.38}/.gitignore

@@ -7,8 +7,6 @@ build/
 .venv/
 *.egg
 
-# UV
-uv.lock
 
 # Node
 node_modules/
@@ -65,3 +63,4 @@ host/client_app/.playwright-cli/*
 .qa/
 .verify/
 /openapi.json
+qa-shots/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_core
-Version: 0.0.37
+Version: 0.0.38
 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
@@ -22,7 +22,7 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: babel>=2.14
-Requires-Dist: fastapi>=0.115
+Requires-Dist: fastapi<0.157,>=0.140
 Requires-Dist: packaging>=23.0
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: pydantic>=2.0

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

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.37"
+version = "0.0.38"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"
@@ -22,7 +22,7 @@ classifiers = [
 ]
 dependencies = [
     "babel>=2.14",
-    "fastapi>=0.115",
+    "fastapi>=0.140,<0.157",
     "packaging>=23.0",
     "pydantic>=2.0",
     "pydantic-settings>=2.0",

{simple_module_core-0.0.37 → simple_module_core-0.0.38}/simple_module_core/__init__.py

@@ -2,6 +2,7 @@
 
 from simple_module_core.audit_links import AuditLink, AuditLinkRegistry, LabelResolver
 from simple_module_core.body_limits import BodyLimitRegistry
+from simple_module_core.cors import CorsPolicy, CorsPolicyRegistry
 from simple_module_core.csp import CspSourceError, CspSourceRegistry
 from simple_module_core.design_packs import DesignPack, DesignPackRegistry
 from simple_module_core.diagnostics import (
@@ -14,6 +15,7 @@ from simple_module_core.discovery import (
     DEFAULT_AUTH_PROVIDER,
     discover_modules,
     get_module_package_name,
+    missing_dependencies,
     resolve_auth_provider,
     select_auth_provider,
     topological_sort,
@@ -28,6 +30,7 @@ from simple_module_core.exceptions import (
     CircularDependencyError,
     FrameworkVersionError,
     InvalidModuleError,
+    MissingDependencyError,
     ModuleError,
     NotFoundError,
     ValidationError,
@@ -51,8 +54,15 @@ from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
 from simple_module_core.module import ModuleBase, ModuleMeta
 from simple_module_core.permissions import PermissionRegistry
 from simple_module_core.public_routes import PublicRoute, PublicRouteRegistry
+from simple_module_core.resources import (
+    ResourcePolicy,
+    ResourcePrincipal,
+    ResourceType,
+    ResourceTypeRegistry,
+)
 from simple_module_core.services import Services
 from simple_module_core.setup_steps import SetupAction, SetupField, SetupRegistry, SetupStep
+from simple_module_core.spa_mount import SpaMount
 from simple_module_core.tenancy import TENANT_ROLE_PREFIX, TenantRole, is_tenant_role, tenant_role
 from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
 
@@ -64,6 +74,8 @@ __all__ = [
     "AuditLinkRegistry",
     "BodyLimitRegistry",
     "CircularDependencyError",
+    "CorsPolicy",
+    "CorsPolicyRegistry",
     "CspSourceError",
     "CspSourceRegistry",
     "DesignPack",
@@ -91,6 +103,7 @@ __all__ = [
     "MenuRegistry",
     "MenuSection",
     "MigrationDiagnostics",
+    "MissingDependencyError",
     "ModuleBase",
     "ModuleError",
     "ModuleMeta",
@@ -98,11 +111,16 @@ __all__ = [
     "PermissionRegistry",
     "PublicRoute",
     "PublicRouteRegistry",
+    "ResourcePolicy",
+    "ResourcePrincipal",
+    "ResourceType",
+    "ResourceTypeRegistry",
     "Services",
     "SetupAction",
     "SetupField",
     "SetupRegistry",
     "SetupStep",
+    "SpaMount",
     "TenantRole",
     "Translator",
     "ValidationError",
@@ -113,6 +131,7 @@ __all__ = [
     "get_module_package_name",
     "is_flag_enabled",
     "is_tenant_role",
+    "missing_dependencies",
     "print_diagnostics",
     "require_flag",
     "resolve_auth_provider",

{simple_module_core-0.0.37 → simple_module_core-0.0.38}/simple_module_core/__main__.py

@@ -30,6 +30,7 @@ from simple_module_core.diagnostics import (
     print_diagnostics,
     run_diagnostics,
 )
+from simple_module_core.diagnostics._dependencies import CODE as MISSING_DEPENDENCY_CODE
 from simple_module_core.diagnostics._i18n import unknown_overrides_for
 from simple_module_core.discovery import (
     discover_modules,
@@ -181,6 +182,11 @@ def main() -> int:
         database_dialect=_database_dialect(),
     )
     diagnostics.extend(override_findings)
+    # A missing dependency only warns at a dev boot, but production refuses
+    # to start with it (GH #501), so doctor reports it as what it will be.
+    for finding in diagnostics:
+        if finding.code == MISSING_DEPENDENCY_CODE:
+            finding.level = DiagnosticLevel.ERROR
     print_diagnostics(diagnostics)
 
     errors = [d for d in diagnostics if d.level == DiagnosticLevel.ERROR]

simple_module_core-0.0.38/simple_module_core/_i18n_translator.py

@@ -0,0 +1,107 @@
+"""Request-scoped translator and CLDR plural resolution."""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any
+
+from babel import Locale
+
+if TYPE_CHECKING:
+    from simple_module_core.i18n import I18nRegistry
+
+# 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")
+
+
+@lru_cache(maxsize=64)
+def _plural_rule(locale: str):
+    """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)
+
+
+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

simple_module_core-0.0.38/simple_module_core/_permission_grants.py

@@ -0,0 +1,74 @@
+"""Permission primitives: the wildcard grant rule, the admin role and grant-source types."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Collection, Iterable
+from typing import Any
+
+PermissionSourceProvider = Callable[[], "Iterable[str] | Iterable[tuple[str, str]]"]
+"""Sync callable returning permission keys, or ``(key, label)`` pairs."""
+
+WILDCARD = "*"
+
+ADMIN_ROLE = "admin"
+"""The one role name the framework itself knows.
+
+Everything else about roles is module-owned, but the framework needs this to
+resolve the wildcard grant below and to decide who can still reach the app
+while maintenance mode is on.
+"""
+
+# Default role→permission mapping. Admin gets all permissions via the wildcard.
+# Additional mappings are added at registration time via PermissionRegistry.map_role.
+DEFAULT_ROLE_PERMISSIONS: dict[str, list[str]] = {
+    ADMIN_ROLE: [WILDCARD],
+}
+
+
+def is_admin(roles: list[str] | None) -> bool:
+    """Whether ``roles`` carries the framework's admin role."""
+    return bool(roles) and ADMIN_ROLE in roles
+
+
+def is_admin_principal(user: Any) -> bool:
+    """Whether *user* may use the admin role's shortcuts — admin and not a token.
+
+    A principal carrying ``scopes`` (an ``api_tokens`` credential) is capped
+    at those scopes even when its owner is an admin, so every check that
+    admits admins on the role alone must use this rather than
+    :func:`is_admin`; otherwise an admin's ``feature_flags.view`` token would
+    still open the Doctor page. Duck-typed: ``UserContext`` lives in the auth
+    module, which framework code must not import.
+    """
+    if user is None or getattr(user, "scopes", None) is not None:
+        return False
+    return is_admin(getattr(user, "roles", None))
+
+
+def grants(held: Collection[str], required: str) -> bool:
+    """Whether a principal holding *held* satisfies *required*.
+
+    One place for the wildcard rule, so code that gates something *inside* a
+    response — a column, a label, a card — reads the grant the same way
+    ``RequiresPermission`` reads it at the door. Two hand-rolled ``in`` checks
+    are two chances to forget that ``admin`` holds ``*`` and nothing else.
+
+    An empty *required* is satisfied by anything: callers use it to mean "no
+    permission gates this", which is the default for a declaration that never
+    named one.
+    """
+    if not required:
+        return True
+    return WILDCARD in held or required in held
+
+
+GrantSource = Callable[[Any, Any], Awaitable[Collection[str]]]
+"""``async (request, user) -> keys`` — permissions a principal holds beyond its roles.
+
+How a module that stores grants of its own (``permissions``' per-user grants)
+gets them into the one set every check reads, without the framework importing
+it (SM009). Called once per authenticated request by
+``simple_module_hosting.permissions.resolve_principal_permissions``, so a
+source that reads the database must cache: it sits on the hot path of every
+page load.
+"""

simple_module_core-0.0.38/simple_module_core/_request_hooks.py

@@ -0,0 +1,103 @@
+"""Request-pipeline registration hooks, split out of ``ModuleBase``.
+
+Everything a module declares about how HTTP requests reach it -- anonymous
+routes, body ceilings, CSP origins, CORS policies, rate limits, middleware and
+exception handlers. ``ModuleBase`` inherits this mixin, so ``from
+simple_module_core.module import ModuleBase`` and every override are unchanged.
+All hooks are no-ops by default and run once at boot, in dependency order.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from simple_module_core.body_limits import BodyLimitRegistry
+    from simple_module_core.cors import CorsPolicyRegistry
+    from simple_module_core.csp import CspSourceRegistry
+    from simple_module_core.public_routes import PublicRouteRegistry
+    from simple_module_core.rate_limit import RateLimitRegistry
+
+
+class RequestHooksMixin:
+    def register_public_routes(self, registry: PublicRouteRegistry) -> None:
+        """Declare routes that must bypass authentication (anonymous access).
+
+        ``AuthMiddleware`` gates every request behind the active auth provider.
+        Override this hook to exempt read-only or webhook routes that are meant
+        to be reached without a session — e.g. a STAC / OGC API surface::
+
+            def register_public_routes(self, registry):
+                registry.add_prefix("/api/gis/stac")
+                registry.add_regex(r"/api/gis/datasets/[^/]+/tilejson$", methods={"GET"})
+
+        Rules are method-aware, so a GET read route nested under a prefix that
+        also carries POST/PATCH mutations can be exempted without opening the
+        mutations. Called once at boot, in dependency order.
+        """
+
+    def register_body_limits(self, registry: BodyLimitRegistry) -> None:
+        """Per-route request-body ceilings; see docs/framework/request-guards.md."""
+
+    def register_csp_sources(self, registry: CspSourceRegistry) -> None:
+        """Declare external origins this module's frontend loads assets from.
+
+        The host ships a strict Content-Security-Policy; a module whose
+        pages pull a stylesheet, font, or API from another origin must
+        declare it here or the browser blocks the request::
+
+            def register_csp_sources(self, registry):
+                registry.add("style-src", "https://rsms.me")
+                registry.add("font-src", "https://rsms.me")
+
+        Fetch directives only; invalid declarations raise at boot. Runs once,
+        *before* DB settings hydrate — for an origin read from settings use
+        ``registry.add_provider(lambda app: [(directive, source)])`` (sync,
+        in-memory state only, evaluated per response).
+        """
+
+    def register_middleware(self, app: FastAPI) -> None:
+        """Add middleware to the application.
+
+        Called after core middleware (session, security headers) positioning
+        is established but before the app starts.
+        """
+
+    def register_exception_handlers(self, app: FastAPI) -> None:
+        """Register custom exception handlers (after the framework's own)."""
+
+    def register_cors_policies(self, registry: CorsPolicyRegistry) -> None:
+        """Declare cross-origin policies for this module's routes.
+
+        The host already allows its configured origins on ``/api/``; override
+        this for a surface with different rules, e.g. publicly served files::
+
+            def register_cors_policies(self, registry):
+                registry.add_prefix(
+                    "/files/public/",
+                    CorsPolicy(origins=("*",), allow_credentials=False, methods=("GET", "HEAD")),
+                    enabled=lambda: self._public_cors_on(),
+                )
+
+        The most specific path match wins (exact, regex, longest prefix);
+        ``enabled`` is evaluated per request. A wildcard origin cannot be
+        combined with credentials. Called once at boot, in dependency order.
+        """
+
+    def register_rate_limits(self, registry: RateLimitRegistry) -> None:
+        """Declare per-route rate limits for this module's endpoints.
+
+        ::
+
+            def register_rate_limits(self, registry):
+                registry.add_exact(
+                    "/api/orders/export", RateLimitRule("5/minute", key="user")
+                )
+
+        ``key`` picks who shares a budget: the signed-in user, the client IP,
+        ``user_or_ip`` (user when signed in, else IP) or the active tenant.
+        The most specific path match wins. Called once at boot, in dependency
+        order.
+        """

simple_module_core-0.0.38/simple_module_core/activity_feed.py

@@ -0,0 +1,75 @@
+"""The activity feed: "what has this person done lately", without the audit log.
+
+The users edit page shows a card of the account's recent actions. The audit log
+is what records them, but ``users`` must not import ``audit_log`` (and
+``audit_log`` must not import ``users``): each is optional to the other, and
+importing both ways was a cycle (GH #501).
+
+So ``audit_log`` registers an :class:`ActivityFeed` with
+:func:`set_activity_feed` and the card asks :func:`get_activity_feed`. ``None``
+means nothing records activity on this install — a card that is absent, which
+is a different claim from an empty one ("nobody did anything").
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+
+ACTIVITY_FEED_STATE_ATTR = "activity_feed"
+"""``app.state`` attribute holding the active :class:`ActivityFeed`."""
+
+
+@dataclass(frozen=True)
+class ActivityItem:
+    """One thing an actor did."""
+
+    at: datetime
+    action: str
+    entity_type: str
+    entity_id: str
+    #: The row's display name, when its owner can name it and the reader may
+    #: see that name; ``None`` otherwise (the caller shows a short id).
+    entity_label: str | None = None
+    #: The recorded change set, whatever its shape, for summarising which
+    #: fields moved. ``None`` when the recorder kept none.
+    changes: Any = None
+
+
+@runtime_checkable
+class ActivityFeed(Protocol):
+    async def recent_for_actor(
+        self,
+        db: Any,
+        actor_id: str,
+        *,
+        limit: int,
+        permissions: Collection[str],
+    ) -> list[ActivityItem]:
+        """The latest *limit* actions by *actor_id*, newest first.
+
+        *permissions* are the reader's grants: labels whose owner gated them
+        behind a permission the reader lacks come back as ``None``.
+        """
+        ...
+
+
+def set_activity_feed(app: Any, feed: ActivityFeed | None) -> None:
+    """Install (or, with ``None``, remove) the app's activity feed."""
+    setattr(app.state, ACTIVITY_FEED_STATE_ATTR, feed)
+
+
+def get_activity_feed(app: Any) -> ActivityFeed | None:
+    """The app's activity feed, or ``None`` when nothing records activity."""
+    return getattr(app.state, ACTIVITY_FEED_STATE_ATTR, None)
+
+
+__all__ = [
+    "ACTIVITY_FEED_STATE_ATTR",
+    "ActivityFeed",
+    "ActivityItem",
+    "get_activity_feed",
+    "set_activity_feed",
+]

{simple_module_core-0.0.37 → simple_module_core-0.0.38}/simple_module_core/audit_links.py

@@ -108,6 +108,33 @@ class AuditLink:
                 f"every row would link to the same page"
             )
 
+    @classmethod
+    def for_model(
+        cls,
+        model: type,
+        *,
+        url_template: str,
+        label: str = "",
+        label_key: str = "",
+        label_resolver: LabelResolver | None = None,
+        label_permission: str = "",
+    ) -> AuditLink:
+        """Build the link for a SQLModel table class.
+
+        Fills ``entity_type`` from ``model.__name__`` (the class name, never the
+        table name) and ``table_name`` from ``model.__tablename__``, so a caller
+        cannot key it off the wrong one. ``model`` must be a table model.
+        """
+        return cls(
+            entity_type=model.__name__,
+            url_template=url_template,
+            label=label,
+            label_key=label_key,
+            table_name=model.__tablename__,
+            label_resolver=label_resolver,
+            label_permission=label_permission,
+        )
+
     def url_for(self, entity_id: str) -> str | None:
         """The row's page, or ``None`` when this kind of row has no screen."""
         if not self.url_template:

simple_module_core-0.0.38/simple_module_core/correlation.py

@@ -0,0 +1,12 @@
+"""The request/task correlation id, shared by every layer.
+
+Lives in core rather than ``simple_module_hosting.logging`` (which re-exports
+it) so the db layer can stamp audit records with it without importing the
+hosting package (#498).
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+correlation_id: ContextVar[str] = ContextVar("correlation_id", default="")

simple_module_core-0.0.38/simple_module_core/cors.py

@@ -0,0 +1,71 @@
+"""CORS policy registry: modules declare which origins may call which paths.
+
+The host registers a policy for ``/api/`` from its ``cors_*`` settings; a module
+with a public, cross-origin surface (e.g. publicly served files) adds its own
+through :meth:`~simple_module_core.module.ModuleBase.register_cors_policies`::
+
+    def register_cors_policies(self, registry):
+        registry.add_prefix(
+            "/files/public/",
+            CorsPolicy(origins=("*",), allow_credentials=False, methods=("GET", "HEAD")),
+            enabled=lambda: app_settings.public_files_cors,
+        )
+
+The most specific match wins (exact, then regex, then longest prefix); a tie
+keeps the first registration and logs a warning. ``enabled`` is evaluated per
+request, so a DB-backed toggle needs no restart.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from simple_module_core.path_rules import KIND_EXACT, KIND_PREFIX, KIND_REGEX, PathRuleSet
+
+__all__ = ["CorsPolicy", "CorsPolicyRegistry"]
+
+WILDCARD = "*"
+
+
+@dataclass(frozen=True, slots=True)
+class CorsPolicy:
+    origins: tuple[str, ...]
+    allow_credentials: bool = False
+    methods: tuple[str, ...] = ("GET",)
+    headers: tuple[str, ...] = ()
+    expose_headers: tuple[str, ...] = ()
+    max_age: int = 600
+
+    def __post_init__(self) -> None:
+        if self.allow_credentials and WILDCARD in self.origins:
+            raise ValueError("A CORS policy cannot combine origin '*' with credentials")
+        if self.max_age < 0:
+            raise ValueError("max_age must be >= 0")
+
+
+class CorsPolicyRegistry:
+    def __init__(self) -> None:
+        self._rules: PathRuleSet[CorsPolicy] = PathRuleSet("CORS policy")
+
+    def add_exact(
+        self, path: str, policy: CorsPolicy, *, enabled: Callable[[], bool] | None = None
+    ) -> None:
+        self._rules.add(KIND_EXACT, path, policy, enabled=enabled)
+
+    def add_prefix(
+        self, prefix: str, policy: CorsPolicy, *, enabled: Callable[[], bool] | None = None
+    ) -> None:
+        self._rules.add(KIND_PREFIX, prefix, policy, enabled=enabled)
+
+    def add_regex(
+        self, pattern: str, policy: CorsPolicy, *, enabled: Callable[[], bool] | None = None
+    ) -> None:
+        self._rules.add(KIND_REGEX, pattern, policy, enabled=enabled)
+
+    def match(self, method: str, path: str) -> CorsPolicy | None:
+        """The governing policy for this request, or ``None`` (no CORS headers)."""
+        return self._rules.match(method, path)
+
+    def __len__(self) -> int:
+        return len(self._rules)