db-process 0.1.0__tar.gz → 0.3.1__tar.gz

{db_process-0.1.0 → db_process-0.3.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Tokarzewski
+Copyright (c) 2026 DesignBuilder Software
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

db_process-0.3.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: db-process
+Version: 0.3.1
+Summary: Python interface to DesignBuilder command line processing.
+Author: DesignBuilder Software
+Project-URL: Homepage, https://github.com/DesignBuilderSoftware/db-process
+Project-URL: Bug Tracker, https://github.com/DesignBuilderSoftware/db-process/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# db-process
+
+Python interface to DesignBuilder's command-line driver — typed `/process=` commands, subprocess execution, and process discovery.
+
+DesignBuilder is a Windows GUI app, but it exposes a `/process=` argument that runs a sequence of commands non-interactively and exits. `db-process` wraps that surface in real Python: dataclass commands instead of stringly-typed flags, a `ProcessChain` builder, blocking and non-blocking runners, and helpers to find/kill the process.
+
+> For diagnostic-log parsing see [db-diag](https://github.com/DesignBuilderSoftware/db-diag).
+
+## Install
+
+```bash
+pip install db-process
+# or, from the cloned repo:
+pip install -e .[dev]
+```
+
+Requires Python 3.10+ and `psutil`. DesignBuilder itself only runs on Windows;
+on other platforms, the package imports fine but `run()` and the process
+helpers will raise `FileNotFoundError`.
+
+## Quick start
+
+### Python — run a model with a chain of commands
+
+```python
+from db_process import ProcessChain, Screen, run
+
+chain = (
+    ProcessChain()
+    .use_sim_manager()
+    .switch_screen(Screen.SIMULATION)
+    .sim_start_date(1, 1)
+    .sim_end_date(31, 12)
+    .change_attribute("OccupancyValue", 0.5)
+    .run()
+)
+
+result = run("models/office.dsb", chain, timeout=600)
+print(result.success, result.duration_seconds)
+```
+
+### Python — convenience factories for common runs
+
+```python
+from db_process import eplus_simulation, run
+
+# A pre-built ProcessChain for "open model, run EnergyPlus, close".
+result = run("models/office.dsb", eplus_simulation())
+```
+
+Other factories: `sbem_calculation`, `export_xml`, `heating_and_cooling_design`,
+`daylighting`, `cfd_simulation`.
+
+### Python — non-blocking with idle-detection kill
+
+```python
+from db_process import run_async
+
+handle = run_async("models/office.dsb")
+# Block until DesignBuilder finishes its work and CPU drops, then kill it.
+handle.kill_when_idle(idle_threshold=10, cpu_threshold=0.1)
+```
+
+`kill_when_idle` is the workaround for runs where DesignBuilder finishes the
+calculation but doesn't exit — common with the GUI Sim Manager path.
+
+### CLI
+
+```bash
+db-process status              # is DesignBuilder running? show pid + exe path
+db-process open                # launch DesignBuilder
+db-process open path/to.dsb    # launch with a model
+db-process close               # kill any running DesignBuilder
+db-process restart [model]     # close + open (with a 1.5 s settle)
+```
+
+`db-process` is the entry point installed by the package; you can also run it as `python -m db_process`.
+
+## Public API
+
+```python
+from db_process import (
+    # Executable discovery
+    find_designbuilder,                          # () -> Path
+
+    # Process status
+    is_running, find_process, status,            # status() -> ProcessStatus
+    kill_process, kill_when_idle,
+    ProcessStatus,                               # is_running, pid, exe_path
+
+    # Run
+    run, run_async, RunHandle, RunResult,
+
+    # Command model
+    ProcessChain, Screen,
+    SwitchScreen, RunCalculation, TabChange,
+    SimStartDate, SimEndDate, ChangeAttributeValue,
+    ExternalCommand, ImportModelData, ImportLibraryData,
+    ExportAsXML, UseSimManager, NoClose,
+
+    # Convenience factories
+    eplus_simulation, sbem_calculation, export_xml,
+    heating_and_cooling_design, daylighting, cfd_simulation,
+)
+```
+
+### Executable discovery
+
+`find_designbuilder(exe_path=None)` resolves DesignBuilder.exe in this order:
+
+1. The explicit `exe_path` argument, if given.
+2. `DESIGNBUILDER_EXE` environment variable.
+3. `C:\Program Files (x86)\DesignBuilder\DesignBuilder.exe`,
+   then `C:\Program Files\DesignBuilder\DesignBuilder.exe`.
+4. The system `PATH` (`shutil.which("DesignBuilder")`).
+
+Raises `FileNotFoundError` with a hint to set `DESIGNBUILDER_EXE` if none match.
+
+### Process status
+
+`status()` is a one-shot snapshot:
+
+```python
+from db_process import status
+
+s = status()
+# ProcessStatus(is_running=True, pid=12345, exe_path='C:\\...\\DesignBuilder.exe')
+if not s.is_running and s.exe_path:
+    # Discovered but not running — safe to launch.
+    ...
+```
+
+`exe_path` is populated regardless of whether the process is running, so
+callers can decide whether to launch without a second `find_designbuilder`
+call.
+
+### `ProcessChain` — building a `/process=` argument
+
+`ProcessChain` is a fluent builder for the `/process=` command sequence
+documented in DesignBuilder Help. Example output of `chain.to_string()`:
+
+```
+/process=UseSimManager, miGSS, SimStartDate 1 1, SimEndDate 31 12,
+         ChangeAttributeValue OccupancyValue 0.5, miTUpdate
+```
+
+Every command is also exposed as a plain dataclass, so you can construct
+chains without the builder when that's clearer.
+
+## Compatibility
+
+- **DesignBuilder**: any version that supports the `/process=` argument.
+  Tested against the v25.1 / v26.1 lines.
+- **Python**: 3.10+.
+- **OS**: Windows for live runs. The command model is pure Python and imports on any platform — useful for unit tests on Linux CI.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest         
+ruff check .
+```
+
+Tests are split by area:
+
+| File | Covers |
+| --- | --- |
+| `test_commands.py`     | `ProcessChain` building + every command's `to_string()` |
+| `test_executable.py`   | `find_designbuilder` resolution order |
+| `test_status.py`       | `status` / `ProcessStatus` |
+| `test_cli.py`          | CLI argparse wiring (mocked subprocess) |
+
+## Releasing
+
+Every version is a tag. `pyproject.toml`'s `version` and the git tag must never
+drift apart — consumers pin to `@vX.Y.Z`, and an untagged bump leaves them with
+nothing to pin to but a commit SHA.
+
+To cut a release, bump `version` in `pyproject.toml` on `main`:
+
+```toml
+[project]
+version = "0.3.0"
+```
+
+The `Release` workflow then tags that commit `v0.3.0` and opens a matching
+GitHub Release with generated notes. It only fires on changes to
+`pyproject.toml`, and skips silently if the tag already exists, so re-runs are
+safe.
+
+To tag manually instead — or to backfill a version that predates the workflow:
+
+```bash
+git tag -a v0.3.0 -m "v0.3.0" && git push origin v0.3.0
+```
+
+Bump the version in the same pull request as the change it describes, not as a
+separate follow-up — that's how the two fell out of step before.

db_process-0.3.1/README.md

@@ -0,0 +1,199 @@
+# db-process
+
+Python interface to DesignBuilder's command-line driver — typed `/process=` commands, subprocess execution, and process discovery.
+
+DesignBuilder is a Windows GUI app, but it exposes a `/process=` argument that runs a sequence of commands non-interactively and exits. `db-process` wraps that surface in real Python: dataclass commands instead of stringly-typed flags, a `ProcessChain` builder, blocking and non-blocking runners, and helpers to find/kill the process.
+
+> For diagnostic-log parsing see [db-diag](https://github.com/DesignBuilderSoftware/db-diag).
+
+## Install
+
+```bash
+pip install db-process
+# or, from the cloned repo:
+pip install -e .[dev]
+```
+
+Requires Python 3.10+ and `psutil`. DesignBuilder itself only runs on Windows;
+on other platforms, the package imports fine but `run()` and the process
+helpers will raise `FileNotFoundError`.
+
+## Quick start
+
+### Python — run a model with a chain of commands
+
+```python
+from db_process import ProcessChain, Screen, run
+
+chain = (
+    ProcessChain()
+    .use_sim_manager()
+    .switch_screen(Screen.SIMULATION)
+    .sim_start_date(1, 1)
+    .sim_end_date(31, 12)
+    .change_attribute("OccupancyValue", 0.5)
+    .run()
+)
+
+result = run("models/office.dsb", chain, timeout=600)
+print(result.success, result.duration_seconds)
+```
+
+### Python — convenience factories for common runs
+
+```python
+from db_process import eplus_simulation, run
+
+# A pre-built ProcessChain for "open model, run EnergyPlus, close".
+result = run("models/office.dsb", eplus_simulation())
+```
+
+Other factories: `sbem_calculation`, `export_xml`, `heating_and_cooling_design`,
+`daylighting`, `cfd_simulation`.
+
+### Python — non-blocking with idle-detection kill
+
+```python
+from db_process import run_async
+
+handle = run_async("models/office.dsb")
+# Block until DesignBuilder finishes its work and CPU drops, then kill it.
+handle.kill_when_idle(idle_threshold=10, cpu_threshold=0.1)
+```
+
+`kill_when_idle` is the workaround for runs where DesignBuilder finishes the
+calculation but doesn't exit — common with the GUI Sim Manager path.
+
+### CLI
+
+```bash
+db-process status              # is DesignBuilder running? show pid + exe path
+db-process open                # launch DesignBuilder
+db-process open path/to.dsb    # launch with a model
+db-process close               # kill any running DesignBuilder
+db-process restart [model]     # close + open (with a 1.5 s settle)
+```
+
+`db-process` is the entry point installed by the package; you can also run it as `python -m db_process`.
+
+## Public API
+
+```python
+from db_process import (
+    # Executable discovery
+    find_designbuilder,                          # () -> Path
+
+    # Process status
+    is_running, find_process, status,            # status() -> ProcessStatus
+    kill_process, kill_when_idle,
+    ProcessStatus,                               # is_running, pid, exe_path
+
+    # Run
+    run, run_async, RunHandle, RunResult,
+
+    # Command model
+    ProcessChain, Screen,
+    SwitchScreen, RunCalculation, TabChange,
+    SimStartDate, SimEndDate, ChangeAttributeValue,
+    ExternalCommand, ImportModelData, ImportLibraryData,
+    ExportAsXML, UseSimManager, NoClose,
+
+    # Convenience factories
+    eplus_simulation, sbem_calculation, export_xml,
+    heating_and_cooling_design, daylighting, cfd_simulation,
+)
+```
+
+### Executable discovery
+
+`find_designbuilder(exe_path=None)` resolves DesignBuilder.exe in this order:
+
+1. The explicit `exe_path` argument, if given.
+2. `DESIGNBUILDER_EXE` environment variable.
+3. `C:\Program Files (x86)\DesignBuilder\DesignBuilder.exe`,
+   then `C:\Program Files\DesignBuilder\DesignBuilder.exe`.
+4. The system `PATH` (`shutil.which("DesignBuilder")`).
+
+Raises `FileNotFoundError` with a hint to set `DESIGNBUILDER_EXE` if none match.
+
+### Process status
+
+`status()` is a one-shot snapshot:
+
+```python
+from db_process import status
+
+s = status()
+# ProcessStatus(is_running=True, pid=12345, exe_path='C:\\...\\DesignBuilder.exe')
+if not s.is_running and s.exe_path:
+    # Discovered but not running — safe to launch.
+    ...
+```
+
+`exe_path` is populated regardless of whether the process is running, so
+callers can decide whether to launch without a second `find_designbuilder`
+call.
+
+### `ProcessChain` — building a `/process=` argument
+
+`ProcessChain` is a fluent builder for the `/process=` command sequence
+documented in DesignBuilder Help. Example output of `chain.to_string()`:
+
+```
+/process=UseSimManager, miGSS, SimStartDate 1 1, SimEndDate 31 12,
+         ChangeAttributeValue OccupancyValue 0.5, miTUpdate
+```
+
+Every command is also exposed as a plain dataclass, so you can construct
+chains without the builder when that's clearer.
+
+## Compatibility
+
+- **DesignBuilder**: any version that supports the `/process=` argument.
+  Tested against the v25.1 / v26.1 lines.
+- **Python**: 3.10+.
+- **OS**: Windows for live runs. The command model is pure Python and imports on any platform — useful for unit tests on Linux CI.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest         
+ruff check .
+```
+
+Tests are split by area:
+
+| File | Covers |
+| --- | --- |
+| `test_commands.py`     | `ProcessChain` building + every command's `to_string()` |
+| `test_executable.py`   | `find_designbuilder` resolution order |
+| `test_status.py`       | `status` / `ProcessStatus` |
+| `test_cli.py`          | CLI argparse wiring (mocked subprocess) |
+
+## Releasing
+
+Every version is a tag. `pyproject.toml`'s `version` and the git tag must never
+drift apart — consumers pin to `@vX.Y.Z`, and an untagged bump leaves them with
+nothing to pin to but a commit SHA.
+
+To cut a release, bump `version` in `pyproject.toml` on `main`:
+
+```toml
+[project]
+version = "0.3.0"
+```
+
+The `Release` workflow then tags that commit `v0.3.0` and opens a matching
+GitHub Release with generated notes. It only fires on changes to
+`pyproject.toml`, and skips silently if the tag already exists, so re-runs are
+safe.
+
+To tag manually instead — or to backfill a version that predates the workflow:
+
+```bash
+git tag -a v0.3.0 -m "v0.3.0" && git push origin v0.3.0
+```
+
+Bump the version in the same pull request as the change it describes, not as a
+separate follow-up — that's how the two fell out of step before.

{db_process-0.1.0 → db_process-0.3.1}/db_process/__init__.py

@@ -1,83 +1,89 @@
-"""
-db-process
-====================================
-Python interface to DesignBuilder command line processing.
-
-This package provides:
-
-- **Executable discovery** — find DesignBuilder.exe across env vars,
-  default install paths, and the system PATH.
-- **Typed command model** — dataclasses for every ``/process=`` command
-  documented in DesignBuilder Help, with a fluent builder API.
-- **Subprocess execution** — blocking and non-blocking modes, timeout
-  handling, and idle-detection termination.
-"""
-
-from db_process.commands import (
-    ChangeAttributeValue,
-    ExportAsXML,
-    ExternalCommand,
-    ImportLibraryData,
-    ImportModelData,
-    NoClose,
-    ProcessChain,
-    RunCalculation,
-    Screen,
-    SimEndDate,
-    SimStartDate,
-    SwitchScreen,
-    TabChange,
-    UseSimManager,
-    # Convenience factories
-    cfd_simulation,
-    daylighting,
-    eplus_simulation,
-    export_xml,
-    heating_and_cooling_design,
-    sbem_calculation,
-)
-from db_process.executable import find_designbuilder
-from db_process.runner import (
-    RunHandle,
-    RunResult,
-    find_process,
-    kill_process,
-    kill_when_idle,
-    run,
-    run_async,
-)
-
-__all__ = [
-    # Executable
-    "find_designbuilder",
-    # Commands
-    "ChangeAttributeValue",
-    "ExportAsXML",
-    "ExternalCommand",
-    "ImportLibraryData",
-    "ImportModelData",
-    "NoClose",
-    "ProcessChain",
-    "RunCalculation",
-    "Screen",
-    "SimEndDate",
-    "SimStartDate",
-    "SwitchScreen",
-    "TabChange",
-    "UseSimManager",
-    # Convenience factories
-    "cfd_simulation",
-    "daylighting",
-    "eplus_simulation",
-    "export_xml",
-    "heating_and_cooling_design",
-    "sbem_calculation",
-    # Runner
-    "RunHandle",
-    "RunResult",
-    "find_process",
-    "kill_process",
-    "kill_when_idle",
-    "run",
-    "run_async",
-]
+"""
+db-process
+====================================
+Python interface to DesignBuilder command line processing.
+
+This package provides:
+
+- **Executable discovery** — find DesignBuilder.exe across env vars,
+  default install paths, and the system PATH.
+- **Typed command model** — dataclasses for every ``/process=`` command
+  documented in DesignBuilder Help, with a fluent builder API.
+- **Subprocess execution** — blocking and non-blocking modes, timeout
+  handling, and idle-detection termination.
+"""
+
+from db_process.commands import (
+    ChangeAttributeValue,
+    ExportAsXML,
+    ExternalCommand,
+    ImportLibraryData,
+    ImportModelData,
+    NoClose,
+    ProcessChain,
+    RunCalculation,
+    Screen,
+    SimEndDate,
+    SimStartDate,
+    SwitchScreen,
+    TabChange,
+    UseSimManager,
+    # Convenience factories
+    cfd_simulation,
+    daylighting,
+    eplus_simulation,
+    export_xml,
+    heating_and_cooling_design,
+    sbem_calculation,
+)
+from db_process.executable import find_designbuilder
+from db_process.runner import (
+    ProcessStatus,
+    RunHandle,
+    RunResult,
+    find_process,
+    is_running,
+    kill_process,
+    kill_when_idle,
+    run,
+    run_async,
+    status,
+)
+
+__all__ = [
+    # Executable
+    "find_designbuilder",
+    # Commands
+    "ChangeAttributeValue",
+    "ExportAsXML",
+    "ExternalCommand",
+    "ImportLibraryData",
+    "ImportModelData",
+    "NoClose",
+    "ProcessChain",
+    "RunCalculation",
+    "Screen",
+    "SimEndDate",
+    "SimStartDate",
+    "SwitchScreen",
+    "TabChange",
+    "UseSimManager",
+    # Convenience factories
+    "cfd_simulation",
+    "daylighting",
+    "eplus_simulation",
+    "export_xml",
+    "heating_and_cooling_design",
+    "sbem_calculation",
+    # Runner / status
+    "RunHandle",
+    "RunResult",
+    "ProcessStatus",
+    "find_process",
+    "is_running",
+    "kill_process",
+    "kill_when_idle",
+    "run",
+    "run_async",
+    "status",
+]

db_process-0.3.1/db_process/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m db_process [subcommand]`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

db_process-0.3.1/db_process/cli.py

@@ -0,0 +1,92 @@
+"""db-process CLI.
+
+Small command-line wrapper over the existing process-control primitives:
+
+    db-process status                  # is DB running? where's the exe?
+    db-process close                   # kill any running DesignBuilder
+    db-process open [MODEL.dsb]        # launch DB; opens MODEL if given
+    db-process restart [MODEL.dsb]     # close + open
+
+Equivalent to:
+
+    python -m db_process <subcommand> [args]
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from .executable import find_designbuilder
+from .runner import find_process, is_running, kill_process, run_async, status as proc_status
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    s = proc_status()
+    print(f"DesignBuilder exe     : {s.exe_path or '<not found>'}")
+    if not s.is_running:
+        print("DesignBuilder process : not running")
+        return 1
+    print(f"DesignBuilder process : pid={s.pid}")
+    return 0
+
+
+def cmd_close(args: argparse.Namespace) -> int:
+    if kill_process():
+        print("Closed running DesignBuilder.")
+        return 0
+    print("No DesignBuilder process to close.")
+    return 1
+
+
+def cmd_open(args: argparse.Namespace) -> int:
+    exe = find_designbuilder()
+    if args.model is not None:
+        print(f"Opening {args.model} with {exe} ...")
+        run_async(str(args.model))
+    else:
+        print(f"Launching {exe} (no model)...")
+        subprocess.Popen([str(exe)])
+    return 0
+
+
+def cmd_restart(args: argparse.Namespace) -> int:
+    if kill_process():
+        print(f"Closed existing process; settling for {args.settle}s ...")
+        time.sleep(args.settle)
+    return cmd_open(args)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="db-process",
+                                description="DesignBuilder process control")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("status", help="Show DesignBuilder exe path and PID").set_defaults(func=cmd_status)
+    sub.add_parser("close", help="Kill any running DesignBuilder").set_defaults(func=cmd_close)
+
+    p_open = sub.add_parser("open", help="Launch DesignBuilder")
+    p_open.add_argument("model", nargs="?", type=Path, default=None,
+                        help="Optional .dsb model to open")
+    p_open.set_defaults(func=cmd_open)
+
+    p_restart = sub.add_parser("restart", help="Close then open DesignBuilder")
+    p_restart.add_argument("model", nargs="?", type=Path, default=None,
+                           help="Optional .dsb model to open after restart")
+    p_restart.add_argument("--settle", type=float, default=1.5,
+                           help="Seconds to wait between close and open (default 1.5)")
+    p_restart.set_defaults(func=cmd_restart)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())