velocity-python 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.3.1"
+__version__ = version = "0.3.2"
 
 import importlib as _importlib
 

velocity/aws/settings.py

@@ -0,0 +1,1104 @@
+"""Settings catalogs: declared, validated, resolved through levels, audited.
+
+An application describes its business settings once, in a **catalog** (a
+dict or JSON document), and velocity does the generic work around it:
+
+- :class:`Catalog` checks the catalog's shape when it loads;
+- :meth:`Catalog.validate` checks and normalizes one value by its type;
+- :func:`resolve` / :func:`resolve_all` walk a **chain of levels** (most
+  specific first, e.g. form → organization → platform default) and return
+  each value together with the level it came from;
+- :func:`apply` sets or unsets values at one level, validated, and writes one
+  history row per call in the shared change-history table (``audit_log``,
+  :mod:`velocity.db.audit`), with the actor and the time;
+- :func:`history` reads those rows back for one owner and one setting.
+
+Catalog shape::
+
+    {
+      "version": 1,
+      "groups": [{"id": "portal", "label": "Portal"}],
+      "settings": [
+        {"key": "portal.maps", "label": "Maps", "group": "portal",
+         "type": "bool", "default": {"value": false},
+         "levels": ["organization"], "visibility": "internal",
+         "help": "Shows the Maps screen.",
+         "storage": {"column": "show_maps"}},
+        {"key": "captcha.threshold", "label": "Score threshold",
+         "group": "portal", "type": "number", "min": 0, "max": 1, "step": 0.1,
+         "default": {"flag": "default_captcha_threshold"},
+         "levels": ["platform", "organization", "form"]}
+      ]
+    }
+
+- ``key``: dotted lower-case segments (``[a-z][a-z0-9_]*``), unique.
+- ``type``: ``bool``, ``choice`` (``choices``: ``[{"value", "label"}]``),
+  ``number`` / ``integer`` (optional ``min``, ``max``, ``step``), ``text``
+  (optional ``max_length``, ``pattern``), ``time_zone`` (an IANA name) or
+  ``json``. An application adds its own types with ``validators={name:
+  fn(setting, value) -> normalized}`` (a ``ValueError`` refuses the value).
+- ``default``: ``{"flag": <column>}`` (the platform row in
+  ``sys_feature_flags``, read by :func:`platform_level`) or ``{"value": v}``.
+  No default means "no platform value": a value must be set somewhere.
+- ``levels``: the level names that may hold a value for this setting.
+- ``visibility``, ``help``, ``storage`` and any other key are carried as-is
+  (``Setting.extra`` for unknown keys) for the application and the UI.
+
+A **level** (:class:`Level`) is a name and a reader ``read(tx, settings) ->
+{key: value}`` (``None``, ``""`` or a missing key mean "not set here"), plus,
+for a level that can be written, ``write(tx, setting, value)`` and
+``unset(tx, setting)``. :class:`ColumnLevel` stores values in columns of one
+owner row (``storage.column``), :class:`RowLevel` in a key/value table (one
+row per owner and key, JSON value); an application can pass its own.
+
+Nothing here knows any application's business: the catalog, the level names
+and the owners are the caller's.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import math
+import re
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Sequence
+
+from velocity.aws.handlers.exceptions import AlertError
+
+AUDIT_TABLE = "audit_log"
+# The operation written on a settings history row.
+OPERATION = "settings"
+
+TYPES = ("bool", "choice", "number", "integer", "text", "time_zone", "json")
+VISIBILITIES = ("internal", "owner", "member", "public")
+SET = "set"
+UNSET = "unset"
+
+_KEY_RE = re.compile(r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$")
+_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+_COLUMN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+MAX_KEY_LENGTH = 120
+MAX_JSON_BYTES = 64 * 1024
+_TRUE = {"true", "t", "yes", "y", "1", "on"}
+_FALSE = {"false", "f", "no", "n", "0", "off"}
+_KNOWN = {
+    "key",
+    "label",
+    "group",
+    "type",
+    "choices",
+    "min",
+    "max",
+    "step",
+    "max_length",
+    "pattern",
+    "default",
+    "levels",
+    "visibility",
+    "help",
+    "storage",
+}
+
+
+class SettingsError(AlertError, ValueError):
+    """A catalog, value or operation that is refused (HTTP 400 from a handler)."""
+
+
+class SettingMissingError(SettingsError):
+    """A required setting has no value at any level."""
+
+
+def _empty(value) -> bool:
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+# ── catalog ──────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Setting:
+    key: str
+    label: str
+    group: str
+    type: str
+    levels: tuple
+    choices: tuple = ()
+    min: Optional[float] = None
+    max: Optional[float] = None
+    step: Optional[float] = None
+    max_length: Optional[int] = None
+    pattern: Optional[str] = None
+    default: Optional[dict] = None
+    visibility: str = "internal"
+    help: str = ""
+    storage: dict = field(default_factory=dict)
+    extra: dict = field(default_factory=dict)
+
+    @property
+    def default_flag(self) -> Optional[str]:
+        return (self.default or {}).get("flag")
+
+    def choice_values(self) -> list:
+        return [c["value"] for c in self.choices]
+
+    def to_dict(self) -> dict:
+        """The JSON form a UI renders (catalog order, every declared key)."""
+        out = {
+            "key": self.key,
+            "label": self.label,
+            "group": self.group,
+            "type": self.type,
+            "levels": list(self.levels),
+            "visibility": self.visibility,
+            "help": self.help,
+        }
+        if self.choices:
+            out["choices"] = [dict(c) for c in self.choices]
+        for name in ("min", "max", "step", "max_length", "pattern"):
+            if getattr(self, name) is not None:
+                out[name] = getattr(self, name)
+        if self.default is not None:
+            out["default"] = dict(self.default)
+        if self.storage:
+            out["storage"] = dict(self.storage)
+        out.update(self.extra)
+        return out
+
+
+def _number(value, name, key):
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise SettingsError(f"setting {key!r}: {name} must be a number")
+    return value
+
+
+def _parse_setting(raw, groups, custom_types) -> Setting:
+    if not isinstance(raw, Mapping):
+        raise SettingsError("each setting must be an object")
+    key = raw.get("key")
+    if not isinstance(key, str) or len(key) > MAX_KEY_LENGTH or not _KEY_RE.match(key):
+        raise SettingsError(f"invalid setting key {key!r}")
+    stype = raw.get("type")
+    if stype not in TYPES and stype not in custom_types:
+        raise SettingsError(f"setting {key!r}: unknown type {stype!r}")
+    group = raw.get("group")
+    if group not in groups:
+        raise SettingsError(f"setting {key!r}: unknown group {group!r}")
+    label = raw.get("label")
+    if not isinstance(label, str) or not label.strip():
+        raise SettingsError(f"setting {key!r}: a label is required")
+    levels = raw.get("levels")
+    if (
+        not isinstance(levels, (list, tuple))
+        or not levels
+        or not all(isinstance(lv, str) and _ID_RE.match(lv) for lv in levels)
+        or len(set(levels)) != len(levels)
+    ):
+        raise SettingsError(f"setting {key!r}: levels must be distinct level names")
+    choices = raw.get("choices") or ()
+    if stype == "choice":
+        if not isinstance(choices, (list, tuple)) or not choices:
+            raise SettingsError(f"setting {key!r}: a choice needs choices")
+        parsed = []
+        for choice in choices:
+            if isinstance(choice, (str, int, float)) and not isinstance(choice, bool):
+                choice = {"value": choice, "label": str(choice)}
+            if not isinstance(choice, Mapping) or "value" not in choice:
+                raise SettingsError(f"setting {key!r}: invalid choice {choice!r}")
+            parsed.append(
+                {
+                    "value": choice["value"],
+                    "label": str(choice.get("label", choice["value"])),
+                }
+            )
+        values = [c["value"] for c in parsed]
+        if len(set(map(json.dumps, values))) != len(values):
+            raise SettingsError(f"setting {key!r}: duplicate choice values")
+        choices = tuple(parsed)
+    elif choices:
+        raise SettingsError(f"setting {key!r}: only a choice has choices")
+    default = raw.get("default")
+    if default is not None:
+        if not isinstance(default, Mapping) or len(default) != 1:
+            raise SettingsError(
+                f"setting {key!r}: default must be {{'flag': column}} or {{'value': v}}"
+            )
+        if "flag" in default:
+            if not isinstance(default["flag"], str) or not _COLUMN_RE.match(
+                default["flag"]
+            ):
+                raise SettingsError(f"setting {key!r}: invalid default flag")
+        elif "value" not in default:
+            raise SettingsError(
+                f"setting {key!r}: default must be {{'flag': column}} or {{'value': v}}"
+            )
+        default = dict(default)
+    visibility = raw.get("visibility", "internal")
+    if visibility not in VISIBILITIES:
+        raise SettingsError(f"setting {key!r}: unknown visibility {visibility!r}")
+    storage = raw.get("storage") or {}
+    if not isinstance(storage, Mapping):
+        raise SettingsError(f"setting {key!r}: storage must be an object")
+    max_length = raw.get("max_length")
+    if max_length is not None and (
+        isinstance(max_length, bool)
+        or not isinstance(max_length, int)
+        or max_length < 1
+    ):
+        raise SettingsError(f"setting {key!r}: max_length must be a positive integer")
+    pattern = raw.get("pattern")
+    if pattern is not None:
+        try:
+            re.compile(pattern)
+        except (re.error, TypeError):
+            raise SettingsError(f"setting {key!r}: invalid pattern") from None
+    help_text = raw.get("help", "")
+    if not isinstance(help_text, str):
+        raise SettingsError(f"setting {key!r}: help must be text")
+    setting = Setting(
+        key=key,
+        label=label.strip(),
+        group=group,
+        type=stype,
+        levels=tuple(levels),
+        choices=tuple(choices),
+        min=_number(raw.get("min"), "min", key),
+        max=_number(raw.get("max"), "max", key),
+        step=_number(raw.get("step"), "step", key),
+        max_length=max_length,
+        pattern=pattern,
+        default=default,
+        visibility=visibility,
+        help=help_text,
+        storage=dict(storage),
+        extra={k: v for k, v in raw.items() if k not in _KNOWN},
+    )
+    if (
+        setting.min is not None
+        and setting.max is not None
+        and setting.min > setting.max
+    ):
+        raise SettingsError(f"setting {key!r}: min is above max")
+    return setting
+
+
+class Catalog:
+    """A checked settings catalog. Build it with :meth:`load`."""
+
+    def __init__(self, groups, settings, *, version=1, validators=None):
+        self.version = version
+        self.groups = [dict(g) for g in groups]
+        self._settings = {s.key: s for s in settings}
+        self._order = [s.key for s in settings]
+        self.validators = dict(validators or {})
+
+    @classmethod
+    def load(cls, source, *, validators=None) -> "Catalog":
+        """A catalog from a dict, a JSON string or a path to a JSON file.
+
+        ``validators`` maps an application type name to ``fn(setting,
+        value) -> normalized`` (raise ``ValueError`` to refuse a value).
+        Raises :class:`SettingsError` for any shape problem."""
+        if isinstance(source, bytes):
+            source = source.decode("utf-8")
+        if isinstance(source, str):
+            if source.lstrip()[:1] in ("{", "["):
+                try:
+                    source = json.loads(source)
+                except ValueError:
+                    raise SettingsError("the catalog is not valid JSON") from None
+            else:
+                with open(source, encoding="utf-8") as fh:
+                    source = json.load(fh)
+        if not isinstance(source, Mapping):
+            raise SettingsError("the catalog must be an object")
+        validators = dict(validators or {})
+        for name, fn in validators.items():
+            if not (isinstance(name, str) and _ID_RE.match(name)) or not callable(fn):
+                raise SettingsError(f"invalid validator {name!r}")
+        groups = source.get("groups")
+        if not isinstance(groups, (list, tuple)) or not groups:
+            raise SettingsError("the catalog needs groups")
+        group_ids = []
+        for group in groups:
+            if (
+                not isinstance(group, Mapping)
+                or not isinstance(group.get("id"), str)
+                or not _ID_RE.match(group["id"])
+                or not isinstance(group.get("label"), str)
+            ):
+                raise SettingsError(f"invalid group {group!r}")
+            group_ids.append(group["id"])
+        if len(set(group_ids)) != len(group_ids):
+            raise SettingsError("duplicate group ids")
+        raw_settings = source.get("settings")
+        if not isinstance(raw_settings, (list, tuple)):
+            raise SettingsError("the catalog needs a settings list")
+        parsed = [
+            _parse_setting(raw, set(group_ids), validators) for raw in raw_settings
+        ]
+        keys = [s.key for s in parsed]
+        if len(set(keys)) != len(keys):
+            raise SettingsError("duplicate setting keys")
+        catalog = cls(
+            groups,
+            parsed,
+            version=source.get("version", 1),
+            validators=validators,
+        )
+        for setting in parsed:
+            if setting.default and "value" in setting.default:
+                catalog.validate(setting.key, setting.default["value"])
+        return catalog
+
+    def __iter__(self):
+        return (self._settings[k] for k in self._order)
+
+    def __len__(self):
+        return len(self._order)
+
+    def __contains__(self, key):
+        return key in self._settings
+
+    def keys(self) -> List[str]:
+        return list(self._order)
+
+    def get(self, key) -> Setting:
+        try:
+            return self._settings[key]
+        except (KeyError, TypeError):
+            raise SettingsError(f"unknown setting {key!r}") from None
+
+    def by_storage(self, name, value) -> Optional[Setting]:
+        """The setting whose ``storage[name] == value`` (e.g. the setting a
+        column holds), or None."""
+        for setting in self:
+            if setting.storage.get(name) == value:
+                return setting
+        return None
+
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "groups": [dict(g) for g in self.groups],
+            "settings": [s.to_dict() for s in self],
+        }
+
+    # ── validation ───────────────────────────────────────────────────────
+
+    def validate(self, key, value):
+        """``value`` normalized for ``key``'s type, or :class:`SettingsError`.
+        ``None`` / blank text is refused: removing a value is an ``unset``."""
+        setting = key if isinstance(key, Setting) else self.get(key)
+        if _empty(value):
+            raise SettingsError(
+                f"{setting.label}: a value is required (unset to clear)"
+            )
+        custom = self.validators.get(setting.type)
+        try:
+            if custom is not None:
+                return custom(setting, value)
+            return _VALIDATORS[setting.type](setting, value)
+        except SettingsError:
+            raise
+        except (ValueError, TypeError, InvalidOperation) as exc:
+            raise SettingsError(f"{setting.label}: {exc}") from None
+
+
+def _v_bool(setting, value):
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int) and value in (0, 1):
+        return bool(value)
+    if isinstance(value, str):
+        text = value.strip().lower()
+        if text in _TRUE:
+            return True
+        if text in _FALSE:
+            return False
+    raise ValueError("expected true or false")
+
+
+def _v_choice(setting, value):
+    for choice in setting.choices:
+        if choice["value"] == value:
+            return choice["value"]
+    if isinstance(value, str):
+        for choice in setting.choices:
+            if str(choice["value"]) == value.strip():
+                return choice["value"]
+    raise ValueError(
+        "must be one of " + ", ".join(str(v) for v in setting.choice_values())
+    )
+
+
+def _range(setting, number):
+    if setting.min is not None and number < setting.min:
+        raise ValueError(f"must be at least {setting.min}")
+    if setting.max is not None and number > setting.max:
+        raise ValueError(f"must be at most {setting.max}")
+    return number
+
+
+def _v_number(setting, value):
+    if isinstance(value, bool):
+        raise ValueError("expected a number")
+    if isinstance(value, str):
+        value = Decimal(value.strip())
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError("expected a finite number")
+    number = _range(setting, number)
+    return int(number) if number.is_integer() and setting.step in (None, 1) else number
+
+
+def _v_integer(setting, value):
+    if isinstance(value, bool):
+        raise ValueError("expected a whole number")
+    if isinstance(value, str):
+        value = Decimal(value.strip())
+    if isinstance(value, (float, Decimal)) and value != int(value):
+        raise ValueError("expected a whole number")
+    return _range(setting, int(value))
+
+
+def _v_text(setting, value):
+    if not isinstance(value, str):
+        raise ValueError("expected text")
+    text = value.strip()
+    if setting.max_length is not None and len(text) > setting.max_length:
+        raise ValueError(f"must be at most {setting.max_length} characters")
+    if setting.pattern is not None and not re.fullmatch(setting.pattern, text):
+        raise ValueError("is not in the expected format")
+    return text
+
+
+def _v_time_zone(setting, value):
+    from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+    if not isinstance(value, str) or "/" not in value and value.strip() != "UTC":
+        raise ValueError("expected a time zone name such as America/Denver")
+    name = value.strip()
+    try:
+        ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError):
+        raise ValueError(f"unknown time zone {name!r}") from None
+    return name
+
+
+def _v_json(setting, value):
+    if isinstance(value, str):
+        value = json.loads(value)
+    text = json.dumps(value)
+    if len(text.encode("utf-8")) > MAX_JSON_BYTES:
+        raise ValueError("is too large")
+    return json.loads(text)
+
+
+_VALIDATORS = {
+    "bool": _v_bool,
+    "choice": _v_choice,
+    "number": _v_number,
+    "integer": _v_integer,
+    "text": _v_text,
+    "time_zone": _v_time_zone,
+    "json": _v_json,
+}
+
+
+# ── levels ───────────────────────────────────────────────────────────────
+
+
+class Level:
+    """One place a setting's value can come from.
+
+    ``read(tx, settings) -> {key: value}`` (blank or missing = not set).
+    ``write(tx, setting, value)`` / ``unset(tx, setting)`` for a writable
+    level. ``ref(setting) -> str`` names where the value lives (shown as the
+    source). ``count(tx, settings) -> {key: n}`` (optional) counts the
+    owners BELOW this level that set their own value (e.g. forms that
+    override an organization's value), for "overridden on N" labels.
+    ``audit_table_name`` / ``owner_id`` / ``field(setting)`` place this
+    level's history rows (see :func:`apply`)."""
+
+    def __init__(
+        self,
+        name,
+        read,
+        *,
+        write=None,
+        unset=None,
+        ref=None,
+        count=None,
+        audit_table_name=None,
+        owner_id=None,
+        field=None,
+    ):
+        if not isinstance(name, str) or not _ID_RE.match(name):
+            raise SettingsError(f"invalid level name {name!r}")
+        self.name = name
+        self._read = read
+        self._write = write
+        self._unset = unset
+        self._ref = ref
+        self._count = count
+        self.audit_table_name = audit_table_name
+        self.owner_id = owner_id
+        self._field = field
+
+    @property
+    def writable(self) -> bool:
+        return self._write is not None and self._unset is not None
+
+    def read(self, tx, settings) -> dict:
+        values = self._read(tx, list(settings)) or {}
+        return {k: v for k, v in values.items() if not _empty(v)}
+
+    def write(self, tx, setting, value):
+        if self._write is None:
+            raise SettingsError(f"the {self.name} level cannot be written")
+        self._write(tx, setting, value)
+
+    def unset(self, tx, setting):
+        if self._unset is None:
+            raise SettingsError(f"the {self.name} level cannot be written")
+        self._unset(tx, setting)
+
+    def ref(self, setting) -> str:
+        return self._ref(setting) if self._ref else self.name
+
+    def count(self, tx, settings) -> dict:
+        return (self._count(tx, list(settings)) or {}) if self._count else {}
+
+    def field(self, setting) -> str:
+        """The name a history row records this setting's change under."""
+        return self._field(setting) if self._field else setting.key
+
+
+def platform_level(name="platform", *, flags=None) -> Level:
+    """The catalog defaults as a level: ``{"value": v}`` as declared, and
+    ``{"flag": column}`` from the platform row of ``sys_feature_flags``
+    (:func:`velocity.aws.feature_flags.get`, read fresh). ``flags`` replaces
+    that read with ``fn(tx) -> dict``."""
+
+    def read_flags(tx):
+        if flags is not None:
+            return flags(tx) or {}
+        from velocity.aws import feature_flags
+
+        return feature_flags.get(tx) or {}
+
+    def read(tx, settings):
+        out = {}
+        row = None
+        for setting in settings:
+            default = setting.default or {}
+            if "value" in default:
+                out[setting.key] = default["value"]
+            elif "flag" in default:
+                if row is None:
+                    row = read_flags(tx)
+                out[setting.key] = row.get(default["flag"])
+        return out
+
+    def ref(setting):
+        default = setting.default or {}
+        if "flag" in default:
+            return f"sys_feature_flags.{default['flag']}"
+        return "catalog default"
+
+    return Level(name, read, ref=ref)
+
+
+class ColumnLevel(Level):
+    """Values held in columns of one owner row (``storage[column_key]`` names
+    the column; a setting without one is not stored at this level).
+
+    Writes coerce to the column's declared type where it is text (a number
+    or choice stored in a TEXT column is written as text) and read text
+    columns back through the catalog's validator, so ``"0.3"`` reads as
+    ``0.3``. History rows are filed under ``table`` and the owner's sys_id,
+    field = the column name, so they sit beside the rows other editors of
+    the same table write."""
+
+    def __init__(
+        self,
+        name,
+        catalog,
+        table,
+        owner_sys_id,
+        *,
+        column_key="column",
+        count=None,
+    ):
+        if not _COLUMN_RE.match(table or ""):
+            raise SettingsError(f"invalid table {table!r}")
+        self.catalog = catalog
+        self.table = table
+        self.column_key = column_key
+        self.owner_sys_id = int(owner_sys_id)
+        super().__init__(
+            name,
+            self._read_columns,
+            write=self._write_column,
+            unset=self._unset_column,
+            ref=lambda s: f"{table}.{self.column(s)}",
+            count=count,
+            audit_table_name=table,
+            owner_id=self.owner_sys_id,
+            field=self.column,
+        )
+
+    def column(self, setting) -> Optional[str]:
+        column = setting.storage.get(self.column_key)
+        if column is not None and not _COLUMN_RE.match(str(column)):
+            raise SettingsError(f"setting {setting.key!r}: invalid column")
+        return column
+
+    def _types(self, tx):
+        return tx.table(self.table).column_types(cache_ttl=300) or {}
+
+    def _read_columns(self, tx, settings):
+        stored = [s for s in settings if self.column(s)]
+        if not stored:
+            return {}
+        columns = sorted({self.column(s) for s in stored})
+        present = set(tx.table(self.table).sys_columns(cache_ttl=300) or ())
+        wanted = [c for c in columns if c in present]
+        if not wanted:
+            return {}
+        rows = (
+            tx.table(self.table)
+            .select(columns=wanted, where={"sys_id": self.owner_sys_id})
+            .all()
+        )
+        if not rows:
+            raise SettingsError(f"no {self.table} row {self.owner_sys_id}")
+        row = rows[0]
+        out = {}
+        for setting in stored:
+            value = row.get(self.column(setting))
+            if _empty(value):
+                continue
+            try:
+                out[setting.key] = self.catalog.validate(setting, value)
+            except SettingsError:
+                # a stored value the catalog would refuse is still shown as it is
+                out[setting.key] = value
+        return out
+
+    def _store_value(self, tx, setting, value):
+        column = self.column(setting)
+        dtype = str(self._types(tx).get(column, "")).lower()
+        if dtype in ("text", "character varying", "varchar", "character", "char"):
+            if isinstance(value, bool):
+                return "true" if value else "false"
+            if isinstance(value, (dict, list)):
+                return json.dumps(value)
+            return str(value)
+        return value
+
+    def _require_column(self, tx, setting):
+        column = self.column(setting)
+        if not column:
+            raise SettingsError(
+                f"{setting.label} is not stored at the {self.name} level"
+            )
+        return column
+
+    def _write_column(self, tx, setting, value):
+        column = self._require_column(tx, setting)
+        tx.table(self.table).update(
+            {column: self._store_value(tx, setting, value)},
+            where={"sys_id": self.owner_sys_id},
+        )
+
+    def _unset_column(self, tx, setting):
+        column = self._require_column(tx, setting)
+        tx.table(self.table).update({column: None}, where={"sys_id": self.owner_sys_id})
+
+
+class RowLevel(Level):
+    """Values held as rows of a key/value table: one row per owner and key,
+    the value as JSON (``ensure_rows_table`` declares it). History rows are
+    filed under ``table`` and the owner id, field = the setting key."""
+
+    def __init__(
+        self,
+        name,
+        table,
+        owner_column,
+        owner_id,
+        *,
+        key_column="key",
+        value_column="value",
+        count=None,
+    ):
+        for ident in (table, owner_column, key_column, value_column):
+            if not _COLUMN_RE.match(ident or ""):
+                raise SettingsError(f"invalid identifier {ident!r}")
+        self.table = table
+        self.owner_column = owner_column
+        self.key_column = key_column
+        self.value_column = value_column
+        super().__init__(
+            name,
+            self._read_rows,
+            write=self._write_row,
+            unset=self._unset_row,
+            ref=lambda s: f"{table}[{s.key}]",
+            count=count,
+            audit_table_name=table,
+            owner_id=owner_id,
+        )
+
+    def _read_rows(self, tx, settings):
+        keys = [s.key for s in settings]
+        if not keys:
+            return {}
+        rows = (
+            tx.table(self.table)
+            .select(
+                columns=[self.key_column, self.value_column],
+                where={self.owner_column: self.owner_id, self.key_column: keys},
+            )
+            .all()
+        )
+        out = {}
+        for row in rows:
+            value = row.get(self.value_column)
+            if isinstance(value, str):
+                try:
+                    value = json.loads(value)
+                except ValueError:
+                    pass
+            out[row[self.key_column]] = value
+        return out
+
+    def _write_row(self, tx, setting, value):
+        tx.table(self.table).merge(
+            {
+                self.owner_column: self.owner_id,
+                self.key_column: setting.key,
+                self.value_column: json.dumps(value),
+            },
+            pk={self.owner_column: self.owner_id, self.key_column: setting.key},
+        )
+
+    def _unset_row(self, tx, setting):
+        tx.table(self.table).delete(
+            where={self.owner_column: self.owner_id, self.key_column: setting.key}
+        )
+
+
+def rows_table_schema(owner_column="owner_sys_id", owner_type="BIGINT"):
+    """``Table.ensure_schema`` keyword arguments for a :class:`RowLevel`
+    table: owner, ``key`` TEXT, ``value`` JSONB, unique (owner, key)."""
+    if not _COLUMN_RE.match(owner_column or ""):
+        raise SettingsError(f"invalid owner column {owner_column!r}")
+    return {
+        "columns": {owner_column: owner_type, "key": "TEXT", "value": "JSONB"},
+        "unique_indexes": [
+            {"columns": [owner_column, "key"], "name": f"uq_{owner_column}_key"}
+        ],
+    }
+
+
+# ── resolution ───────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Resolved:
+    key: str
+    value: Any
+    source: Optional[str]
+    source_ref: Optional[str]
+    levels: dict
+    overrides: dict
+
+    @property
+    def missing(self) -> bool:
+        return self.source is None
+
+    def to_dict(self) -> dict:
+        return {
+            "key": self.key,
+            "value": self.value,
+            "source": self.source,
+            "source_ref": self.source_ref,
+            "missing": self.missing,
+            "levels": dict(self.levels),
+            "overrides": dict(self.overrides),
+        }
+
+
+def _check_chain(chain: Sequence[Level]):
+    names = [level.name for level in chain]
+    if not chain or len(set(names)) != len(names):
+        raise SettingsError("the level chain needs distinct levels")
+
+
+def resolve_all(tx, catalog: Catalog, chain: Sequence[Level], keys=None) -> dict:
+    """``{key: Resolved}`` for ``keys`` (default: every setting), each the
+    value of the first level in ``chain`` (most specific first) that the
+    setting allows and that holds a value. One read per level."""
+    _check_chain(chain)
+    settings = [catalog.get(k) for k in (keys if keys is not None else catalog.keys())]
+    by_level = {}
+    counts = {}
+    for level in chain:
+        allowed = [s for s in settings if level.name in s.levels]
+        by_level[level.name] = level.read(tx, allowed) if allowed else {}
+        counts[level.name] = level.count(tx, allowed) if allowed else {}
+    out = {}
+    for setting in settings:
+        levels = {}
+        value = source = source_ref = None
+        for level in chain:
+            if level.name not in setting.levels:
+                continue
+            if setting.key in by_level[level.name]:
+                found = by_level[level.name][setting.key]
+                levels[level.name] = found
+                if source is None:
+                    value, source, source_ref = found, level.name, level.ref(setting)
+        overrides = {
+            name: n
+            for name, per_key in counts.items()
+            for key, n in per_key.items()
+            if key == setting.key and n
+        }
+        out[setting.key] = Resolved(
+            setting.key, value, source, source_ref, levels, overrides
+        )
+    return out
+
+
+def resolve(tx, catalog: Catalog, key, chain: Sequence[Level], *, required=False):
+    """The :class:`Resolved` value of one setting. With ``required=True`` a
+    setting no level holds raises :class:`SettingMissingError` (report it,
+    never guess a value)."""
+    resolved = resolve_all(tx, catalog, chain, [key])[key]
+    if required and resolved.missing:
+        raise SettingMissingError(
+            f"{catalog.get(key).label} ({key}) is not set at any level"
+        )
+    return resolved
+
+
+def value(tx, catalog: Catalog, key, chain: Sequence[Level]):
+    """The resolved value of a required setting (see :func:`resolve`)."""
+    return resolve(tx, catalog, key, chain, required=True).value
+
+
+# ── audited writes ───────────────────────────────────────────────────────
+
+
+def _operations(operations):
+    if isinstance(operations, Mapping):
+        operations = [operations]
+    if not isinstance(operations, (list, tuple)) or not operations:
+        raise SettingsError("no operations")
+    if len(operations) > 100:
+        raise SettingsError("too many operations")
+    out = []
+    for op in operations:
+        if not isinstance(op, Mapping) or op.get("op") not in (SET, UNSET):
+            raise SettingsError(f"invalid operation {op!r}")
+        if op["op"] == SET and "value" not in op:
+            raise SettingsError("a set operation needs a value")
+        out.append(op)
+    return out
+
+
+def _json_safe(value):
+    from velocity.aws.handlers.mixins.audit_trail import json_safe
+
+    return json_safe(value)
+
+
+def apply(
+    tx,
+    catalog: Catalog,
+    level: Level,
+    operations,
+    *,
+    by,
+    audit_table=AUDIT_TABLE,
+    now=None,
+) -> List[dict]:
+    """Set or unset settings at one writable ``level``, validated, in
+    ``tx``, and record the change.
+
+    ``operations``: ``[{"op": "set", "key": k, "value": v} | {"op":
+    "unset", "key": k}]`` (or one such dict). Each key must allow
+    ``level.name``; each value is normalized by :meth:`Catalog.validate`.
+    An operation that changes nothing is skipped. ``by`` (the actor, e.g.
+    the signed-in email) is required: it is stamped on the trigger actor
+    (:func:`velocity.db.audit.set_audit_actor`) and written, with the time,
+    on ONE history row in ``audit_table`` (``table_name`` =
+    ``level.audit_table_name``, ``row_sys_id`` = ``level.owner_id``,
+    ``operation`` = ``"settings"``, ``field_diff`` keyed by
+    ``level.field(setting)``). The history row is part of the same
+    transaction: when it cannot be written, nothing is.
+
+    Returns ``[{"key", "field", "from", "to", "op"}]`` for the changes made.
+    """
+    if not level.writable:
+        raise SettingsError(f"the {level.name} level cannot be written")
+    if not isinstance(by, str) or not by.strip():
+        raise SettingsError("an actor is required to change settings")
+    if level.audit_table_name is None or level.owner_id is None:
+        raise SettingsError("the level does not say where its history is filed")
+    ops = _operations(operations)
+    planned = []
+    for op in ops:
+        setting = catalog.get(op.get("key"))
+        if level.name not in setting.levels:
+            raise SettingsError(
+                f"{setting.label} cannot be set at the {level.name} level"
+            )
+        new = catalog.validate(setting, op["value"]) if op["op"] == SET else None
+        planned.append((op["op"], setting, new))
+    current = level.read(tx, [s for _, s, _ in planned])
+    changes = []
+    before, after = {}, {}
+    from velocity.db import audit as db_audit
+
+    db_audit.set_audit_actor(tx, by.strip())
+    for op, setting, new in planned:
+        old = current.get(setting.key)
+        if op == SET and old == new and old is not None:
+            continue
+        if op == UNSET and old is None:
+            continue
+        if op == SET:
+            level.write(tx, setting, new)
+        else:
+            level.unset(tx, setting)
+        current[setting.key] = new
+        name = level.field(setting)
+        before[name] = _json_safe(old)
+        after[name] = _json_safe(new)
+        changes.append(
+            {"key": setting.key, "field": name, "from": old, "to": new, "op": op}
+        )
+    if changes:
+        tx.table(audit_table).insert(
+            {
+                "table_name": level.audit_table_name,
+                "row_sys_id": int(level.owner_id),
+                "operation": OPERATION,
+                "changed_by": by.strip(),
+                "changed_at": now or datetime.datetime.now(datetime.timezone.utc),
+                "before": before,
+                "after": after,
+                "field_diff": {
+                    name: {"from": before[name], "to": after[name]} for name in after
+                },
+            }
+        )
+    return changes
+
+
+def _decode(value):
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except ValueError:
+            return None
+    return value
+
+
+def history(
+    tx,
+    *,
+    table_name,
+    owner_id,
+    field=None,
+    limit=50,
+    audit_table=AUDIT_TABLE,
+    scan=500,
+) -> List[dict]:
+    """The change history of one owner, newest first: settings rows from
+    :func:`apply` and any other history row for the same record (a form
+    save, the audit trigger). With ``field`` only rows that changed it, as
+    ``{"changed_at", "changed_by", "operation", "from", "to"}``; without,
+    ``{"changed_at", "changed_by", "operation", "changes": {field: {from,
+    to}}}``. Reads at most ``scan`` recent rows of the record."""
+    rows = (
+        tx.table(audit_table)
+        .select(
+            columns=["changed_at", "changed_by", "operation", "field_diff"],
+            where={"table_name": table_name, "row_sys_id": int(owner_id)},
+            orderby="changed_at desc",
+            qty=max(1, min(int(scan), 5000)),
+        )
+        .all()
+    )
+    out = []
+    for row in rows:
+        diff = _decode(row.get("field_diff")) or {}
+        if not isinstance(diff, dict):
+            continue
+        base = {
+            "changed_at": row.get("changed_at"),
+            "changed_by": row.get("changed_by"),
+            "operation": row.get("operation"),
+        }
+        if field is not None:
+            change = diff.get(field)
+            if not isinstance(change, dict):
+                continue
+            out.append({**base, "from": change.get("from"), "to": change.get("to")})
+        elif diff:
+            out.append({**base, "changes": diff})
+        if len(out) >= limit:
+            break
+    return out
+
+
+def compare(
+    tx,
+    catalog: Catalog,
+    key,
+    owners: Iterable[Any],
+    chain_for: Callable[[Any], Sequence[Level]],
+) -> List[dict]:
+    """One setting across owners: ``[{"owner", **Resolved.to_dict()}]``,
+    ``chain_for(owner)`` building each owner's chain. For a large owner set
+    an application reads the stored values in one query instead."""
+    catalog.get(key)
+    return [
+        {"owner": owner, **resolve(tx, catalog, key, chain_for(owner)).to_dict()}
+        for owner in owners
+    ]
+
+
+__all__ = [
+    "AUDIT_TABLE",
+    "OPERATION",
+    "SET",
+    "TYPES",
+    "UNSET",
+    "VISIBILITIES",
+    "Catalog",
+    "ColumnLevel",
+    "Level",
+    "Resolved",
+    "RowLevel",
+    "Setting",
+    "SettingMissingError",
+    "SettingsError",
+    "apply",
+    "compare",
+    "history",
+    "platform_level",
+    "resolve",
+    "resolve_all",
+    "rows_table_schema",
+    "value",
+]

{velocity_python-0.3.1.dist-info → velocity_python-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.3.1
+Version: 0.3.2
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.3.1.dist-info → velocity_python-0.3.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-velocity/__init__.py,sha256=SOQcuKluU-M9Yg6SQ0kLn2LtIi1F4u-QooAzeAX9hIM,362
+velocity/__init__.py,sha256=N00pstJ8GXBj7DXMu29lkVjmUMBtgRmMKh443yhzIAs,362
 velocity/cache.py,sha256=pthvw7gDVEXRzkTcQtA5YVf4Q1IxAamWsba4UReT0RE,8933
 velocity/hooks.py,sha256=jY_qtAapNHvptmryFSD-Zc7RvLhV6e5nJEH3x2xTgCw,20575
 velocity/logging.py,sha256=MAsZap1cDSdOBNRc_9ezQxup5dHOS0ARxU9NI_-UK3E,4037
@@ -21,6 +21,7 @@ velocity/aws/queue_defaults.py,sha256=480V3pDvWBBamJ6hIJyVtPGJKMVmnP43otl3E9qnwf
 velocity/aws/s3.py,sha256=Mn6rlK6sXykx32EjptFK2IRRBQZ9xijl9r33DUnKDzQ,30277
 velocity/aws/scheduler.py,sha256=TzhvCcPpgNpRtIdobxQ-A4KsykjAXSM9VUcSr35Lgds,21006
 velocity/aws/schema.py,sha256=JwjCGIQVAHBI8uDXfBljMu8rXAmIGG71JSkeXtQ1ugU,5677
+velocity/aws/settings.py,sha256=aAQL7_dtcC5VSBnk60SX2KwU6jYDmKuyBQVp12Mr5as,39464
 velocity/aws/sms.py,sha256=2CdcLlIEy_V5K5Qx_pZ2vrakvEK7IhP7y1JUttBgyG4,16253
 velocity/aws/ssm_config.py,sha256=xkcBxPuCcdjpeArxdcGnSBiuyG2txlUraSqtCtb_kIo,7987
 velocity/aws/tiles.py,sha256=_38EH9ngxQxLeiZnTHBta-TXg1VkO2hPvaoPHWEKAlc,28011
@@ -235,9 +236,9 @@ velocity/rules/facts.py,sha256=07GuPDW7sB81jihObfwC29eDrGJ-NRVEskWMo9gl1ME,11619
 velocity/rules/storage.py,sha256=dCWhN6g5_kQCTWy66CgpyNmIwrTY1VsVsMPXKoaiO6U,13054
 velocity/testing/__init__.py,sha256=WtYMDHgCLxOq6mlemcOYV5Y9HqF_2QQgSfuAjFRg69Q,731
 velocity/testing/fake_db.py,sha256=phgdulk5owf3noUDpEfI7yFsVcKxRGZ82f2BJPYnaiU,53226
-velocity_python-0.3.1.dist-info/licenses/LICENSE,sha256=aoN245GG8s9oRUU89KNiGTU4_4OtnNmVi4hQeChg6rM,1076
-velocity_python-0.3.1.dist-info/METADATA,sha256=2b2rUzB3cmMq8gEfQ5FuNsFkNGTQDnz2aR0XsBcehZs,17820
-velocity_python-0.3.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-velocity_python-0.3.1.dist-info/entry_points.txt,sha256=nXUKJHkOGQCSPoagdmMNd_qycrle1LVU-GhYknLGM1M,56
-velocity_python-0.3.1.dist-info/top_level.txt,sha256=JW2vJPmodgdgSz7H6yoZvnxF8S3fTMIv-YJWCT1sNW0,9
-velocity_python-0.3.1.dist-info/RECORD,,
+velocity_python-0.3.2.dist-info/licenses/LICENSE,sha256=aoN245GG8s9oRUU89KNiGTU4_4OtnNmVi4hQeChg6rM,1076
+velocity_python-0.3.2.dist-info/METADATA,sha256=GSH-hyhMyotb4-cRn4ttbtDYZD4mqKkT-KOQNo9Zzck,17820
+velocity_python-0.3.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+velocity_python-0.3.2.dist-info/entry_points.txt,sha256=nXUKJHkOGQCSPoagdmMNd_qycrle1LVU-GhYknLGM1M,56
+velocity_python-0.3.2.dist-info/top_level.txt,sha256=JW2vJPmodgdgSz7H6yoZvnxF8S3fTMIv-YJWCT1sNW0,9
+velocity_python-0.3.2.dist-info/RECORD,,