simple-module-settings 0.0.36__tar.gz → 0.0.37__tar.gz

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/.gitignore

@@ -64,3 +64,4 @@ host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
 .verify/
+/openapi.json

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_settings
-Version: 0.0.36
+Version: 0.0.37
 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
@@ -21,9 +21,9 @@ 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.36
-Requires-Dist: simple-module-db==0.0.36
-Requires-Dist: simple-module-hosting==0.0.36
+Requires-Dist: simple-module-core==0.0.37
+Requires-Dist: simple-module-db==0.0.37
+Requires-Dist: simple-module-hosting==0.0.37
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_settings"
-version = "0.0.36"
+version = "0.0.37"
 description = "Runtime settings UI — modules plug their own settings panels into a shared admin view"
 readme = "README.md"
 license = "MIT"
@@ -21,9 +21,9 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.36",
-    "simple_module_db==0.0.36",
-    "simple_module_hosting==0.0.36",
+    "simple_module_core==0.0.37",
+    "simple_module_db==0.0.37",
+    "simple_module_hosting==0.0.37",
     "typer>=0.12",
 ]
 

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/settings/_module_settings.py

@@ -19,6 +19,7 @@ from settings._field_meta import choices_for, env_readable_var, resolve_default
 from settings._secrets import (  # noqa: F401
     _NEVER_SECRET_TYPES,
     SECRET_MASK,
+    annotation_holds_secret,
     conceals_secret,
     embeds_credential,
     is_named_secret,
@@ -26,7 +27,7 @@ from settings._secrets import (  # noqa: F401
     mask,
 )
 from settings.env_vars import env_prefix_for
-from settings.hydrate import value_type_for_field
+from settings.hydrate import env_supplied_fields, input_type_for_field, value_type_for_field
 from settings.service import SettingService
 
 
@@ -71,22 +72,28 @@ class ModuleSettingField:
     """
     choices: list[str] | None = None
     """Closed set of accepted values, or ``None`` when the field is free text."""
+    input_type: str = ""
+    """Editor control: ``type`` with an ``X | None`` unwrapped to ``X``."""
+    nullable: bool = False
+    """``None`` is a valid value; the editor sends it for an empty input."""
 
     @property
     def source(self) -> str:
         """Where the live value came from: ``db``, ``env`` or ``default``.
 
-        Mirrors the precedence in ``hydrate_settings``: DB overrides are passed
-        to the constructor explicitly, so they beat anything pydantic reads for
-        fields left unset, which in turn beats the field default. ``env`` only
-        appears for settings classes that actually declare an ``env_prefix``;
-        see :attr:`env_set`. Showing this is the difference between "why is
-        this not taking effect" being a five-minute question and an afternoon.
+        Mirrors the precedence in ``hydrate_settings``: env → DB → default
+        (GH #486). A stored override for a field the environment sets is
+        ignored, so ``env`` wins even when ``db_override`` is true. ``env`` only
+        appears for settings classes that declare an ``env_prefix`` (or name
+        the field in ``env_seeded_fields``) — the same rule
+        ``hydrate.env_supplied_fields`` applies; see :attr:`env_set`. Showing
+        this is the difference between "why is this not taking effect" being a
+        five-minute question and an afternoon.
         """
-        if self.db_override:
-            return "db"
         if self.env_set:
             return "env"
+        if self.db_override:
+            return "db"
         return "default"
 
 
@@ -126,28 +133,41 @@ def _field_view(
     settings: BaseSettings,
     prefix: str,
     overridden: frozenset[str] = frozenset(),
+    env_supplied: frozenset[str] | None = None,
 ) -> ModuleSettingField:
     cls = type(settings)
+    if env_supplied is None:
+        env_supplied = env_supplied_fields(cls)
     info = cls.model_fields[name]
     raw_value = getattr(settings, name)
     value_type = value_type_for_field(cls, name)
+    input_type, nullable = input_type_for_field(cls, name)
     named_secret = is_named_secret(name, value_type)
     extra = info.json_schema_extra if isinstance(info.json_schema_extra, dict) else {}
     default = resolve_default(info)
     env_var = f"{prefix}{name.upper()}"
     live_env_var = env_readable_var(settings, name)
-    env_set = live_env_var is not None and live_env_var in os.environ
-    # ``live_env_var`` is not None whenever env_set is True, but the narrowing
-    # is spelled out so a future edit cannot turn this into ``os.environ[None]``.
-    raw_env = os.environ[live_env_var] if env_set and live_env_var is not None else None
+    # The same answer ``build_settings`` acts on (GH #486), so a value supplied
+    # by the class's ``.env``, a secrets file or an alias is labelled "env"
+    # here exactly when hydration lets it beat a stored override.
+    env_set = name in env_supplied
+    raw_env = os.environ.get(live_env_var) if env_set and live_env_var is not None else None
+
+    # Declared as ``SecretStr`` (also inside ``X | None`` or a container):
+    # masked whatever the field is called, since the store holds it in clear.
+    typed_secret = annotation_holds_secret(info.annotation)
 
     def hidden(value: Any) -> bool:
-        return conceals_secret(name, value, value_type)
+        return typed_secret or conceals_secret(name, value, value_type)
 
     # ``is_secret`` drives the editor's input type and the "reveal" affordance,
     # so it has to be true when *any* of the three readings is being hidden —
     # otherwise the form offers to edit a value it is showing as dots.
-    secret = named_secret or any(embeds_credential(v) for v in (raw_value, default, raw_env))
+    secret = (
+        typed_secret
+        or named_secret
+        or any(embeds_credential(v) for v in (raw_value, default, raw_env))
+    )
     return ModuleSettingField(
         name=name,
         env_var=env_var,
@@ -166,6 +186,8 @@ def _field_view(
         # Resolved value panel's env row into a row of dots for every key.
         env_value=(mask(raw_env) if hidden(raw_env) else raw_env) if raw_env is not None else None,
         choices=choices_for(info),
+        input_type=input_type,
+        nullable=nullable,
     )
 
 
@@ -228,8 +250,10 @@ def _build_view(
 ) -> ModuleSettingsView:
     prefix = env_prefix_for(package)
     overridden = (overrides or {}).get(package, frozenset())
+    from_env = env_supplied_fields(type(settings))
     fields = [
-        _field_view(name, settings, prefix, overridden) for name in type(settings).model_fields
+        _field_view(name, settings, prefix, overridden, from_env)
+        for name in type(settings).model_fields
     ]
     return ModuleSettingsView(
         module_name=module_name,

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/settings/_module_settings_props.py

@@ -49,6 +49,8 @@ def serialize(views: list[ModuleSettingsView]) -> list[dict[str, Any]]:
                     # Turns a pattern-constrained string into a select rather
                     # than a text box whose only feedback on a typo is a 422.
                     "choices": f.choices,
+                    "input_type": f.input_type or f.type,
+                    "nullable": f.nullable,
                 }
                 for f in v.fields
             ],

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/settings/_secrets.py

@@ -9,9 +9,11 @@ be reasoned about without a FastAPI app in scope. Re-exported from
 from __future__ import annotations
 
 import re
-from typing import Any
+from typing import Any, get_args, get_origin
 from urllib.parse import urlsplit
 
+from pydantic import BaseModel, SecretBytes, SecretStr
+
 # 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.
@@ -25,6 +27,41 @@ SECRET_MASK = "••••••••"
 _NEVER_SECRET_TYPES = frozenset({"int", "float", "bool"})
 
 
+# ``<package>.<field>`` keys whose declared type holds a ``SecretStr`` /
+# ``SecretBytes``. Filled by ``ModuleSettingsRegistry.register`` so the row
+# browser, tenant view and known-keys list — which see only a key and a stored
+# string — mask them too. Only ever grows; keys are package-qualified.
+_TYPED_SECRET_KEYS: set[str] = set()
+
+
+def annotation_holds_secret(annotation: Any, _seen: frozenset[type] = frozenset()) -> bool:
+    """True if a ``SecretStr``/``SecretBytes`` sits anywhere in ``annotation``.
+
+    Walks unions (``SecretStr | None``), containers (``dict[str, SecretStr]``)
+    and nested models. Since json fields store the real secret (GH #487
+    review), a field typed this way must be masked whatever its name.
+    """
+    if get_origin(annotation) is None and isinstance(annotation, type):
+        if issubclass(annotation, SecretStr | SecretBytes):
+            return True
+        if issubclass(annotation, BaseModel) and annotation not in _seen:
+            seen = _seen | {annotation}
+            return any(
+                annotation_holds_secret(f.annotation, seen)
+                for f in annotation.model_fields.values()
+            )
+    return any(annotation_holds_secret(arg, _seen) for arg in get_args(annotation))
+
+
+def register_typed_secrets(package: str, cls: type[BaseModel]) -> None:
+    """Record which of ``cls``'s fields are secrets by type."""
+    _TYPED_SECRET_KEYS.update(
+        f"{package}.{name}"
+        for name, info in cls.model_fields.items()
+        if annotation_holds_secret(info.annotation)
+    )
+
+
 def is_secret_field(name: str) -> bool:
     """True if a field name suggests it holds credential material."""
     return bool(_SECRET_PATTERNS.search(name))
@@ -49,11 +86,14 @@ def is_named_secret(name: str, value_type: str | None = None) -> bool:
 def conceals_secret(name: str, value: Any, value_type: str | None = None) -> bool:
     """True if this name/value pair must be masked on the way out.
 
-    The one rule every read path shares: mask per *value* as well as per name,
+    The one rule every read path shares: mask per *type* (a registered
+    ``<package>.<field>`` declared as a secret), per *value* and per name,
     so a DSN carrying a password is hidden even on a field called
     ``broker_url``, while that field's password-free default is still shown.
     """
-    return is_named_secret(name, value_type) or embeds_credential(value)
+    return (
+        name in _TYPED_SECRET_KEYS or is_named_secret(name, value_type) or embeds_credential(value)
+    )
 
 
 def embeds_credential(value: Any) -> bool:

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/settings/endpoints/module_api.py

@@ -11,6 +11,7 @@ from typing import Any
 
 from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response, status
 from pydantic import ValidationError
+from simple_module_hosting.i18n_deps import TranslatorDep
 from simple_module_hosting.permissions import RequiresPermission
 
 from settings._module_settings import (
@@ -23,7 +24,7 @@ from settings.constants import MODULE_PACKAGE, PERM_DELETE, PERM_EDIT, PERM_VIEW
 from settings.contracts.events import SettingsReloaded
 from settings.deps import get_setting_service
 from settings.hydrate import hydrate_settings
-from settings.reload import apply_changes_and_reload
+from settings.reload import EnvPinnedError, apply_changes_and_reload
 from settings.service import SettingService
 from settings.store import SettingsStore
 
@@ -90,6 +91,7 @@ async def update_module(
     package: str,
     changes: dict[str, Any],
     request: Request,
+    t: TranslatorDep,
     service: SettingService = Depends(get_setting_service),
 ) -> dict[str, Any]:
     registry = getattr(request.app.state, MODULE_PACKAGE).module_registry
@@ -116,9 +118,21 @@ async def update_module(
     except ValidationError as exc:
         # ``exc.errors()`` still leaves ``ctx.error`` holding the raw Python
         # exception (not JSON-serializable). Round-trip through pydantic's
-        # own JSON encoder to get clean, serializable errors.
-        clean = json.loads(exc.json(include_url=False))
+        # own JSON encoder to get clean, serializable errors. ``input`` is
+        # dropped: it echoes the submitted value, which may be a secret.
+        clean = json.loads(exc.json(include_url=False, include_input=False))
         raise HTTPException(status_code=422, detail=clean) from exc
+    except EnvPinnedError as exc:
+        # Shaped like a pydantic 422 so the editor shows it on the field.
+        detail = [
+            {
+                "loc": ["body", name],
+                "msg": t.t("settings.modules_form.env_pinned"),
+                "type": "env_pinned",
+            }
+            for name in exc.fields
+        ]
+        raise HTTPException(status_code=422, detail=detail) from exc
     except KeyError as exc:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
 

simple_module_settings-0.0.37/settings/hydrate.py

@@ -0,0 +1,223 @@
+"""Resolve a module's BaseSettings from DB overrides + pydantic defaults.
+
+A field's declared Python type maps to one of the five ``value_type`` labels
+understood by SettingsStore (``string | bool | int | float | json``). The
+hydrator reads overrides, parses each according to its stored ``value_type``,
+and constructs the BaseSettings — pydantic enforces field validators and any
+``@model_validator`` hooks.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import types
+from typing import Union, get_args, get_origin
+
+from pydantic import BaseModel, ValidationError
+from pydantic_core import ErrorDetails
+from pydantic_settings import (
+    BaseSettings,
+    DotEnvSettingsSource,
+    EnvSettingsSource,
+    InitSettingsSource,
+    SecretsSettingsSource,
+)
+from sqlalchemy.orm import Session
+
+from settings.store import SettingsStore, get_overrides_sync
+
+logger = logging.getLogger(__name__)
+
+_SCALAR_TYPES = {bool: "bool", int: "int", float: "float"}
+
+#: ``ctx`` key on a validation error listing the *other* fields a cross-field
+#: rule depends on; raise it with ``PydanticCustomError(type, msg, {key: [...]})``.
+#: Lenient hydration drops those when the reported field is not from the DB.
+RELATED_FIELDS_CTX = "related_fields"
+
+
+def value_type_for_field(cls: type[BaseSettings], field_name: str) -> str:
+    """Return the ``value_type`` label for a field based on its annotation.
+
+    - ``bool`` → ``"bool"``
+    - ``int`` → ``"int"``
+    - ``float`` → ``"float"``
+    - ``str`` and enums → ``"string"``
+    - ``list``, ``dict``, and other container types → ``"json"``
+    """
+    info = cls.model_fields[field_name]
+    ann = info.annotation
+    origin = get_origin(ann)
+    if origin is not None:
+        return "json"
+    return _SCALAR_TYPES.get(ann, "string")
+
+
+def _holds_structure(ann: object) -> bool:
+    """A bare ``dict``/``list``/model: not editable as a single-line string."""
+    return isinstance(ann, type) and issubclass(
+        ann, dict | list | set | frozenset | tuple | BaseModel
+    )
+
+
+def input_type_for_field(cls: type[BaseSettings], field_name: str) -> tuple[str, bool]:
+    """``(input_type, nullable)`` — which editor control a field needs.
+
+    Storage stays on :func:`value_type_for_field`, which files every union
+    under ``json``. That is right for the store and wrong for the form:
+    ``int | None`` wants a number box where empty means ``None``, not a JSON
+    textarea that shows the literal text ``null`` (GH #487).
+    """
+    ann = cls.model_fields[field_name].annotation
+    if get_origin(ann) not in (Union, types.UnionType):
+        return value_type_for_field(cls, field_name), False
+    args = get_args(ann)
+    rest = [a for a in args if a is not type(None)]
+    nullable = len(rest) < len(args)
+    if len(rest) == 1 and get_origin(rest[0]) is None:
+        only = rest[0]
+        if _holds_structure(only):
+            return "json", nullable
+        return _SCALAR_TYPES.get(only, "string"), nullable
+    return "json", nullable
+
+
+def _parse(raw: str, value_type: str):
+    if value_type == "bool":
+        return raw.lower() in ("1", "true", "yes", "on")
+    if value_type == "int":
+        return int(raw)
+    if value_type == "float":
+        return float(raw)
+    if value_type == "json":
+        return json.loads(raw)
+    return raw
+
+
+def env_supplied_fields(cls: type[BaseSettings]) -> frozenset[str]:
+    """Fields the class's own non-init sources (env, ``.env``, secrets) answer.
+
+    Asks the sources ``cls`` actually installs, so a ``DbBackedSettings``
+    (init-only) reports nothing and an ``env_prefix`` class reports exactly the
+    ``<PREFIX><FIELD>`` names that are set. Deliberately not ``cls()``: a
+    model validator can reject the env-only view (a production broker check)
+    that the DB-merged one would pass.
+
+    A class with no ``env_prefix`` reports nothing from its sources: a plain
+    ``BaseSettings`` reads bare, case-insensitive names, so a field called
+    ``user``, ``home`` or ``path`` would be pinned by the process environment
+    and every admin edit refused. Only its ``env_seeded_fields`` count.
+    """
+    found: set[str] = set()
+    if cls.model_config.get("env_prefix"):
+        found.update(_source_supplied_fields(cls))
+    # A class may also read env through a ``default_factory`` (one shared
+    # variable seeding several fields), which no source can see. It names
+    # those fields itself, so env still beats the DB for them.
+    seeded = getattr(cls, "env_seeded_fields", None)
+    if callable(seeded):
+        found.update(seeded())
+    return frozenset(found) & cls.model_fields.keys()
+
+
+def _source_supplied_fields(cls: type[BaseSettings]) -> set[str]:
+    sources = cls.settings_customise_sources(
+        cls,
+        init_settings=InitSettingsSource(cls, init_kwargs={}),
+        env_settings=EnvSettingsSource(cls),
+        dotenv_settings=DotEnvSettingsSource(cls),
+        file_secret_settings=SecretsSettingsSource(cls),
+    )
+    by_key = {(info.alias or name): name for name, info in cls.model_fields.items()}
+    found: set[str] = set()
+    for source in sources:
+        if isinstance(source, InitSettingsSource):
+            continue
+        found.update(by_key.get(key, key) for key in source())
+    return found
+
+
+def build_settings[T: BaseSettings](
+    cls: type[T], raw_overrides: dict[str, tuple[str, str]], *, lenient: bool = False
+) -> T:
+    """Construct ``cls`` from ``{field: (raw, value_type)}``, skipping unknown fields.
+
+    Shared by the async and sync hydrators so parsing cannot drift.
+
+    Strict by default: an invalid stored value raises, which is what a settings
+    write relies on to answer 422. ``lenient=True`` is for *boot* paths (web
+    lifespan, workers): a row that was stored before a validator tightened must
+    not take the app down, nor discard the module's other, valid overrides. Each
+    offending field is logged and ignored (it falls back to env/default).
+
+    Precedence is env → DB → default (GH #486). pydantic-settings ranks init
+    kwargs above its env source, so a stored override for a field the
+    environment sets is dropped here rather than passed in.
+    """
+    from_env = env_supplied_fields(cls)
+    parsed: dict[str, object] = {}
+    for field_name, (raw, vtype) in raw_overrides.items():
+        if field_name not in cls.model_fields or field_name in from_env:
+            continue
+        try:
+            parsed[field_name] = _parse(raw, vtype)
+        except ValueError:
+            if not lenient:
+                raise
+            logger.error(
+                "Ignoring stored %s.%s: cannot parse as %s", cls.__name__, field_name, vtype
+            )
+    if not lenient:
+        return cls(**parsed)
+    try:
+        return cls(**parsed)
+    except ValidationError as exc:
+        culprits = {name: err["type"] for err in exc.errors() for name in _culprits(err, parsed)}
+        if not culprits:
+            raise
+        for name in sorted(culprits):
+            logger.error(
+                "Ignoring stored value for %s.%s: it no longer validates (%s)",
+                cls.__name__,
+                name,
+                # error *type* only: a validator's message may echo the value (a secret)
+                culprits[name],
+            )
+        return cls(**{k: v for k, v in parsed.items() if k not in culprits})
+
+
+def _culprits(error: ErrorDetails, parsed: dict[str, object]) -> list[str]:
+    """The stored keys to drop so that ``error`` goes away.
+
+    The field the error is reported on, when its value came from the DB.
+    Otherwise — that field is env-pinned or defaulted — the stored fields the
+    validator names under ``ctx[RELATED_FIELDS_CTX]``: a cross-field rule
+    reported on one field (so the editor shows it there) whose other half came
+    from the DB, which is the only half lenient hydration can drop (#548).
+    """
+    loc = str(error["loc"][0]) if error["loc"] else None
+    if loc in parsed:
+        return [loc]
+    related = (error.get("ctx") or {}).get(RELATED_FIELDS_CTX, ())
+    return [name for name in related if name in parsed]
+
+
+async def hydrate_settings[T: BaseSettings](
+    cls: type[T], store: SettingsStore, package: str, *, lenient: bool = False
+) -> T:
+    """Construct ``cls`` with DB overrides merged over pydantic defaults."""
+    return build_settings(cls, await store.get_overrides(package), lenient=lenient)
+
+
+def hydrate_settings_sync[T: BaseSettings](
+    cls: type[T], session: Session, package: str, *, lenient: bool = False
+) -> T:
+    """Sync :func:`hydrate_settings` for Celery workers and other non-async code.
+
+    Workers never run the hosting lifespan, so a bare ``cls()`` there returns
+    pydantic defaults (``DbBackedSettings`` ignores the environment on purpose).
+    Takes a plain sync ``Session`` and applies the same SYSTEM-scope overrides
+    with the same ``value_type`` parsing as the web process.
+    """
+    return build_settings(cls, get_overrides_sync(session, package), lenient=lenient)

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/settings/locales/en.json

@@ -119,7 +119,7 @@
     "env_var_hint": "Environment variable name for this field, used by \"smpy settings import-from-env\"",
     "env_var_not_read_hint": "{env_var} is a label only — this module reads its settings from the database, never from the environment",
     "source_db": "overridden in DB",
-    "source_db_over_env": "overridden in DB · shadows env",
+    "source_db_ignored_for_env": "stored in DB · env var wins",
     "secret_write_only": "write-only · never returned",
     "head_title": "Module settings",
     "managed_title": "Managed on its own page",
@@ -130,9 +130,16 @@
     "save": "Save",
     "saving": "Saving…",
     "saved_toast": "Settings saved",
+    "validation_failed": "These settings could not be saved",
+    "save_failed": "Saving failed. Try again.",
     "requires_restart": "Requires restart",
     "reset_to_default": "Revert",
-    "set_new_value": "Set new value"
+    "set_new_value": "Set new value",
+    "invalid_json": "Not valid JSON — it will be rejected on save.",
+    "not_set": "Not set (default)",
+    "option_on": "On",
+    "option_off": "Off",
+    "env_pinned": "Set by an environment variable, which takes precedence. Change it there."
   },
   "nav": {
     "settings": "Settings"

{simple_module_settings-0.0.36 → simple_module_settings-0.0.37}/settings/module_registry.py

@@ -11,6 +11,8 @@ from dataclasses import dataclass, field
 
 from pydantic_settings import BaseSettings
 
+from settings._secrets import register_typed_secrets
+
 
 @dataclass(slots=True)
 class ModuleSettingsRegistry:
@@ -28,6 +30,7 @@ class ModuleSettingsRegistry:
         if package in self._classes:
             raise ValueError(f"{package!r} already registered")
         self._classes[package] = cls
+        register_typed_secrets(package, cls)
         if manage_url:
             self._manage_urls[package] = manage_url