flextool 4.0.0__py3-none-any.whl

flextool/cli/cmd_open_results_db.py

@@ -0,0 +1,269 @@
+"""Open the project's results database(s) in the standalone Spine DB editor.
+
+This is the Toolbox-interop launcher Tool. It resolves the per-project
+``results.sqlite`` at RUNTIME and launches the Spine DB editor on it,
+DETACHED, so the Tool item completes immediately.
+
+Two resolution modes (``--results-db-url`` overrides both):
+
+* **From Output info (preferred):** ``--output-locations-db-url`` points at
+  the Output-info DB — the SAME source Re-create results and Scenario
+  comparison read.  Each scenario's ``scenario/output_location`` records where
+  its outputs (and ``results.sqlite``) were written.  We collect every DISTINCT
+  location and open every ``<location>/results.sqlite`` that exists — as tabs
+  in a single Spine DB editor (its ``main`` accepts multiple positional URLs).
+  Normally all scenarios share one project folder, so this is one DB.
+* **From the project-folder redirect (fallback):** ``--project-folder-file``
+  resolves ``<project>/results.sqlite`` via ``resolve_output_path`` (the 5-tier
+  rule shared with the run Tool), for running this Tool without an Output-info
+  link.
+
+Launch mechanism (the only supported standalone entry point — the
+``spine-db-editor`` console script, ``spinetoolbox.spine_db_editor.main:main``):
+its ``main()`` parses positional ``url`` args, so we invoke
+
+    <python> -m spinetoolbox.spine_db_editor.main sqlite:///<path> [sqlite:///<path> ...]
+
+with the SAME interpreter that runs this script (``sys.executable``).
+"""
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from flextool.cli._console import run_tool
+from flextool.cli.cmd_run_flextool import resolve_output_path
+
+
+def resolve_results_db_path(project_folder_file, output_location=None):
+    """Resolve the filesystem path of the project's ``results.sqlite``.
+
+    Reuses ``resolve_output_path`` (the 5-tier rule shared with the run
+    Tool) to find the project/output root, then appends ``results.sqlite``.
+    """
+    output_root = resolve_output_path(
+        input_db_url=None,
+        flextool_location=None,
+        output_location=output_location,
+        cwd=Path.cwd(),
+        project_folder_file=project_folder_file,
+    )
+    return Path(output_root) / "results.sqlite"
+
+
+def output_locations_from_db(output_info_db_url):
+    """Return the DISTINCT per-scenario ``output_location`` paths recorded in
+    the Output-info DB, in first-seen order.
+
+    Mirrors ``cmd_write_outputs``: scenarios come from the alternative filter
+    applied to the DB (or, unfiltered, from every ``scenario`` entity); each
+    scenario's ``scenario/output_location`` value names where its outputs were
+    written.  The DB URL may be a ``sqlite:///`` path or a Spine DB-server
+    ``http://`` URL (both open via ``DatabaseMapping``).
+    """
+    from spinedb_api import DatabaseMapping
+
+    locations = []
+    with DatabaseMapping(output_info_db_url) as db:
+        filter_configs = db.get_filter_configs()
+        scenario_names = []
+        if filter_configs and filter_configs[0].get("alternatives"):
+            scenario_names = list(filter_configs[0]["alternatives"])
+        if not scenario_names:
+            scenario_names = [
+                e["name"]
+                for e in db.get_entity_items(entity_class_name="scenario")
+            ]
+        for scenario_name in scenario_names:
+            pv = db.get_parameter_value_item(
+                entity_class_name="scenario",
+                entity_byname=(scenario_name,),
+                parameter_definition_name="output_location",
+                alternative_name=scenario_name,
+            )
+            if not pv:
+                continue
+            loc = pv["parsed_value"]
+            if loc and loc not in locations:
+                locations.append(loc)
+    return locations
+
+
+def _to_sqlite_url(db_path):
+    """Build a ``sqlite:///`` URL for an absolute/relative filesystem path."""
+    return f"sqlite:///{Path(db_path).as_posix()}"
+
+
+def _build_launch_argv(db_urls):
+    """Build the argv that opens the standalone Spine DB editor.
+
+    ``db_urls`` may be a single URL string or a list of URLs (each becomes a
+    tab).  The supported standalone entry point is
+    ``spinetoolbox.spine_db_editor.main:main``, whose ``main()`` reads
+    positional ``url`` args.
+    """
+    if isinstance(db_urls, str):
+        db_urls = [db_urls]
+    return [
+        sys.executable,
+        "-m",
+        "spinetoolbox.spine_db_editor.main",
+        *db_urls,
+    ]
+
+
+def launch_db_editor(db_urls, _popen=subprocess.Popen):
+    """Launch the Spine DB editor on ``db_urls`` (str or list), DETACHED.
+
+    ``_popen`` is injectable for testing so the launch argv can be asserted
+    without spawning a real GUI process.  Returns the spawned handle.
+    """
+    argv = _build_launch_argv(db_urls)
+    # start_new_session detaches the child into its own process group so it
+    # outlives this Tool process.  No ``.wait()`` — the Tool returns at once.
+    # Redirect the child's std streams to DEVNULL so the detached editor does
+    # NOT inherit (and write to) Spine Toolbox's Basic Console pipes: otherwise
+    # the editor's import-time chatter — e.g. requests' RequestsDependencyWarning
+    # from the venv — leaks back into the Tool console long after this Tool has
+    # returned.  A GUI app has its own window; it needs no console streams.
+    return _popen(
+        argv,
+        start_new_session=True,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+
+def _open_from_output_info(output_info_db_url):
+    """Open every existing ``<output_location>/results.sqlite`` found via the
+    Output-info DB, as tabs in one editor.  Returns a process exit code."""
+    locations = output_locations_from_db(output_info_db_url)
+    if not locations:
+        print(
+            "No scenario output locations found in the Output-info DB "
+            f"({output_info_db_url}); run the workflow first.",
+            file=sys.stderr,
+        )
+        return 1
+    urls, missing = [], []
+    for loc in locations:
+        path = Path(loc) / "results.sqlite"
+        if path.exists():
+            urls.append(_to_sqlite_url(path))
+        else:
+            missing.append(path)
+    if missing:
+        print(
+            "results.sqlite missing at: "
+            + ", ".join(str(p) for p in missing)
+            + " (those scenarios were not run with output-spinedb).",
+            file=sys.stderr,
+        )
+    if not urls:
+        print(
+            "No results.sqlite found at any scenario output location; run "
+            "the workflow with output-spinedb enabled first.",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"Opening Spine DB editor on {len(urls)} results database(s): "
+          + ", ".join(urls))
+    launch_db_editor(urls)
+    return 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description=(
+            "Open the project's results.sqlite in the standalone Spine DB "
+            "editor.  Preferred: resolve locations from the Output-info DB "
+            "(--output-locations-db-url), the same source Re-create results "
+            "uses, opening every scenario's results.sqlite as tabs.  "
+            "Fallback: resolve <project>/results.sqlite from "
+            "--project-folder-file."
+        )
+    )
+    parser.add_argument(
+        "--output-locations-db-url",
+        metavar="URL",
+        default=None,
+        help=(
+            "Output-info DB URL (sqlite:/// or http://). Opens every distinct "
+            "scenario <output_location>/results.sqlite that exists, as tabs."
+        ),
+    )
+    parser.add_argument(
+        "--project-folder-file",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Fallback: path to the user-local file whose CONTENTS name the "
+            "project folder (templates/project_folder.txt).  results.sqlite is "
+            "resolved at <project>/results.sqlite."
+        ),
+    )
+    parser.add_argument(
+        "--output-location",
+        metavar="PATH",
+        default=None,
+        help="Explicit project/output root override (used by the fallback).",
+    )
+    parser.add_argument(
+        "--results-db-url",
+        metavar="URL_OR_PATH",
+        default=None,
+        help=(
+            "Open this DB directly instead of resolving from Output info or "
+            "the project folder.  Accepts a sqlite:/// URL or a bare path."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    # 1. Explicit --results-db-url short-circuits everything.
+    if args.results_db_url:
+        value = args.results_db_url
+        if "://" in value:
+            db_url = value
+            db_path = (
+                Path(value.replace("sqlite:///", "", 1))
+                if value.startswith("sqlite:")
+                else None
+            )
+        else:
+            db_path = Path(value)
+            db_url = _to_sqlite_url(db_path)
+        if db_path is not None and not db_path.exists():
+            print(
+                f"results.sqlite not found at {db_path}; run the workflow with "
+                f"output-spinedb enabled first (then re-run this Tool).",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"Opening Spine DB editor on {db_url}")
+        launch_db_editor(db_url)
+        return 0
+
+    # 2. Preferred: resolve locations from the Output-info DB (open all).
+    if args.output_locations_db_url:
+        return _open_from_output_info(args.output_locations_db_url)
+
+    # 3. Fallback: the project-folder redirect → <project>/results.sqlite.
+    db_path = resolve_results_db_path(
+        args.project_folder_file, output_location=args.output_location
+    )
+    if not db_path.exists():
+        print(
+            f"results.sqlite not found at {db_path}; run the workflow with "
+            f"output-spinedb enabled first (then re-run this Tool).",
+            file=sys.stderr,
+        )
+        return 1
+    db_url = _to_sqlite_url(db_path)
+    print(f"Opening Spine DB editor on {db_url}")
+    launch_db_editor(db_url)
+    return 0
+
+
+if __name__ == "__main__":
+    run_tool(main)

flextool/cli/cmd_read_matpower.py

@@ -0,0 +1,66 @@
+"""CLI entry point for importing a MATPOWER .m file to a FlexTool Spine DB."""
+
+import argparse
+
+from flextool.process_inputs.read_matpower import (
+    create_flextool_db_from_matpower,
+    read_matpower,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Import a MATPOWER .m file into a FlexTool Spine DB "
+        "with DC power flow enabled.",
+    )
+    parser.add_argument(
+        "matpower_file",
+        help="Path to the MATPOWER .m file (e.g. pglib_opf_case14_ieee.m)",
+    )
+    parser.add_argument(
+        "target_db",
+        help="Path for the output SQLite database (e.g. case14.sqlite)",
+    )
+    parser.add_argument(
+        "--scenario-name",
+        default="dc_opf_test",
+        help="Name for the scenario (default: dc_opf_test)",
+    )
+    parser.add_argument(
+        "--alternative-name",
+        default="base",
+        help="Name for the alternative (default: base)",
+    )
+    parser.add_argument(
+        "--template-json",
+        default=None,
+        help="Path to FlexTool master template JSON "
+        "(default: schemas/spinedb_schema.json relative to cwd)",
+    )
+    args = parser.parse_args()
+
+    print(f"Reading MATPOWER file: {args.matpower_file}")
+    case = read_matpower(args.matpower_file)
+    print(
+        f"  Parsed: {case.name} — {len(case.buses)} buses, "
+        f"{len(case.generators)} generators, {len(case.branches)} branches, "
+        f"baseMVA={case.base_mva}"
+    )
+
+    print(f"Writing FlexTool database: {args.target_db}")
+    url = create_flextool_db_from_matpower(
+        case,
+        args.target_db,
+        scenario_name=args.scenario_name,
+        alternative_name=args.alternative_name,
+        template_json=args.template_json,
+    )
+    print(f"Import complete! Database URL: {url}")
+    print(
+        f"Run with: python run_flextool.py {url} sqlite:///output.sqlite "
+        f"--scenario-name {args.scenario_name}"
+    )
+
+
+if __name__ == "__main__":
+    main()

flextool/cli/cmd_read_old_flextool.py

@@ -0,0 +1,63 @@
+"""CLI entry point for importing an old-format FlexTool .xlsm file to a Spine DB.
+
+This runs the full pipeline: initialise the target from the frozen v56 import
+template (if not already a FlexTool DB), write the workbook's data, then
+``migrate_database`` the result up to the current schema version.  See
+``import_old_flextool_xlsm`` for why the importer is pinned to a fixed version
+and relies on migration rather than tracking the live schema.
+"""
+
+import argparse
+
+from flextool.process_inputs.write_old_flextool_to_db import (
+    import_old_flextool_xlsm,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Import an old-format FlexTool Excel (.xlsm) into a Spine DB."
+    )
+    parser.add_argument(
+        "xlsm_path",
+        help="Path to the old-format FlexTool Excel file (.xlsm)",
+    )
+    parser.add_argument(
+        "target_db_url",
+        help="Target database URL (e.g. sqlite:///output.sqlite)",
+    )
+    parser.add_argument(
+        "--alternative-name",
+        default="base",
+        help="Name for the alternative (default: base)",
+    )
+    parser.add_argument(
+        "--no-purge",
+        action="store_true",
+        help="Do not purge existing data before importing",
+    )
+    parser.add_argument(
+        "--no-migrate",
+        action="store_true",
+        help=(
+            "Do not migrate the database to the current schema version after "
+            "writing. The GUI uses this so it can run migration as a separate "
+            "execution job; standalone use should leave migration on."
+        ),
+    )
+    args = parser.parse_args()
+
+    print(f"Importing old FlexTool Excel: {args.xlsm_path}")
+    print(f"Target database: {args.target_db_url}")
+    import_old_flextool_xlsm(
+        args.xlsm_path,
+        args.target_db_url,
+        alternative_name=args.alternative_name,
+        purge=not args.no_purge,
+        migrate=not args.no_migrate,
+    )
+    print("Import complete!")
+
+
+if __name__ == "__main__":
+    main()

flextool/cli/cmd_read_self_describing_tabular_input.py

@@ -0,0 +1,50 @@
+"""CLI entry point for importing a self-describing FlexTool Excel file to a Spine DB."""
+
+import argparse
+
+from flextool.process_inputs.read_self_describing_excel import read_self_describing_excel
+from flextool.process_inputs.write_self_describing_to_db import write_sheet_data_to_db
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Import a self-describing FlexTool Excel (.xlsx) into a Spine DB."
+    )
+    parser.add_argument(
+        "xlsx_path",
+        help="Path to the self-describing Excel file (.xlsx)",
+    )
+    parser.add_argument(
+        "target_db_url",
+        help="Target database URL (e.g. sqlite:///output.sqlite)",
+    )
+    parser.add_argument(
+        "--no-purge",
+        action="store_true",
+        help="Do not purge existing data before importing",
+    )
+    parser.add_argument(
+        "--keep-entities",
+        action="store_true",
+        help="Keep existing entities during purge (for fresh template DBs)",
+    )
+    args = parser.parse_args()
+
+    print(f"Reading Excel: {args.xlsx_path}")
+    sheets = read_self_describing_excel(args.xlsx_path, skip_sheets={"navigate", "version"})
+
+    total_records = sum(len(s.records) for s in sheets)
+    total_links = sum(len(s.link_entities) for s in sheets)
+    print(f"Parsed {len(sheets)} sheets: {total_records} records, {total_links} links")
+
+    print(f"Writing to database: {args.target_db_url}")
+    write_sheet_data_to_db(
+        sheets, args.target_db_url,
+        purge_first=not args.no_purge,
+        keep_entities=args.keep_entities,
+    )
+    print("Import complete!")
+
+
+if __name__ == "__main__":
+    main()

flextool/cli/cmd_read_tabular_input.py

@@ -0,0 +1,81 @@
+import argparse
+import os
+from pathlib import Path
+from flextool.process_inputs.read_tabular_with_specification import TabularReader
+from flextool.process_inputs.write_to_input_db import write_to_flextool_input_db
+
+
+def _ensure_target_db_exists(target_db_url: str) -> None:
+    """Initialize the target database from the FlexTool template if it does not exist.
+
+    The ``write_to_flextool_input_db`` function opens the database with
+    ``create=False`` and expects a valid FlexTool schema (including a
+    *version* parameter).  When the caller asks us to write into a brand-new
+    sqlite file (e.g. during xlsx-to-sqlite conversion) the file won't exist
+    yet, so we must create and initialise it first.
+    """
+    if not target_db_url.startswith("sqlite:///"):
+        return  # Only handle local sqlite files
+
+    db_path = target_db_url.replace("sqlite:///", "", 1)
+    if os.path.exists(db_path):
+        return  # Already exists -- nothing to do
+
+    # Make sure the parent directory exists
+    parent = Path(db_path).parent
+    parent.mkdir(parents=True, exist_ok=True)
+
+    # Locate the FlexTool master template (bundled in the package).
+    from flextool._resources import package_data_path
+    json_template = package_data_path("schemas/spinedb_schema.json")
+    if not json_template.exists():
+        raise FileNotFoundError(
+            f"FlexTool template not found at {json_template}. "
+            "Cannot initialize the target database."
+        )
+
+    from flextool.update_flextool.initialize_database import initialize_database
+    from flextool.update_flextool.db_migration import migrate_database
+
+    print(f"Target database does not exist. Initializing: {db_path}")
+    initialize_database(str(json_template), db_path)
+    migrate_database(db_path)
+
+
+def main():
+
+        parser = argparse.ArgumentParser()
+        parser.add_argument('target_db_url',help= "URL to FlexTool input database (e.g. sqlite:///input_data.sqlite)")
+
+        input_group = parser.add_mutually_exclusive_group(required=True)
+        input_group.add_argument('--tabular-file-path', help= "The file path of a FlexTool input file (either xlsx or ods).")
+        input_group.add_argument('--csv-directory-path', help= "Input data as csv files in FlexTool format.")
+        parser.add_argument('--migration-follows', action='store_true',
+                            help="Accept a version mismatch because migration will run after import")
+
+        args = parser.parse_args()
+
+        # Initialize the target database if it doesn't exist yet
+        _ensure_target_db_exists(args.target_db_url)
+
+        # Get the path to the old 3.x format specification in process_inputs/
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        json_path = os.path.join(script_dir, "..", "process_inputs", "import_old_excel_input.json")
+        tabular_reader = TabularReader(json_path)
+
+        if args.tabular_file_path:
+            input_path = args.tabular_file_path
+            input_type = 'excel'
+        elif args.csv_directory_path:
+            input_path = args.csv_directory_path
+            input_type = 'csv'
+        else:
+            raise ValueError("Must provide either tabular_file_path or csv_directory_path")
+
+        write_to_flextool_input_db(input_path, tabular_reader, args.target_db_url, input_type,
+                                   migration_follows=args.migration_follows)
+
+
+
+if __name__ == '__main__':
+    main()