db-process 0.1.0__py3-none-any.whl

db_process/__init__.py

@@ -0,0 +1,83 @@
+"""
+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/commands.py

@@ -0,0 +1,449 @@
+"""
+commands.py
+====================================
+Typed representation of DesignBuilder command line process commands.
+
+DesignBuilder CLI syntax::
+
+    "DesignBuilder.exe" "MyFile.dsb" /process=Command1, Command2, ...
+
+This module provides dataclasses for each command type and a
+:class:`ProcessChain` builder to compose them into valid ``/process=`` strings.
+
+Reference: DesignBuilder Help > Reference > Command Line Processing
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Union
+
+
+# ---------------------------------------------------------------------------
+# Screen / view commands
+# ---------------------------------------------------------------------------
+
+class Screen(str, Enum):
+    """Available DesignBuilder screen commands."""
+
+    SIMULATION = "miGSS"
+    HEATING_DESIGN = "miGHL"
+    COOLING_DESIGN = "miGHG"
+    DAYLIGHTING = "miGDY"
+    SBEM_DSM = "miGCalculate"
+    CFD = "miGCFD"
+
+
+# ---------------------------------------------------------------------------
+# Individual command dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class SwitchScreen:
+    """Change the view to a specific DesignBuilder screen.
+
+    Examples: miGSS, miGHL, miGHG, miGDY, miGCalculate, miGCFD
+    """
+
+    screen: Screen
+
+    def render(self) -> str:
+        return self.screen.value
+
+
+@dataclass(frozen=True)
+class RunCalculation:
+    """Run the calculation for the current screen (miTUpdate).
+
+    Generally this command should be placed after screen switching
+    and before any ChangeAttributeValue commands that follow it.
+    """
+
+    def render(self) -> str:
+        return "miTUpdate"
+
+
+@dataclass(frozen=True)
+class TabChange:
+    """Change the view to tab *n* on the current screen.
+
+    Example: ``TabChange_2`` on the Daylighting screen switches to
+    the Annual daylighting tab.
+    """
+
+    tab: int
+
+    def __post_init__(self) -> None:
+        if self.tab < 1:
+            raise ValueError(f"Tab number must be >= 1, got {self.tab}")
+
+    def render(self) -> str:
+        return f"TabChange_{self.tab}"
+
+
+@dataclass(frozen=True)
+class SimStartDate:
+    """Set simulation start date.
+
+    Parameters are day and month as integers.
+    Example: ``SimStartDate 4 5`` sets start to May 4.
+    """
+
+    day: int
+    month: int
+
+    def __post_init__(self) -> None:
+        if not (1 <= self.month <= 12):
+            raise ValueError(f"Month must be 1-12, got {self.month}")
+        if not (1 <= self.day <= 31):
+            raise ValueError(f"Day must be 1-31, got {self.day}")
+
+    def render(self) -> str:
+        return f"SimStartDate {self.day} {self.month}"
+
+
+@dataclass(frozen=True)
+class SimEndDate:
+    """Set simulation end date.
+
+    Parameters are day and month as integers.
+    Example: ``SimEndDate 11 5`` sets end to May 11.
+    """
+
+    day: int
+    month: int
+
+    def __post_init__(self) -> None:
+        if not (1 <= self.month <= 12):
+            raise ValueError(f"Month must be 1-12, got {self.month}")
+        if not (1 <= self.day <= 31):
+            raise ValueError(f"Day must be 1-31, got {self.day}")
+
+    def render(self) -> str:
+        return f"SimEndDate {self.day} {self.month}"
+
+
+@dataclass(frozen=True)
+class ChangeAttributeValue:
+    """Change a model attribute at building level.
+
+    Attribute value types (from documentation):
+        - Numeric enums: integer codes (e.g. ``Layout 0``)
+        - Booleans: ``1`` for True, ``0`` for False
+        - Real numbers: SI units, ``.`` decimal separator
+        - Database table selections: numeric Id (obtain via API)
+
+    Tip: Enable *Show attribute names in tooltips* in
+    Tools > Program Options > Interface to find attribute names.
+    """
+
+    attribute: str
+    value: Union[str, int, float]
+
+    def render(self) -> str:
+        return f"ChangeAttributeValue {self.attribute} {self.value}"
+
+
+@dataclass(frozen=True)
+class ExternalCommand:
+    """Run an external command with optional arguments.
+
+    The external executable must be on the system PATH or in the
+    working directory.
+    """
+
+    command: str
+
+    def render(self) -> str:
+        return f"ExternalCommand_{self.command}"
+
+
+@dataclass(frozen=True)
+class ImportModelData:
+    """Import model data from a CSV file previously exported from the model."""
+
+    filepath: str
+
+    def render(self) -> str:
+        return f"ImportModelData_{self.filepath}"
+
+
+@dataclass(frozen=True)
+class ImportLibraryData:
+    """Import library data from a file."""
+
+    filepath: str
+
+    def render(self) -> str:
+        return f"ImportLibraryData_{self.filepath}"
+
+
+@dataclass(frozen=True)
+class ExportAsXML:
+    """Export the model as a dsbXML file (miFExportAsXML)."""
+
+    def render(self) -> str:
+        return "miFExportAsXML"
+
+
+@dataclass(frozen=True)
+class UseSimManager:
+    """Ensure the simulation runs using the Simulation Manager.
+
+    Uses the Server and EnergyPlus server method settings
+    currently configured in the model.
+    """
+
+    def render(self) -> str:
+        return "UseSimManager"
+
+
+@dataclass(frozen=True)
+class NoClose:
+    """Prevent DesignBuilder from shutting down after all commands."""
+
+    def render(self) -> str:
+        return "NoClose"
+
+
+# Union of all command types for type hints.
+Command = Union[
+    SwitchScreen,
+    RunCalculation,
+    TabChange,
+    SimStartDate,
+    SimEndDate,
+    ChangeAttributeValue,
+    ExternalCommand,
+    ImportModelData,
+    ImportLibraryData,
+    ExportAsXML,
+    UseSimManager,
+    NoClose,
+]
+
+
+# ---------------------------------------------------------------------------
+# ProcessChain builder
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ProcessChain:
+    """Build a ``/process=`` command string from a sequence of commands.
+
+    Usage::
+
+        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()
+        )
+        print(chain.to_string())
+        # /process=UseSimManager, miGSS, SimStartDate 1 1, SimEndDate 31 12,
+        #          ChangeAttributeValue OccupancyValue 0.5, miTUpdate
+    """
+
+    commands: list[Command] = field(default_factory=list)
+
+    # -- Fluent builder methods -----------------------------------------------
+
+    def add(self, command: Command) -> ProcessChain:
+        """Add an arbitrary command to the chain."""
+        self.commands.append(command)
+        return self
+
+    def switch_screen(self, screen: Screen) -> ProcessChain:
+        """Add a screen-switching command."""
+        return self.add(SwitchScreen(screen))
+
+    def run(self) -> ProcessChain:
+        """Add miTUpdate (run calculation for current screen)."""
+        return self.add(RunCalculation())
+
+    def tab_change(self, tab: int) -> ProcessChain:
+        """Switch to a specific tab on the current screen."""
+        return self.add(TabChange(tab))
+
+    def sim_start_date(self, day: int, month: int) -> ProcessChain:
+        """Set simulation start date."""
+        return self.add(SimStartDate(day, month))
+
+    def sim_end_date(self, day: int, month: int) -> ProcessChain:
+        """Set simulation end date."""
+        return self.add(SimEndDate(day, month))
+
+    def change_attribute(
+        self, attribute: str, value: Union[str, int, float]
+    ) -> ProcessChain:
+        """Change a model attribute value."""
+        return self.add(ChangeAttributeValue(attribute, value))
+
+    def external_command(self, command: str) -> ProcessChain:
+        """Run an external command."""
+        return self.add(ExternalCommand(command))
+
+    def import_model_data(self, filepath: str) -> ProcessChain:
+        """Import model data from a CSV file."""
+        return self.add(ImportModelData(filepath))
+
+    def import_library_data(self, filepath: str) -> ProcessChain:
+        """Import library data from a file."""
+        return self.add(ImportLibraryData(filepath))
+
+    def export_as_xml(self) -> ProcessChain:
+        """Export the model as dsbXML."""
+        return self.add(ExportAsXML())
+
+    def use_sim_manager(self) -> ProcessChain:
+        """Use the Simulation Manager for the run."""
+        return self.add(UseSimManager())
+
+    def no_close(self) -> ProcessChain:
+        """Prevent DesignBuilder from closing after processing."""
+        return self.add(NoClose())
+
+    # -- Rendering ------------------------------------------------------------
+
+    def to_string(self) -> str:
+        """Render the chain as a ``/process=...`` argument string.
+
+        Raises
+        ------
+        ValueError
+            If the chain contains no commands.
+        """
+        if not self.commands:
+            raise ValueError("ProcessChain is empty — add at least one command.")
+        parts = [cmd.render() for cmd in self.commands]
+        return "/process=" + ", ".join(parts)
+
+    def to_list(self) -> list[str]:
+        """Return the chain as a list of individual command strings."""
+        return [cmd.render() for cmd in self.commands]
+
+    def __str__(self) -> str:
+        return self.to_string()
+
+    def __repr__(self) -> str:
+        return f"ProcessChain({self.commands!r})"
+
+    def __len__(self) -> int:
+        return len(self.commands)
+
+
+# ---------------------------------------------------------------------------
+# Convenience factory functions
+# ---------------------------------------------------------------------------
+
+def eplus_simulation(
+    *,
+    sim_start_date: Optional[tuple[int, int]] = None,
+    sim_end_date: Optional[tuple[int, int]] = None,
+    use_sim_manager: bool = False,
+    attributes: Optional[list[tuple[str, Union[str, int, float]]]] = None,
+    no_close: bool = False,
+) -> ProcessChain:
+    """Build a standard EnergyPlus simulation command chain.
+
+    This produces the equivalent of what ``db-batch`` creates for
+    ``analysis_type="eplus"``.
+    """
+    chain = ProcessChain()
+
+    if use_sim_manager:
+        chain.use_sim_manager()
+
+    if sim_start_date:
+        chain.sim_start_date(sim_start_date[0], sim_start_date[1])
+
+    if sim_end_date:
+        chain.sim_end_date(sim_end_date[0], sim_end_date[1])
+
+    if attributes:
+        for attr, val in attributes:
+            chain.change_attribute(attr, val)
+
+    chain.switch_screen(Screen.SIMULATION)
+    chain.run()
+
+    if no_close:
+        chain.no_close()
+
+    return chain
+
+
+def sbem_calculation(
+    *,
+    sim_start_date: Optional[tuple[int, int]] = None,
+    sim_end_date: Optional[tuple[int, int]] = None,
+    attributes: Optional[list[tuple[str, Union[str, int, float]]]] = None,
+    no_close: bool = False,
+) -> ProcessChain:
+    """Build a standard SBEM/DSM calculation command chain."""
+    chain = ProcessChain()
+
+    if sim_start_date:
+        chain.sim_start_date(sim_start_date[0], sim_start_date[1])
+
+    if sim_end_date:
+        chain.sim_end_date(sim_end_date[0], sim_end_date[1])
+
+    if attributes:
+        for attr, val in attributes:
+            chain.change_attribute(attr, val)
+
+    chain.switch_screen(Screen.SBEM_DSM)
+    chain.run()
+
+    if no_close:
+        chain.no_close()
+
+    return chain
+
+
+def export_xml() -> ProcessChain:
+    """Build a command chain to export the model as dsbXML."""
+    return ProcessChain().export_as_xml()
+
+
+def heating_and_cooling_design(*, no_close: bool = False) -> ProcessChain:
+    """Run both Heating and Cooling Design calculations."""
+    chain = (
+        ProcessChain()
+        .switch_screen(Screen.HEATING_DESIGN)
+        .run()
+        .switch_screen(Screen.COOLING_DESIGN)
+        .run()
+    )
+    if no_close:
+        chain.no_close()
+    return chain
+
+
+def daylighting(
+    *, run_annual: bool = False, no_close: bool = False
+) -> ProcessChain:
+    """Run daylighting calculation, optionally including annual daylighting.
+
+    When *run_annual* is True, runs both Illuminance (tab 1) and
+    Annual daylighting (tab 2) calculations.
+    """
+    chain = ProcessChain().switch_screen(Screen.DAYLIGHTING).run()
+    if run_annual:
+        chain.tab_change(2).run()
+    if no_close:
+        chain.no_close()
+    return chain
+
+
+def cfd_simulation(*, no_close: bool = False) -> ProcessChain:
+    """Run a CFD simulation."""
+    chain = ProcessChain().switch_screen(Screen.CFD).run()
+    if no_close:
+        chain.no_close()
+    return chain

