simple-db-settings 1.0.0__py3-none-any.whl

simple_db_settings/__init__.py

@@ -0,0 +1,41 @@
+from simple_db_settings.audit import causer, current_causer
+from simple_db_settings.cache import CacheBackend, NullCache, TTLCache
+from simple_db_settings.store import DEFAULT_GROUP, GroupView, SettingsStore
+from simple_db_settings.exceptions import (
+    CodecError,
+    InvalidValueError,
+    MissingExtraError,
+    SimpleSettingsError,
+    TransferError,
+    UnknownTypeError,
+)
+from simple_db_settings.transfer import (
+    export_json,
+    export_rows,
+    import_json,
+    import_rows,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "causer",
+    "current_causer",
+    "CacheBackend",
+    "NullCache",
+    "TTLCache",
+    "DEFAULT_GROUP",
+    "GroupView",
+    "SettingsStore",
+    "CodecError",
+    "InvalidValueError",
+    "MissingExtraError",
+    "SimpleSettingsError",
+    "TransferError",
+    "UnknownTypeError",
+    "export_json",
+    "export_rows",
+    "import_json",
+    "import_rows",
+    "__version__",
+]

simple_db_settings/audit.py

@@ -0,0 +1,75 @@
+import json
+import logging
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import datetime
+from typing import Any, Iterator
+
+from sqlalchemy import Connection, Table, insert
+
+logger = logging.getLogger("simple_db_settings")
+
+EVENT_CREATED = "created"
+EVENT_UPDATED = "updated"
+EVENT_DELETED = "deleted"
+
+_causer_var: ContextVar[tuple[str | None, int | None]] = ContextVar(
+    "simple_db_settings_causer", default=(None, None)
+)
+
+
+@contextmanager
+def causer(causer_type: str, causer_id: int) -> Iterator[None]:
+    """Attribute audit rows written inside the block to this actor."""
+    token = _causer_var.set((causer_type, causer_id))
+    try:
+        yield
+    finally:
+        _causer_var.reset(token)
+
+
+def current_causer() -> tuple[str | None, int | None]:
+    return _causer_var.get()
+
+
+def payload(value: Any) -> str | None:
+    """Audit payload: SQL NULL both for missing values and for None."""
+    if value is None:
+        return None
+    return json.dumps(value, ensure_ascii=True, separators=(",", ":"), allow_nan=False)
+
+
+def record(
+    conn: Connection,
+    table: Table,
+    group: str,
+    entries: list[dict[str, Any]],
+    now: datetime,
+) -> None:
+    """Write all audit rows of one operation with a single insert.
+
+    Each entry carries: name, event, old (value or None), new (value or None).
+    """
+    if not entries:
+        return
+
+    causer_type, causer_id = current_causer()
+    rows = [
+        {
+            "group": group,
+            "name": e["name"],
+            "event": e["event"],
+            "old_payload": payload(e["old"]),
+            "new_payload": payload(e["new"]),
+            "causer_type": causer_type,
+            "causer_id": causer_id,
+            "created_at": now,
+        }
+        for e in entries
+    ]
+    conn.execute(insert(table).values(rows))
+    logger.debug(
+        "audit recorded: group=%s events=%s",
+        group,
+        [e["event"] for e in entries],
+    )

simple_db_settings/cache.py

