simple-module-core 0.0.24__tar.gz → 0.0.26__tar.gz

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_core
-Version: 0.0.24
+Version: 0.0.26
 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
@@ -63,6 +63,7 @@ class OrdersModule(ModuleBase):
 
     def register_routes(self, api_router, view_router):
         from .endpoints import api, views
+
         api_router.include_router(api.router)
         view_router.include_router(views.router)
 ```

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/README.md

@@ -32,6 +32,7 @@ class OrdersModule(ModuleBase):
 
     def register_routes(self, api_router, view_router):
         from .endpoints import api, views
+
         api_router.include_router(api.router)
         view_router.include_router(views.router)
 ```

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_core"
-version = "0.0.24"
+version = "0.0.26"
 description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
 readme = "README.md"
 license = "MIT"

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/simple_module_core/__init__.py

@@ -1,5 +1,6 @@
 """SimpleModule Core - Module system, menu, permissions, events, and diagnostics."""
 
+from simple_module_core.design_packs import DesignPack, DesignPackRegistry
 from simple_module_core.diagnostics import (
     DiagnosticLevel,
     MigrationDiagnostics,
@@ -40,6 +41,8 @@ from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework
 __all__ = [
     "FRAMEWORK_API_VERSION",
     "CircularDependencyError",
+    "DesignPack",
+    "DesignPackRegistry",
     "DiagnosticLevel",
     "Event",
     "EventBus",

simple_module_core-0.0.26/simple_module_core/design_packs.py

@@ -0,0 +1,88 @@
+"""Design-pack registry — modules contribute a selectable look for the public site.
+
+A *design pack* is a stylesheet a module ships that restyles the reader-facing
+site by overriding the base design tokens beneath a ``<value>-root`` class. A
+module declares the packs it provides via
+:meth:`~simple_module_core.module.ModuleBase.register_design_packs`; the host
+collects them into one registry at boot and stores it on
+``app.state.design_packs``.
+
+**The registry supplies the dropdown, not the stylesheet.** A pack's CSS still
+reaches the bundle through the host's ``styles.css`` importing it by package
+specifier. The registry's only job is to stop an administrator selecting a pack
+that no installed module provides — which would otherwise put a class on the
+document with nothing behind it and silently do nothing.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+"""A pack slug: lowercase alphanumerics and dashes, not starting with a dash.
+
+The site root class is ``f"{value}-root"``, so the slug has to be usable as a
+bare CSS identifier fragment.
+"""
+
+
+@dataclass(frozen=True)
+class DesignPack:
+    """One selectable look.
+
+    Args:
+        value: Slug identifying the pack. The public site's root element
+            carries ``f"{value}-root"``, which is the hook the pack's own
+            stylesheet selects on.
+        label: Human-readable name, shown in the branding dropdown.
+    """
+
+    value: str
+    label: str
+
+    def __post_init__(self) -> None:
+        if not SLUG_RE.match(self.value):
+            raise ValueError(
+                f"DesignPack value {self.value!r} is not a usable class-name "
+                f"fragment; it must match {SLUG_RE.pattern}"
+            )
+
+
+class DesignPackRegistry:
+    """Aggregates every module's :class:`DesignPack` declarations.
+
+    Populated once during boot (``register_design_packs`` hook) and read
+    thereafter — by the branding view to build its dropdown, and by the
+    branding API to validate a submitted slug.
+    """
+
+    def __init__(self) -> None:
+        self._packs: dict[str, DesignPack] = {}
+
+    def register(self, pack: DesignPack) -> None:
+        """Add *pack*, rejecting a slug another module already claimed.
+
+        Duplicate slugs are an error rather than a silent overwrite: two packs
+        sharing one root class would leave whichever stylesheet happened to
+        load last in charge, which is not something an administrator could
+        diagnose from the UI.
+        """
+        existing = self._packs.get(pack.value)
+        if existing is not None:
+            raise ValueError(
+                f"Design pack {pack.value!r} is already registered "
+                f"(as {existing.label!r}); slugs must be unique across modules"
+            )
+        self._packs[pack.value] = pack
+
+    def all(self) -> list[DesignPack]:
+        """Every registered pack, in registration order (a copy)."""
+        return list(self._packs.values())
+
+    def has(self, value: str) -> bool:
+        """Return ``True`` if some module registered a pack with this slug."""
+        return value in self._packs
+
+
+__all__ = ["DesignPack", "DesignPackRegistry"]

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/simple_module_core/module.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from fastapi import APIRouter, FastAPI
 
+    from simple_module_core.design_packs import DesignPackRegistry
     from simple_module_core.events import EventBus
     from simple_module_core.feature_flags import FeatureFlagRegistry
     from simple_module_core.health import HealthRegistry
@@ -137,6 +138,22 @@ class ModuleBase(ABC):
         mutations. Called once at boot, in dependency order.
         """
 
+    def register_design_packs(self, registry: DesignPackRegistry) -> None:
+        """Declare design packs this module ships for the public site.
+
+        A design pack is a stylesheet that restyles the reader-facing site by
+        overriding the base tokens beneath a ``<value>-root`` class. Override
+        this hook to make the pack selectable in branding::
+
+            def register_design_packs(self, registry):
+                registry.register(DesignPack(value="gca", label="Canopy Atlas"))
+
+        Registering only advertises the pack — the stylesheet itself still
+        reaches the bundle through the host's ``styles.css``. Slugs are unique
+        across modules; a collision raises at boot. Called once, in dependency
+        order.
+        """
+
     def register_middleware(self, app: FastAPI) -> None:
         """Add middleware to the application.
 

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/simple_module_core/services.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
     from simple_module_db.session import DatabaseState
     from simple_module_hosting.settings import Settings
 
+    from simple_module_core.design_packs import DesignPackRegistry
     from simple_module_core.events import EventBus
     from simple_module_core.feature_flags import FeatureFlagRegistry
     from simple_module_core.health import HealthRegistry
@@ -42,6 +43,7 @@ class Services:
     feature_flags: FeatureFlagRegistry
     health_registry: HealthRegistry
     public_routes: PublicRouteRegistry
+    design_packs: DesignPackRegistry
     i18n_registry: I18nRegistry
     inertia_config: InertiaConfig
     modules: tuple[ModuleBase, ...]

simple_module_core-0.0.26/tests/test_design_packs.py

@@ -0,0 +1,105 @@
+"""Tests for DesignPackRegistry — modules contribute site-wide design packs.
+
+A design pack is a stylesheet a module ships that restyles the public site by
+overriding the base tokens beneath a ``<value>-root`` class. The registry is
+what lets branding offer an administrator only the packs an installed module
+actually provides: selecting one nothing ships would put a class on the
+document with no stylesheet behind it, silently doing nothing.
+
+The registry supplies the dropdown, not the stylesheet — a pack's CSS still
+reaches the bundle through the host's ``styles.css``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+from simple_module_core.design_packs import DesignPack, DesignPackRegistry
+
+
+class TestDesignPack:
+    def test_carries_slug_and_label(self):
+        pack = DesignPack(value="gca", label="Canopy Atlas")
+        assert pack.value == "gca"
+        assert pack.label == "Canopy Atlas"
+
+    def test_is_frozen(self):
+        pack = DesignPack(value="gca", label="Canopy Atlas")
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            pack.value = "other"
+
+    @pytest.mark.parametrize("value", ["gca", "g", "7", "canopy-atlas", "a1-b2"])
+    def test_accepts_a_css_safe_slug(self, value):
+        assert DesignPack(value=value, label="X").value == value
+
+    @pytest.mark.parametrize(
+        "value",
+        ["", "-gca", "GCA", "canopy_atlas", "canopy atlas", "gca!", "gca.pack"],
+    )
+    def test_rejects_a_slug_that_would_not_survive_a_class_name(self, value):
+        # The site root class is f"{value}-root", so anything that isn't a bare
+        # lowercase CSS identifier fragment either fails to select or, worse,
+        # silently selects something else.
+        with pytest.raises(ValueError, match="value"):
+            DesignPack(value=value, label="X")
+
+
+class TestDesignPackRegistry:
+    def test_starts_empty(self):
+        assert DesignPackRegistry().all() == []
+
+    def test_registered_pack_is_returned(self):
+        registry = DesignPackRegistry()
+        pack = DesignPack(value="gca", label="Canopy Atlas")
+        registry.register(pack)
+        assert registry.all() == [pack]
+
+    def test_all_preserves_registration_order(self):
+        registry = DesignPackRegistry()
+        first = DesignPack(value="gca", label="Canopy Atlas")
+        second = DesignPack(value="aurora", label="Aurora")
+        registry.register(first)
+        registry.register(second)
+        assert registry.all() == [first, second]
+
+    def test_all_returns_a_copy(self):
+        registry = DesignPackRegistry()
+        registry.register(DesignPack(value="gca", label="Canopy Atlas"))
+        registry.all().clear()
+        assert len(registry.all()) == 1
+
+    def test_duplicate_value_is_rejected(self):
+        # Two modules claiming one root class would leave whichever stylesheet
+        # loaded last in charge — a silent overwrite is the wrong answer.
+        registry = DesignPackRegistry()
+        registry.register(DesignPack(value="gca", label="Canopy Atlas"))
+        with pytest.raises(ValueError, match="gca"):
+            registry.register(DesignPack(value="gca", label="Someone Else's Pack"))
+
+    def test_distinct_values_sharing_a_label_are_allowed(self):
+        registry = DesignPackRegistry()
+        registry.register(DesignPack(value="gca", label="Atlas"))
+        registry.register(DesignPack(value="gca-dark", label="Atlas"))
+        assert [p.value for p in registry.all()] == ["gca", "gca-dark"]
+
+    def test_has_reports_membership(self):
+        # Branding's PUT validates the submitted slug against this.
+        registry = DesignPackRegistry()
+        registry.register(DesignPack(value="gca", label="Canopy Atlas"))
+        assert registry.has("gca")
+        assert not registry.has("aurora")
+
+    def test_has_is_false_on_an_empty_registry(self):
+        assert not DesignPackRegistry().has("gca")
+
+
+class TestPublicSurface:
+    def test_both_names_are_exported_from_the_package_root(self):
+        # Module authors import registries from ``simple_module_core``, the
+        # same way they reach MenuRegistry or PublicRouteRegistry.
+        import simple_module_core
+
+        assert simple_module_core.DesignPack is DesignPack
+        assert simple_module_core.DesignPackRegistry is DesignPackRegistry
+        assert {"DesignPack", "DesignPackRegistry"} <= set(simple_module_core.__all__)

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/tests/test_module_base.py

@@ -125,6 +125,28 @@ class TestModuleNewHooks:
         assert reg.matches("GET", "/api/with-public/datasets/9/tilejson")
         assert not reg.matches("PATCH", "/api/with-public/datasets/9/tilejson")
 
+    async def test_register_design_packs_default_noop(self):
+        from simple_module_core.design_packs import DesignPackRegistry
+
+        mod = DummyModule()
+        reg = DesignPackRegistry()
+        mod.register_design_packs(reg)
+        assert reg.all() == []
+
+    async def test_register_design_packs_override(self):
+        from simple_module_core.design_packs import DesignPack, DesignPackRegistry
+
+        class ModWithPack(ModuleBase):
+            meta = ModuleMeta(name="WithPack")
+
+            def register_design_packs(self, registry):
+                registry.register(DesignPack(value="with-pack", label="With Pack"))
+
+        reg = DesignPackRegistry()
+        ModWithPack().register_design_packs(reg)
+        assert reg.has("with-pack")
+        assert [p.label for p in reg.all()] == ["With Pack"]
+
 
 class TestModuleAssetHooks:
     async def test_template_dirs_default_empty(self):

{simple_module_core-0.0.24 → simple_module_core-0.0.26}/tests/test_services.py

@@ -30,6 +30,7 @@ class TestServices:
         assert s.feature_flags is _SENTINEL_FLAGS
         assert s.health_registry is _SENTINEL_HEALTH
         assert s.public_routes is _SENTINEL_PUBLIC_ROUTES
+        assert s.design_packs is _SENTINEL_DESIGN_PACKS
         assert s.i18n_registry is _SENTINEL_I18N
         assert s.inertia_config is _SENTINEL_INERTIA
         assert s.modules == ()
@@ -43,6 +44,7 @@ _SENTINEL_PERMS = object()
 _SENTINEL_FLAGS = object()
 _SENTINEL_HEALTH = object()
 _SENTINEL_PUBLIC_ROUTES = object()
+_SENTINEL_DESIGN_PACKS = object()
 _SENTINEL_I18N = object()
 _SENTINEL_INERTIA = object()
 
@@ -58,6 +60,7 @@ def _make_services() -> Services:
         feature_flags=_SENTINEL_FLAGS,  # type: ignore[arg-type]
         health_registry=_SENTINEL_HEALTH,  # type: ignore[arg-type]
         public_routes=_SENTINEL_PUBLIC_ROUTES,  # type: ignore[arg-type]
+        design_packs=_SENTINEL_DESIGN_PACKS,  # type: ignore[arg-type]
         i18n_registry=_SENTINEL_I18N,  # type: ignore[arg-type]
         inertia_config=_SENTINEL_INERTIA,  # type: ignore[arg-type]
         modules=(),