db_process/executable.py

@@ -0,0 +1,76 @@
+"""
+executable.py
+====================================
+Locate and validate the DesignBuilder executable.
+
+Resolution order:
+    1. Explicit path argument
+    2. DESIGNBUILDER_EXE environment variable
+    3. Common Windows installation directories
+    4. System PATH (via shutil.which)
+"""
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+# Environment variable to override the DesignBuilder executable path.
+ENV_VAR = "DESIGNBUILDER_EXE"
+
+# Common DesignBuilder installation paths (Windows).
+DEFAULT_INSTALL_PATHS = [
+    Path(r"C:\Program Files (x86)\DesignBuilder\DesignBuilder.exe"),
+    Path(r"C:\Program Files\DesignBuilder\DesignBuilder.exe"),
+]
+
+
+def find_designbuilder(exe_path: Optional[str | Path] = None) -> Path:
+    """Locate the DesignBuilder executable.
+
+    Parameters
+    ----------
+    exe_path : str or Path, optional
+        Explicit path to DesignBuilder.exe.  Takes highest priority.
+
+    Returns
+    -------
+    Path
+        Resolved path to the executable.
+
+    Raises
+    ------
+    FileNotFoundError
+        If DesignBuilder cannot be found via any method.
+    """
+    # 1. Explicit argument
+    if exe_path is not None:
+        p = Path(exe_path)
+        if p.is_file():
+            return p
+        raise FileNotFoundError(f"DesignBuilder not found at: {p}")
+
+    # 2. Environment variable
+    env = os.environ.get(ENV_VAR)
+    if env:
+        p = Path(env)
+        if p.is_file():
+            return p
+        raise FileNotFoundError(
+            f"{ENV_VAR} is set to '{env}' but the file does not exist."
+        )
+
+    # 3. Common install locations
+    for p in DEFAULT_INSTALL_PATHS:
+        if p.is_file():
+            return p
+
+    # 4. System PATH
+    which = shutil.which("DesignBuilder")
+    if which:
+        return Path(which)
+
+    raise FileNotFoundError(
+        "Could not find DesignBuilder.exe. "
+        f"Set the {ENV_VAR} environment variable or pass the path explicitly."
+    )