@@ -0,0 +1,70 @@
+import logging
+import threading
+import time
+from typing import Any, Callable, Protocol
+
+logger = logging.getLogger("simple_db_settings")
+
+DEFAULT_TTL = 5.0
+
+
+class CacheBackend(Protocol):
+    def get(self, group: str) -> dict[str, Any] | None: ...
+
+    def set(self, group: str, data: dict[str, Any]) -> None: ...
+
+    def invalidate(self, group: str) -> None: ...
+
+
+class NullCache:
+    """Cache that never stores anything."""
+
+    def get(self, group: str) -> dict[str, Any] | None:
+        return None
+
+    def set(self, group: str, data: dict[str, Any]) -> None:
+        pass
+
+    def invalidate(self, group: str) -> None:
+        pass
+
+
+class TTLCache:
+    """In-process cache of whole groups with a time-to-live.
+
+    The TTL bounds staleness across processes: another worker cannot
+    invalidate this cache, so entries must expire on their own.
+    """
+
+    def __init__(
+        self,
+        ttl: float = DEFAULT_TTL,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._ttl = ttl
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._entries: dict[str, tuple[float, dict[str, Any]]] = {}
+
+    def get(self, group: str) -> dict[str, Any] | None:
+        with self._lock:
+            entry = self._entries.get(group)
+            if entry is None:
+                logger.debug("cache miss: group=%s", group)
+                return None
+            expires_at, data = entry
+            if self._clock() >= expires_at:
+                del self._entries[group]
+                logger.debug("cache expired: group=%s", group)
+                return None
+            logger.debug("cache hit: group=%s", group)
+            return data
+
+    def set(self, group: str, data: dict[str, Any]) -> None:
+        with self._lock:
+            self._entries[group] = (self._clock() + self._ttl, data)
+
+    def invalidate(self, group: str) -> None:
+        with self._lock:
+            self._entries.pop(group, None)
+        logger.debug("cache invalidated: group=%s", group)

simple_db_settings/cli.py

@@ -0,0 +1,183 @@
+"""Command line interface for the settings table (extra: cli)."""
+
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+from simple_db_settings.exceptions import MissingExtraError, SimpleSettingsError
+
+try:
+    import typer
+except ImportError as exc:
+    raise MissingExtraError("Command line interface", "cli") from exc
+
+from sqlalchemy import create_engine
+from sqlalchemy.pool import NullPool
+
+from simple_db_settings.schema import DEFAULT_SETTINGS_TABLE
+from simple_db_settings.store import DEFAULT_GROUP, SettingsStore
+from simple_db_settings.transfer import export_json, import_json
+
+app = typer.Typer(help="Manage DB-backed settings", no_args_is_help=True)
+
+UrlOption = Annotated[
+    str,
+    typer.Option("--url", envvar="SIMPLE_DB_SETTINGS_URL", help="Database URL"),
+]
+TableOption = Annotated[
+    str, typer.Option("--table", help="Settings table name")
+]
+GroupOption = Annotated[str, typer.Option("--group", "-g", help="Settings group")]
+VerboseOption = Annotated[bool, typer.Option("--verbose", help="Debug logging")]
+
+
+def _store(url: str, table: str, verbose: bool) -> SettingsStore:
+    logging.basicConfig(level=logging.DEBUG if verbose else logging.WARNING)
+    engine = create_engine(url, poolclass=NullPool)
+    return SettingsStore(engine, table_name=table)
+
+
+def _fail(message: str) -> "typer.Exit":
+    typer.echo(f"Error: {message}", err=True)
+    return typer.Exit(code=1)
+
+
+@app.command()
+def get(
+    key: str,
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: GroupOption = DEFAULT_GROUP,
+    verbose: VerboseOption = False,
+):
+    """Print one setting as JSON."""
+    store = _store(url, table, verbose)
+    try:
+        value = store.group(group)[key]
+    except KeyError:
+        raise _fail(f"Setting {group}.{key} not found") from None
+    except SimpleSettingsError as exc:
+        raise _fail(str(exc)) from None
+    typer.echo(json.dumps(value, ensure_ascii=False))
+
+
+@app.command("set")
+def set_(
+    key: str,
+    value: str,
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: GroupOption = DEFAULT_GROUP,
+    verbose: VerboseOption = False,
+):
+    """Store a setting. VALUE is parsed as JSON, falling back to a string."""
+    store = _store(url, table, verbose)
+    try:
+        parsed = json.loads(value)
+    except ValueError:
+        parsed = value
+    try:
+        store.group(group)[key] = parsed
+    except SimpleSettingsError as exc:
+        raise _fail(str(exc)) from None
+
+
+@app.command()
+def delete(
+    key: str,
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: GroupOption = DEFAULT_GROUP,
+    verbose: VerboseOption = False,
+):
+    """Remove one setting."""
+    store = _store(url, table, verbose)
+    try:
+        del store.group(group)[key]
+    except KeyError:
+        raise _fail(f"Setting {group}.{key} not found") from None
+
+
+@app.command("list")
+def list_(
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: Annotated[Optional[str], typer.Option("--group", "-g")] = None,
+    verbose: VerboseOption = False,
+):
+    """List raw rows: group, name, type, val."""
+    store = _store(url, table, verbose)
+    for row in store.rows(group):
+        typer.echo(f"{row.group}\t{row.name}\t{row.type}\t{row.val}")
+
+
+@app.command()
+def groups(
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    verbose: VerboseOption = False,
+):
+    """List group names."""
+    store = _store(url, table, verbose)
+    for name in store.groups():
+        typer.echo(name)
+
+
+@app.command()
+def clear(
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: GroupOption = DEFAULT_GROUP,
+    verbose: VerboseOption = False,
+):
+    """Remove all settings in a group."""
+    store = _store(url, table, verbose)
+    store.group(group).clear()
+
+
+@app.command()
+def export(
+    url: UrlOption,
+    file: Annotated[Optional[Path], typer.Argument()] = None,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: Annotated[Optional[str], typer.Option("--group", "-g")] = None,
+    verbose: VerboseOption = False,
+):
+    """Export settings to JSON (stdout when FILE is omitted)."""
+    store = _store(url, table, verbose)
+    dump = export_json(store, group)
+    if file is None:
+        typer.echo(dump)
+    else:
+        file.write_text(dump)
+        typer.echo(f"Exported to {file}")
+
+
+@app.command("import")
+def import_(
+    file: Path,
+    url: UrlOption,
+    table: TableOption = DEFAULT_SETTINGS_TABLE,
+    group: Annotated[Optional[str], typer.Option("--group", "-g")] = None,
+    replace: Annotated[bool, typer.Option("--replace")] = False,
+    verbose: VerboseOption = False,
+):
+    """Import settings from a JSON file made by export."""
+    store = _store(url, table, verbose)
+    if not file.is_file():
+        raise _fail(f"File not found: {file}")
+    try:
+        count = import_json(store, file.read_text(), group=group, replace=replace)
+    except SimpleSettingsError as exc:
+        raise _fail(str(exc)) from None
+    typer.echo(f"Imported {count} setting(s)")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simple_db_settings/codec.py

@@ -0,0 +1,67 @@
+"""Value codec for the shared settings table.
+
+Follows the cross-language storage contract: values are written with
+type='json', rows written by the Laravel package (string, integer, float,
+boolean, array, object, null, legacy double) stay readable forever.
+"""
+
+import json
+
+from simple_db_settings.exceptions import (
+    CodecError,
+    InvalidValueError,
+    UnknownTypeError,
+)
+
+JSON_TYPE = "json"
+
+_PHP_FALSE_STRINGS = frozenset(("", "0"))
+
+
+def encode(value: object) -> tuple[str, str]:
+    """Serialize a value for storage. Returns (val, type)."""
+    try:
+        val = json.dumps(value, ensure_ascii=True, separators=(",", ":"), allow_nan=False)
+    except (TypeError, ValueError) as exc:
+        raise InvalidValueError(f"Value is not JSON-serializable: {exc}") from exc
+    return val, JSON_TYPE
+
+
+def decode(val: str | None, type_: str, group: str = "", name: str = "") -> object:
+    """Restore a value from a stored (val, type) pair.
+
+    Dispatch is driven by the type column only, never by val content.
+    """
+    if val is None:
+        val = ""
+    kind = type_.strip().lower()
+
+    if kind == "string":
+        return val
+    if kind == "boolean":
+        return val not in _PHP_FALSE_STRINGS
+    if kind == "null":
+        return None
+    if kind == "integer":
+        try:
+            return int(val)
+        except ValueError as exc:
+            raise CodecError(
+                f"Bad integer value {val!r} for {group}.{name}"
+            ) from exc
+    if kind in ("float", "double"):
+        try:
+            return float(val)
+        except ValueError as exc:
+            raise CodecError(
+                f"Bad float value {val!r} for {group}.{name}"
+            ) from exc
+    if kind in ("array", "object", "json"):
+        try:
+            return json.loads(val)
+        except ValueError as exc:
+            raise CodecError(
+                f"Bad JSON value for {group}.{name}: {exc}"
+            ) from exc
+
+    raise UnknownTypeError(group, name, type_)

simple_db_settings/exceptions.py

@@ -0,0 +1,38 @@
+class SimpleSettingsError(Exception):
+    """Base error for the simple-db-settings package."""
+
+
+class MissingExtraError(SimpleSettingsError):
+    """Optional dependency is not installed."""
+
+    def __init__(self, feature: str, extra: str) -> None:
+        self.feature = feature
+        self.extra = extra
+        super().__init__(
+            f"{feature} requires an optional dependency. "
+            f"Install it with: pip install simple-db-settings[{extra}]"
+        )
+
+
+class InvalidValueError(SimpleSettingsError):
+    """Value cannot be serialized for storage."""
+
+
+class CodecError(SimpleSettingsError):
+    """Stored data cannot be decoded."""
+
+
+class TransferError(SimpleSettingsError):
+    """Export or import data does not match the exchange format."""
+
+
+class UnknownTypeError(SimpleSettingsError):
+    """Row has a type value the codec does not recognize."""
+
+    def __init__(self, group: str, name: str, type_: str) -> None:
+        self.group = group
+        self.name = name
+        self.type = type_
+        super().__init__(
+            f"Unknown settings type {type_!r} for {group}.{name}"
+        )

simple_db_settings/schema.py

@@ -0,0 +1,50 @@
+from sqlalchemy import (
+    CHAR,
+    BigInteger,
+    Column,
+    DateTime,
+    Index,
+    Integer,
+    MetaData,
+    String,
+    Table,
+    Text,
+)
+
+DEFAULT_SETTINGS_TABLE = "simple_settings"
+DEFAULT_CHANGES_TABLE = "simple_setting_changes"
+
+# Автоинкремент BigInteger не работает на SQLite, вариант Integer его чинит.
+_PK_BIGINT = BigInteger().with_variant(Integer, "sqlite")
+
+
+def make_settings_table(metadata: MetaData, name: str = DEFAULT_SETTINGS_TABLE) -> Table:
+    return Table(
+        name,
+        metadata,
+        Column("group", String(255), primary_key=True),
+        Column("name", String(255), primary_key=True),
+        Column("val", Text, nullable=False),
+        Column("type", CHAR(20), nullable=False, server_default="string"),
+        Column("created_at", DateTime, nullable=True),
+        Column("updated_at", DateTime, nullable=True),
+    )
+
+
+def make_changes_table(metadata: MetaData, name: str = DEFAULT_CHANGES_TABLE) -> Table:
+    return Table(
+        name,
+        metadata,
+        Column("id", _PK_BIGINT, primary_key=True, autoincrement=True),
+        Column("group", String(255), nullable=False),
+        Column("name", String(255), nullable=False),
+        Column("event", String(20), nullable=False),
+        Column("old_payload", Text, nullable=True),
+        Column("new_payload", Text, nullable=True),
+        Column("causer_type", String(255), nullable=True),
+        Column("causer_id", BigInteger, nullable=True),
+        Column("created_at", DateTime, nullable=True),
+        Index(f"{name}_target_idx", "group", "name", "created_at"),
+        Index(f"{name}_causer_idx", "causer_type", "causer_id"),
+        Index(f"{name}_event_idx", "event"),
+    )