flextool 4.0.0__py3-none-any.whl

flextool/update_flextool/ensure_settings_db.py

@@ -0,0 +1,138 @@
+"""Self-healing creation of lightweight settings SQLite databases.
+
+FlexTool accepts three small, user-editable SQLite databases as
+command-line inputs: ``output_info.sqlite`` (output-location mapping),
+``output_settings.sqlite`` (per-scenario output configuration), and
+``comparison_settings.sqlite`` (scenario-comparison configuration).
+These were previously created only by ``flextool-update``, which users
+had to remember to run at least once.  On a fresh clone, forgetting
+this leads to opaque "file not found" errors from ``spinedb_api``.
+
+This module lets the main runtime paths seed them on demand from their
+tracked JSON templates under ``schemas/``.  The logic is intentionally
+conservative:
+
+* Only file basenames in :data:`SETTINGS_TEMPLATES` are auto-seeded.
+  Other ``*.sqlite`` paths the user passes are left alone.
+* Existing files are never overwritten — user edits always persist.
+* Parent directories are created as needed.
+
+For heavier templates (``examples.sqlite``, ``results_template.sqlite``,
+``example_input.xlsx``) the canonical path remains ``flextool-update``;
+those require migrations that aren't appropriate to run on every solve.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+from .initialize_database import initialize_database
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+SETTINGS_TEMPLATES: dict[str, str] = {
+    "output_info.sqlite": "output_info_template.json",
+    "output_settings.sqlite": "output_settings_template.json",
+    "comparison_settings.sqlite": "comparison_settings_template.json",
+}
+"""Mapping from settings-DB basename to the JSON template that seeds it.
+
+Templates are looked up under ``flextool/schemas/`` via
+``importlib.resources`` (see :func:`ensure_settings_db`).  Keys are
+compared case-sensitively against ``Path.name`` of the target path, not
+full paths — so a user-custom name like ``my_config.sqlite`` is
+intentionally not auto-seeded.
+"""
+
+
+def _sqlite_url_to_path(sqlite_url: str, cwd: Optional[Path] = None) -> Optional[Path]:
+    """Return the filesystem path for a ``sqlite://...`` URL, or ``None``
+    if the input isn't a plain SQLite URL.
+
+    Accepts both ``sqlite:///relative/path.sqlite`` and
+    ``sqlite:////absolute/path.sqlite`` forms.  Unusual URL schemes
+    (in-memory, mysql, remote) are not handled here.
+    """
+    if sqlite_url is None:
+        return None
+    parsed = urlparse(sqlite_url)
+    # A bare Windows path like ``C:\foo`` urlparses with ``scheme='c'``; a
+    # single-letter scheme is a drive letter, not a URL scheme, so treat it as
+    # a plain path (otherwise every drive-anchored Windows path returned None).
+    scheme = "" if len(parsed.scheme) == 1 else parsed.scheme
+    if scheme and scheme != "sqlite":
+        return None
+    if scheme == "sqlite":
+        # ``sqlite:///relative/path``  → parsed.path == '/relative/path'
+        #                                (one leading slash from URL syntax;
+        #                                 actual path is relative)
+        # ``sqlite:////abs/path``      → parsed.path == '//abs/path'
+        #                                (two leading slashes; path is absolute)
+        raw = parsed.path or parsed.netloc
+        if raw.startswith("//"):
+            fs_path = Path(raw[1:])  # ``//abs/path`` → ``/abs/path``
+        elif raw.startswith("/"):
+            fs_path = Path(raw[1:])  # ``/relative/path`` → ``relative/path``
+        else:
+            fs_path = Path(raw)
+    else:
+        # Bare filesystem path (no scheme). Use as-is; do NOT strip a
+        # leading slash — on POSIX that makes absolute paths relative.
+        fs_path = Path(sqlite_url)
+    if not fs_path.is_absolute() and cwd is not None:
+        fs_path = cwd / fs_path
+    return fs_path
+
+
+def ensure_settings_db(
+    target: str | Path,
+    repo_root: Path | None = None,
+    *,
+    logger: Optional[logging.Logger] = None,
+) -> Optional[Path]:
+    """If ``target`` is a known settings DB (by basename) and does not
+    yet exist, create it from the corresponding JSON template.
+
+    ``target`` may be a filesystem path or an ``sqlite://...`` URL.
+    The JSON template ships inside the ``flextool`` package
+    (``flextool/schemas/<template>``); ``repo_root`` is accepted for
+    backward compatibility but ignored — templates are always read from
+    package data via :mod:`importlib.resources`.
+    """
+    log = logger or _LOGGER
+    if target is None:
+        return None
+    if isinstance(target, str):
+        path = _sqlite_url_to_path(target)
+        if path is None:
+            return None
+    else:
+        path = Path(target)
+
+    template_name = SETTINGS_TEMPLATES.get(path.name)
+    if template_name is None:
+        return None
+    if path.exists():
+        return None
+
+    from flextool._resources import package_data_path
+    template_path = package_data_path(f"schemas/{template_name}")
+    if not template_path.is_file():
+        log.warning(
+            "Cannot auto-seed %s: template %s is missing.",
+            path, template_path,
+        )
+        return None
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    initialize_database(str(template_path), str(path))
+    log.info("Seeded %s from %s", path, template_path)
+    return path
+
+
+__all__ = ["SETTINGS_TEMPLATES", "ensure_settings_db"]

flextool/update_flextool/export_database.py

@@ -0,0 +1,103 @@
+"""Export a FlexTool Spine DB to deterministic JSON.
+
+Companion to :func:`flextool.update_flextool.initialize_database`.  The
+round-trip ``export_database -> initialize_database -> export_database``
+is bit-identical, which lets canonical example/template databases live
+in git as JSON instead of binary ``.sqlite`` files.
+
+Two callables sit at the heart of the round-trip:
+
+``keep_serialized_parse``
+    Passed as ``parse_value`` to :func:`spinedb_api.export_data`.  Instead
+    of returning a parsed Python object (``Array``, ``Map``, ``DateTime``,
+    ...), it returns the raw ``(value_json_str, type_str)`` pair that
+    ``spinedb_api`` already stores in the DB.  That keeps every shape
+    JSON-serialisable and avoids lossy round-trips through parsed
+    object identity (e.g. ``Map`` repr ordering, float printing).
+
+``keep_serialized_unparse``
+    Passed as ``unparse_value`` to :func:`spinedb_api.import_data` by
+    :func:`flextool.update_flextool.initialize_database` when the JSON
+    came from this exporter.  Accepts either the ``(str, type)`` pair
+    (preserved from JSON) or a raw scalar (master-template style); in
+    the former case it bypasses :func:`spinedb_api.to_database` and
+    writes the bytes straight back.
+"""
+
+import argparse
+import json
+from typing import Any
+
+from spinedb_api import DatabaseMapping, export_data
+from spinedb_api.parameter_value import to_database
+
+
+def keep_serialized_parse(value: bytes | None, type_: str | None) -> Any:
+    """``parse_value`` callback that preserves the raw DB form.
+
+    Returns ``None`` for ``None`` and for the JSON-``null`` blob (those
+    are equivalent on the import side and collapsing them keeps the
+    exported JSON tidy and round-trip-stable).  Otherwise returns a
+    ``[json_string, type_string]`` two-list — a list, not a tuple,
+    so it survives ``json.dumps``/``json.loads`` unchanged.
+    """
+    if value is None:
+        return None
+    if value == b"null" and type_ is None:
+        return None
+    return [value.decode("utf-8"), type_]
+
+
+def keep_serialized_unparse(value: Any) -> tuple[bytes | None, str | None]:
+    """``unparse_value`` callback paired with :func:`keep_serialized_parse`.
+
+    Recognises the ``[json_string, type_string]`` shape produced by this
+    exporter and routes it back to the DB without re-parsing.  Falls
+    back to the default :func:`spinedb_api.to_database` for any other
+    shape, so master templates that author raw scalars (``"no_method"``,
+    numbers, ``None``) keep working.
+    """
+    if (
+        isinstance(value, list)
+        and len(value) == 2
+        and (value[1] is None or isinstance(value[1], str))
+    ):
+        val_str, type_str = value
+        if val_str is None:
+            return None, None
+        return val_str.encode("utf-8"), type_str
+    return to_database(value)
+
+
+def export_database(database_path: str, json_path: str) -> None:
+    """Export ``database_path`` to a deterministic JSON file.
+
+    The output is ``json.dumps``-ed with ``sort_keys=True`` and
+    ``indent=2`` so diffs are reviewable and ordering is stable.  Lists
+    inside the dump preserve ``spinedb_api`` insertion order — that is
+    already deterministic per DB, and forcing a sort would invalidate
+    ordered structures such as ``parameter_value_lists``.
+    """
+    if database_path.startswith("sqlite://"):
+        url = database_path
+    elif database_path.endswith(".sqlite"):
+        url = "sqlite:///" + database_path
+    else:
+        raise ValueError(
+            f"Expected a .sqlite path or sqlite:// URL, got {database_path!r}"
+        )
+
+    with DatabaseMapping(url, create=False, upgrade=True) as db:
+        data = export_data(db, parse_value=keep_serialized_parse)
+
+    with open(json_path, "w", encoding="utf-8") as out:
+        json.dump(data, out, sort_keys=True, indent=2, ensure_ascii=False)
+        out.write("\n")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("database_path", help="Source .sqlite path")
+    parser.add_argument("json_path", help="Destination JSON path")
+    args = parser.parse_args()
+    export_database(args.database_path, args.json_path)