simple-module-settings 0.0.1__tar.gz

simple_module_settings-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/

simple_module_settings-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_module_settings-0.0.1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: simple_module_settings
+Version: 0.0.1
+Summary: Runtime settings UI — modules plug their own settings panels into a shared admin view
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,configuration,settings,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: simple-module-hosting==0.0.1
+Description-Content-Type: text/markdown
+
+# simple_module_settings
+
+Runtime settings UI for [simple_module](https://github.com/antosubash/simple_module_python) apps. Other modules plug their own settings panels into a shared admin view — one page per module tab — without the host having to know about them.
+
+## Install
+
+```bash
+pip install simple_module_settings
+```
+
+## What it provides
+
+- `/settings` admin page aggregating every installed module's settings panel.
+- `register_settings_panel()` hook — a module declares `{title, inertia_page, requires_permission}`; `simple_module_settings` renders the tab.
+- DB-backed runtime settings table (separate from env-var-driven `SM_*` settings) for values admins change at runtime.
+
+## Usage
+
+Register a panel:
+
+```python
+class OrdersModule(ModuleBase):
+    meta = ModuleMeta(name="orders")
+
+    def register_settings_panel(self):
+        return {
+            "title": "Orders",
+            "inertia_page": "Orders/SettingsPanel",
+            "requires_permission": "orders.manage",
+        }
+```
+
+That adds an **Orders** tab at `/settings`. The rendered page is a regular Inertia page authored inside the `orders` module.
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_settings-0.0.1/README.md

@@ -0,0 +1,41 @@
+# simple_module_settings
+
+Runtime settings UI for [simple_module](https://github.com/antosubash/simple_module_python) apps. Other modules plug their own settings panels into a shared admin view — one page per module tab — without the host having to know about them.
+
+## Install
+
+```bash
+pip install simple_module_settings
+```
+
+## What it provides
+
+- `/settings` admin page aggregating every installed module's settings panel.
+- `register_settings_panel()` hook — a module declares `{title, inertia_page, requires_permission}`; `simple_module_settings` renders the tab.
+- DB-backed runtime settings table (separate from env-var-driven `SM_*` settings) for values admins change at runtime.
+
+## Usage
+
+Register a panel:
+
+```python
+class OrdersModule(ModuleBase):
+    meta = ModuleMeta(name="orders")
+
+    def register_settings_panel(self):
+        return {
+            "title": "Orders",
+            "inertia_page": "Orders/SettingsPanel",
+            "requires_permission": "orders.manage",
+        }
+```
+
+That adds an **Orders** tab at `/settings`. The rendered page is a regular Inertia page authored inside the `orders` module.
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_settings-0.0.1/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@simple-module-py/settings",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the Settings module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

simple_module_settings-0.0.1/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "simple_module_settings"
+version = "0.0.1"
+description = "Runtime settings UI — modules plug their own settings panels into a shared admin view"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "settings", "admin", "configuration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "simple_module_core==0.0.1",
+    "simple_module_db==0.0.1",
+    "simple_module_hosting==0.0.1",
+]
+
+[project.entry-points.simple_module]
+settings = "settings.module:SettingsModule"
+
+[project.scripts]
+sm-settings = "settings.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+Changelog = "https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["settings"]
+
+# Ship the module-root package.json inside the wheel so the host can
+# discover JS deps via importlib.resources after a pip install.
+[tool.hatch.build.targets.wheel.force-include]
+"package.json" = "settings/package.json"
+
+[tool.uv.sources]
+simple_module_core = { workspace = true }
+simple_module_db = { workspace = true }
+simple_module_hosting = { workspace = true }

simple_module_settings-0.0.1/settings/__init__.py

@@ -0,0 +1 @@
+"""Settings module."""

simple_module_settings-0.0.1/settings/_module_settings.py

@@ -0,0 +1,169 @@
+"""Autodiscover per-module pydantic ``BaseSettings`` attached to ``app.state``.
+
+Each module stores a services dataclass on ``app.state.<package>`` whose
+``.settings`` attribute is a pydantic ``BaseSettings`` subclass.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings
+
+from settings.env_vars import env_prefix_for
+from settings.hydrate import value_type_for_field
+
+# We intentionally DON'T match the bare word "token" (would mask
+# `verification_token_lifetime_seconds` — just an int) or "key" alone (would
+# mask `s3_bucket_key_prefix`). Only fragments that actually indicate material.
+_SECRET_PATTERNS = re.compile(
+    r"(password|secret|api[_-]?key|private[_-]?key|token[_-]?secret)", re.I
+)
+SECRET_MASK = "••••••••"
+
+
+def is_secret_field(name: str) -> bool:
+    """True if a field name suggests it holds credential material."""
+    return bool(_SECRET_PATTERNS.search(name))
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleSettingField:
+    name: str
+    env_var: str
+    value: Any
+    default: Any
+    description: str
+    is_secret: bool
+    type: str
+    requires_restart: bool
+    group: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleSettingsView:
+    module_name: str
+    package: str
+    env_prefix: str
+    class_name: str
+    fields: list[ModuleSettingField]
+
+
+def _mask(value: Any) -> Any:
+    if value in (None, "", [], {}):
+        return value
+    return SECRET_MASK
+
+
+def _package_of(mod: Any) -> str:
+    return type(mod).__module__.split(".", 1)[0]
+
+
+def _extract_settings(app: FastAPI, package: str) -> BaseSettings | None:
+    """Return the ``BaseSettings`` instance attached to ``app.state.<package>``.
+
+    The services dataclass exposes it as ``.settings``. We also accept the
+    rare case where the module stashes the settings object directly.
+    """
+    services = getattr(app.state, package, None)
+    if services is None:
+        return None
+    if isinstance(services, BaseSettings):
+        return services
+    inner = getattr(services, "settings", None)
+    return inner if isinstance(inner, BaseSettings) else None
+
+
+def _field_view(name: str, settings: BaseSettings, prefix: str) -> ModuleSettingField:
+    cls = type(settings)
+    info = cls.model_fields[name]
+    raw_value = getattr(settings, name)
+    secret = is_secret_field(name)
+    extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
+    return ModuleSettingField(
+        name=name,
+        env_var=f"{prefix}{name.upper()}",
+        value=_mask(raw_value) if secret else raw_value,
+        default=_mask(info.default) if secret else info.default,
+        description=info.description or "",
+        is_secret=secret,
+        type=value_type_for_field(cls, name),
+        requires_restart=bool(extra.get("requires_restart", False)),
+        group=extra.get("group"),
+    )
+
+
+def collect_module_settings(app: FastAPI) -> list[ModuleSettingsView]:
+    """Return a sorted, serializable view of every module's BaseSettings.
+
+    Folds in both ``app.state.sm.modules`` (plugin modules) and additional
+    packages registered via ``app.state.settings.module_registry`` (e.g.
+    ``"host"``) that aren't backed by a ``ModuleBase`` instance.
+    """
+    views: list[ModuleSettingsView] = []
+    seen: set[str] = set()
+
+    for mod in getattr(app.state.sm, "modules", ()):
+        package = _package_of(mod)
+        settings = _extract_settings(app, package)
+        if settings is None:
+            continue
+        views.append(_build_view(mod.meta.name, package, settings))
+        seen.add(package)
+
+    settings_services = getattr(app.state, "settings", None)
+    registry = getattr(settings_services, "module_registry", None)
+    if registry is not None:
+        for package in registry.all_packages():
+            if package in seen:
+                continue
+            settings = _extract_settings(app, package)
+            if settings is None:
+                continue
+            views.append(_build_view(package.title(), package, settings))
+            seen.add(package)
+
+    views.sort(key=lambda v: v.module_name)
+    return views
+
+
+def _build_view(module_name: str, package: str, settings: BaseSettings) -> ModuleSettingsView:
+    prefix = env_prefix_for(package)
+    fields = [_field_view(name, settings, prefix) for name in type(settings).model_fields]
+    return ModuleSettingsView(
+        module_name=module_name,
+        package=package,
+        env_prefix=prefix,
+        class_name=type(settings).__name__,
+        fields=fields,
+    )
+
+
+def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
+    """Convert dataclass views to plain dicts for Inertia props."""
+    return [
+        {
+            "module_name": v.module_name,
+            "package": v.package,
+            "env_prefix": v.env_prefix,
+            "class_name": v.class_name,
+            "fields": [
+                {
+                    "name": f.name,
+                    "env_var": f.env_var,
+                    "value": f.value,
+                    "default": f.default,
+                    "description": f.description,
+                    "is_secret": f.is_secret,
+                    "type": f.type,
+                    "requires_restart": f.requires_restart,
+                    "group": f.group,
+                }
+                for f in v.fields
+            ],
+        }
+        for v in views
+    ]

simple_module_settings-0.0.1/settings/cli.py

@@ -0,0 +1,78 @@
+"""``sm-settings`` CLI — currently only ``import-from-env``.
+
+One-shot migration: walks every registered module's ``BaseSettings`` and,
+for each field whose legacy ``SM_<PREFIX>_<FIELD>`` env var is set, writes
+a SYSTEM-scoped override into the Settings store.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from fastapi import FastAPI
+
+from settings.constants import MODULE_PACKAGE
+from settings.env_vars import env_prefix_for
+from settings.hydrate import value_type_for_field
+from settings.store import SettingsStore
+
+
+async def import_from_env_impl(app: FastAPI, store: SettingsStore) -> int:
+    """Write a SYSTEM override for every ``SM_<PREFIX>_<FIELD>`` env var set.
+
+    Returns the count of overrides written. Env vars that don't match a
+    registered field are ignored.
+    """
+    registry = getattr(app.state, MODULE_PACKAGE).module_registry
+    count = 0
+    for package, cls in registry.items():
+        prefix = env_prefix_for(package)
+        for field_name in cls.model_fields:
+            raw = os.environ.get(f"{prefix}{field_name.upper()}")
+            if raw is None:
+                continue
+            vtype = value_type_for_field(cls, field_name)
+            await store.set_override(package, field_name, raw, vtype)
+            count += 1
+    return count
+
+
+def main() -> int:
+    """Console-script entry point for ``sm-settings``.
+
+    Supports a single subcommand: ``import-from-env``.
+    """
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ("-h", "--help"):
+        print("Usage: sm-settings import-from-env")
+        return 0 if argv else 1
+    if argv[0] != "import-from-env":
+        print(f"Unknown command: {argv[0]}", file=sys.stderr)
+        print("Usage: sm-settings import-from-env", file=sys.stderr)
+        return 2
+
+    from simple_module_hosting.app_builder import create_app
+    from simple_module_hosting.settings import Settings
+
+    from settings.service import SettingService
+
+    app = create_app(Settings())
+
+    async def run() -> int:
+        async with (
+            app.router.lifespan_context(app),
+            app.state.sm.db.session_factory() as session,
+        ):
+            store = SettingsStore(SettingService(session))
+            n = await import_from_env_impl(app, store)
+            await session.commit()
+            print(f"Imported {n} override(s) from environment.")
+        return 0
+
+    return asyncio.run(run())
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simple_module_settings-0.0.1/settings/constants.py

@@ -0,0 +1,115 @@
+"""Centralized constants for the Settings module.
+
+Keeps module-level strings (route prefixes, permission ids, table names,
+menu metadata, error messages, field limits, env prefix, i18n namespace,
+scope identifiers) in one place so nothing is duplicated in Python or
+inline-literal'd at call sites.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# ── Module identity ──────────────────────────────────────────────────
+MODULE_NAME: Final = "Settings"
+MODULE_PACKAGE: Final = "settings"
+ENV_PREFIX: Final = "SM_SETTINGS_"
+LOCALE_NAMESPACE: Final = MODULE_PACKAGE
+
+# ── Scopes ───────────────────────────────────────────────────────────
+# Precedence high → low when resolving a key: USER > TENANT > SYSTEM.
+SCOPE_SYSTEM: Final = "system"
+SCOPE_TENANT: Final = "tenant"
+SCOPE_USER: Final = "user"
+ALL_SCOPES: Final = (SCOPE_SYSTEM, SCOPE_TENANT, SCOPE_USER)
+# scope_id is empty for SYSTEM; empty string (not NULL) so composite unique
+# works uniformly on SQLite and PostgreSQL (NULL breaks uniqueness on PG).
+SYSTEM_SCOPE_ID: Final = ""
+
+# ── Value types ──────────────────────────────────────────────────────
+# Values are always stored as strings; ``value_type`` tells consumers how
+# to interpret the bytes and lets the UI pick the right input control.
+VALUE_TYPE_STRING: Final = "string"
+VALUE_TYPE_BOOL: Final = "bool"
+VALUE_TYPE_INT: Final = "int"
+VALUE_TYPE_FLOAT: Final = "float"
+VALUE_TYPE_JSON: Final = "json"
+ALL_VALUE_TYPES: Final = (
+    VALUE_TYPE_STRING,
+    VALUE_TYPE_BOOL,
+    VALUE_TYPE_INT,
+    VALUE_TYPE_FLOAT,
+    VALUE_TYPE_JSON,
+)
+
+# ── Routing ──────────────────────────────────────────────────────────
+API_PREFIX: Final = "/api/settings"
+VIEW_PREFIX: Final = "/settings"
+VIEW_CREATE_PATH: Final = "/create"
+VIEW_EDIT_PATH: Final = "/{setting_id}/edit"
+VIEW_MODULES_PATH: Final = "/modules"
+API_BY_ID_PATH: Final = "/{setting_id}"
+API_BY_KEY_PATH: Final = "/by-key/{key}"
+API_RESOLVE_PATH: Final = "/resolve/{key}"
+API_SYSTEM_PATH: Final = "/system/{key}"
+API_TENANT_PATH: Final = "/tenant/{scope_id}/{key}"
+API_USER_PATH: Final = "/user/{scope_id}/{key}"
+
+# ── Menu ─────────────────────────────────────────────────────────────
+MENU_LABEL: Final = MODULE_NAME
+MENU_URL: Final = VIEW_PREFIX
+MENU_ICON: Final = "settings"
+MENU_ORDER: Final = 30
+
+# ── Permissions ──────────────────────────────────────────────────────
+PERM_GROUP: Final = MODULE_NAME
+PERM_VIEW: Final = "settings.view"
+PERM_CREATE: Final = "settings.create"
+PERM_EDIT: Final = "settings.edit"
+PERM_DELETE: Final = "settings.delete"
+ALL_PERMISSIONS: Final = (PERM_VIEW, PERM_CREATE, PERM_EDIT, PERM_DELETE)
+
+# ── Database ─────────────────────────────────────────────────────────
+DB_SCHEMA: Final = MODULE_PACKAGE
+TABLE_SETTING: Final = "settings_setting"
+UQ_SCOPE_KEY: Final = "uq_settings_setting_scope_scope_id_key"
+
+# ── Field limits ─────────────────────────────────────────────────────
+KEY_MAX_LENGTH: Final = 200
+VALUE_MAX_LENGTH: Final = 4000
+DESCRIPTION_MAX_LENGTH: Final = 2000
+SCOPE_MAX_LENGTH: Final = 10
+SCOPE_ID_MAX_LENGTH: Final = 255
+VALUE_TYPE_MAX_LENGTH: Final = 10
+
+# ── Inertia page component names ─────────────────────────────────────
+PAGE_BROWSE: Final = f"{MODULE_NAME}/Browse"
+PAGE_CREATE: Final = f"{MODULE_NAME}/Create"
+PAGE_EDIT: Final = f"{MODULE_NAME}/Edit"
+PAGE_MODULES_EDIT: Final = f"{MODULE_NAME}/ModulesEdit"
+
+# ── Inertia prop keys ────────────────────────────────────────────────
+PROP_SETTINGS: Final = "settings"
+PROP_SETTING: Final = "setting"
+PROP_MODULES: Final = "modules"
+PROP_ERROR: Final = "error"
+
+# ── User-facing error messages ───────────────────────────────────────
+ERR_SETTING_NOT_FOUND: Final = "Setting not found"
+ERR_KEY_ALREADY_EXISTS: Final = "Setting key already exists"
+ERR_SYSTEM_SCOPE_NO_ID: Final = "system scope must not have a scope_id"
+ERR_SCOPED_REQUIRES_ID: Final = "tenant/user scope requires a scope_id"
+ERR_UNKNOWN_SCOPE: Final = "unknown scope"
+ERR_VALUE_MISMATCH: Final = "value does not parse as declared value_type"
+
+# ── HTTP ─────────────────────────────────────────────────────────────
+STATUS_CREATED: Final = 201
+STATUS_NO_CONTENT: Final = 204
+STATUS_NOT_FOUND: Final = 404
+STATUS_CONFLICT: Final = 409
+
+# ── Query parameter names ────────────────────────────────────────────
+QP_USER_ID: Final = "user_id"
+QP_TENANT_ID: Final = "tenant_id"
+QP_SCOPE: Final = "scope"
+QP_SCOPE_ID: Final = "scope_id"

simple_module_settings-0.0.1/settings/contracts/__init__.py

@@ -0,0 +1,24 @@
+"""Settings contracts — public interface for other modules."""
+
+from settings.contracts.accessor import SettingsAccessor
+from settings.contracts.registry import SettingDefinition, SettingsRegistry
+from settings.contracts.schemas import (
+    SettingCreate,
+    SettingOut,
+    SettingScope,
+    SettingUpdate,
+    SettingUpsert,
+    SettingValueType,
+)
+
+__all__ = [
+    "SettingCreate",
+    "SettingDefinition",
+    "SettingOut",
+    "SettingScope",
+    "SettingUpdate",
+    "SettingUpsert",
+    "SettingValueType",
+    "SettingsAccessor",
+    "SettingsRegistry",
+]