db_process/runner.py

@@ -0,0 +1,298 @@
+"""
+runner.py
+====================================
+Run DesignBuilder as a subprocess with support for blocking and
+non-blocking execution, timeouts, and idle-detection termination.
+
+This module unifies the execution patterns from ``designbuilder_schema``
+(blocking with error capture) and ``db-batch`` (Popen + idle monitoring).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Union
+
+import psutil
+
+from db_process.commands import ProcessChain
+from db_process.executable import find_designbuilder
+
+
+# ---------------------------------------------------------------------------
+# Result dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RunResult:
+    """Outcome of a DesignBuilder process execution."""
+
+    success: bool
+    """Whether the process completed without error."""
+
+    returncode: Optional[int] = None
+    """Process return code (None if killed or not yet finished)."""
+
+    stdout: str = ""
+    """Captured stdout (blocking mode only)."""
+
+    stderr: str = ""
+    """Captured stderr (blocking mode only)."""
+
+    timed_out: bool = False
+    """True if the process was killed due to timeout."""
+
+    killed_idle: bool = False
+    """True if the process was killed by idle detection."""
+
+    duration_seconds: Optional[float] = None
+    """Wall-clock duration of the run in seconds."""
+
+
+# ---------------------------------------------------------------------------
+# Process management
+# ---------------------------------------------------------------------------
+
+DESIGNBUILDER_PROCESS_NAME = "DesignBuilder.exe"
+
+
+def find_process(name: str = DESIGNBUILDER_PROCESS_NAME) -> Optional[psutil.Process]:
+    """Find a running process by name.
+
+    Returns the first matching process, or None.
+    """
+    for p in psutil.process_iter(["name"]):
+        try:
+            if p.info["name"] == name:
+                return p
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            continue
+    return None
+
+
+def kill_process(name: str = DESIGNBUILDER_PROCESS_NAME) -> bool:
+    """Terminate a DesignBuilder process forcefully.
+
+    Returns True if a process was found and killed, False otherwise.
+    """
+    proc = find_process(name)
+    if proc is None:
+        return False
+
+    proc.kill()
+    proc.wait(timeout=5)
+    return True
+
+
+def kill_when_idle(
+    name: str = DESIGNBUILDER_PROCESS_NAME,
+    *,
+    idle_threshold: float = 10,
+    check_interval: float = 0.5,
+    startup_period: float = 20,
+    cpu_threshold: float = 0.1,
+) -> bool:
+    """Monitor a process and kill it once CPU usage stays below threshold.
+
+    The function blocks until the process is killed or exits on its own.
+
+    Parameters
+    ----------
+    name : str
+        Process name to monitor.
+    idle_threshold : float
+        Seconds the process must be idle before termination.
+    check_interval : float
+        Polling interval in seconds.
+    startup_period : float
+        Grace period before idle detection begins.
+    cpu_threshold : float
+        CPU percentage below which the process is considered idle.
+
+    Returns
+    -------
+    bool
+        True if the process was killed due to idle, False if it
+        exited on its own or was not found.
+    """
+    proc = find_process(name)
+    if proc is None:
+        return False
+
+    idle_time = 0.0
+    has_been_active = False
+
+    try:
+        if startup_period > 0:
+            time.sleep(startup_period)
+
+        while proc.is_running():
+            cpu = proc.cpu_percent(interval=0.1)
+
+            if cpu >= cpu_threshold:
+                has_been_active = True
+                idle_time = 0.0
+            elif has_been_active:
+                idle_time += check_interval
+                if idle_time >= idle_threshold:
+                    proc.kill()
+                    proc.wait(timeout=5)
+                    return True
+
+            time.sleep(check_interval)
+
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        pass
+
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Blocking execution
+# ---------------------------------------------------------------------------
+
+def run(
+    model_path: Union[str, Path],
+    process_chain: Optional[ProcessChain] = None,
+    *,
+    exe_path: Optional[Union[str, Path]] = None,
+    timeout: Optional[int] = None,
+) -> RunResult:
+    """Run DesignBuilder in blocking mode and wait for completion.
+
+    Parameters
+    ----------
+    model_path : str or Path
+        Path to the .dsb model file.
+    process_chain : ProcessChain, optional
+        Commands to execute.  When None, DesignBuilder opens the file
+        without processing (useful for XML import).
+    exe_path : str or Path, optional
+        Explicit path to DesignBuilder.exe.
+    timeout : int, optional
+        Maximum seconds to wait.  None means wait indefinitely.
+
+    Returns
+    -------
+    RunResult
+        Outcome of the execution.
+    """
+    exe = find_designbuilder(exe_path)
+    model = Path(model_path)
+
+    cmd = [str(exe), str(model)]
+    if process_chain is not None:
+        cmd.append(process_chain.to_string())
+
+    t0 = time.monotonic()
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        duration = time.monotonic() - t0
+        return RunResult(
+            success=result.returncode == 0,
+            returncode=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            duration_seconds=duration,
+        )
+    except subprocess.TimeoutExpired:
+        duration = time.monotonic() - t0
+        kill_process()
+        return RunResult(
+            success=False,
+            timed_out=True,
+            duration_seconds=duration,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Non-blocking execution
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RunHandle:
+    """Handle for a non-blocking DesignBuilder process.
+
+    Use :meth:`wait`, :meth:`kill`, or :meth:`kill_when_idle` to
+    manage the process after launch.
+    """
+
+    process: subprocess.Popen
+    """The underlying Popen object."""
+
+    start_time: float = field(default_factory=time.monotonic)
+    """Monotonic timestamp when the process was launched."""
+
+    def is_running(self) -> bool:
+        """Check if the process is still running."""
+        return self.process.poll() is None
+
+    def wait(self, timeout: Optional[int] = None) -> RunResult:
+        """Block until the process finishes or timeout expires."""
+        try:
+            self.process.wait(timeout=timeout)
+            duration = time.monotonic() - self.start_time
+            return RunResult(
+                success=self.process.returncode == 0,
+                returncode=self.process.returncode,
+                duration_seconds=duration,
+            )
+        except subprocess.TimeoutExpired:
+            duration = time.monotonic() - self.start_time
+            kill_process()
+            return RunResult(
+                success=False,
+                timed_out=True,
+                duration_seconds=duration,
+            )
+
+    def kill(self) -> None:
+        """Terminate the process immediately."""
+        kill_process()
+
+    def kill_when_idle(self, **kwargs) -> bool:
+        """Monitor and kill the process when it becomes idle.
+
+        Accepts the same keyword arguments as :func:`kill_when_idle`.
+        This call blocks until the process is killed or exits.
+        """
+        return kill_when_idle(**kwargs)
+
+
+def run_async(
+    model_path: Union[str, Path],
+    process_chain: Optional[ProcessChain] = None,
+    *,
+    exe_path: Optional[Union[str, Path]] = None,
+) -> RunHandle:
+    """Launch DesignBuilder in non-blocking mode.
+
+    Returns a :class:`RunHandle` that can be used to wait for
+    completion, kill the process, or monitor for idle termination.
+
+    Parameters
+    ----------
+    model_path : str or Path
+        Path to the .dsb model file.
+    process_chain : ProcessChain, optional
+        Commands to execute.
+    exe_path : str or Path, optional
+        Explicit path to DesignBuilder.exe.
+
+    Returns
+    -------
+    RunHandle
+        Handle for the launched process.
+    """
+    exe = find_designbuilder(exe_path)
+    model = Path(model_path)
+
+    cmd = [str(exe), str(model)]
+    if process_chain is not None:
+        cmd.append(process_chain.to_string())
+
+    proc = subprocess.Popen(cmd)
+    return RunHandle(process=proc)

db_process-0.1.0.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: db-process
+Version: 0.1.0
+Summary: Python interface to DesignBuilder command line processing.
+Author-email: Bartlomiej Tokarzewski <bartlomiej.tokarzewski@gmail.com>
+Project-URL: Homepage, https://github.com/tokarzewski/db-process
+Project-URL: Bug Tracker, https://github.com/tokarzewski/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
+DesignBuilder command line processing

db_process-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+db_process/__init__.py,sha256=Zf8vIjye2ejV3CZJP1HUyCA5F8dSIrm14_eMcoTgKLk,1822
+db_process/commands.py,sha256=1E1EMxkx8lWLBbD5z4hZFEMRZV8XGbFU2xFzX92aXlY,12470
+db_process/executable.py,sha256=0nQ38-x6OWUpd11ac3DRziwX8mHMz5xtI9xOyTXauAY,1957
+db_process/runner.py,sha256=HMWbykseGAuKSgtmsIFv1xjRWI69QD0d8p5PwgmrCiQ,8633
+db_process-0.1.0.dist-info/licenses/LICENSE,sha256=Dik23IwCfTKw3e2cSounRZn27EeAI421gnZ9vzgWdJw,1088
+db_process-0.1.0.dist-info/METADATA,sha256=WHV8vRgg4EI5lV5v7jw3vk9flDBBaa0orFkoknHxRFA,635
+db_process-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+db_process-0.1.0.dist-info/top_level.txt,sha256=yOsVAh7uYY7yuQvrtzeyg05CLpYbNjePhNn1V16XloI,11
+db_process-0.1.0.dist-info/RECORD,,

db_process-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

db_process-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tokarzewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

db_process-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+db_process