Results API

Simulation result container and output file access.

SimulationResult

idfkit.simulation.result.SimulationResult dataclass

Result of an EnergyPlus simulation run.

Attributes:

Name	Type	Description
run_dir	Path	Directory containing all simulation output.
success	bool	Whether the simulation exited successfully.
exit_code	int | None	Process exit code (None if timed out).
stdout	str	Captured standard output.
stderr	str	Captured standard error.
runtime_seconds	float	Wall-clock execution time in seconds.
output_prefix	str	Output file prefix (default "eplus").
fs	FileSystem | None	Optional sync file system backend for reading output files.
async_fs	AsyncFileSystem | None	Optional async file system backend for non-blocking reads. Set automatically by async_simulate when an AsyncFileSystem is provided.
migration_report	MigrationReport | None	Populated when simulate(..., auto_migrate=True) forward-migrated the model before running. None when no migration occurred.

Source code in idfkit/simulation/result.py

@dataclass(slots=True)
class SimulationResult:
    """Result of an EnergyPlus simulation run.

    Attributes:
        run_dir: Directory containing all simulation output.
        success: Whether the simulation exited successfully.
        exit_code: Process exit code (None if timed out).
        stdout: Captured standard output.
        stderr: Captured standard error.
        runtime_seconds: Wall-clock execution time in seconds.
        output_prefix: Output file prefix (default "eplus").
        fs: Optional sync file system backend for reading output files.
        async_fs: Optional async file system backend for non-blocking reads.
            Set automatically by [async_simulate][idfkit.simulation.async_runner.async_simulate] when an
            [AsyncFileSystem][idfkit.simulation.fs.AsyncFileSystem] is provided.
        migration_report: Populated when ``simulate(..., auto_migrate=True)``
            forward-migrated the model before running. ``None`` when no
            migration occurred.
    """

    run_dir: Path
    success: bool
    exit_code: int | None
    stdout: str
    stderr: str
    runtime_seconds: float
    output_prefix: str = "eplus"
    fs: FileSystem | None = field(default=None, repr=False)
    async_fs: AsyncFileSystem | None = field(default=None, repr=False)
    migration_report: MigrationReport | None = field(default=None, repr=False)
    _cached_errors: Any = field(default=_UNSET, init=False, repr=False)
    _cached_sql: Any = field(default=_UNSET, init=False, repr=False)
    _cached_variables: Any = field(default=_UNSET, init=False, repr=False)
    _cached_csv: Any = field(default=_UNSET, init=False, repr=False)
    _cached_html: Any = field(default=_UNSET, init=False, repr=False)
    _cached_eso: Any = field(default=_UNSET, init=False, repr=False)
    _cached_mtr: Any = field(default=_UNSET, init=False, repr=False)

    def __post_init__(self) -> None:
        if self.fs is not None and self.async_fs is not None:
            msg = "fs and async_fs are mutually exclusive — provide one or neither"
            raise ValueError(msg)

    def close(self) -> None:
        """Release any open file handles held by cached parsers.

        Closes the SQLite connection opened lazily by [sql][idfkit.simulation.result.SimulationResult.sql] /
        [async_sql][idfkit.simulation.result.SimulationResult.async_sql] (and removes the temporary copy made
        for remote file systems). The other parsers read their files eagerly
        and hold no handles, so this is currently a no-op for them.

        Call this — or use the result as a context manager — before deleting
        the run directory. On Windows an open SQLite connection locks
        ``eplus.sql`` and blocks ``shutil.rmtree`` / ``TemporaryDirectory``
        cleanup with ``PermissionError [WinError 32]``. Safe to call more
        than once; the cached connection is reopened on next access if needed.
        """
        cached = object.__getattribute__(self, "_cached_sql")
        if cached is not _UNSET and cached is not None:
            cached.close()
        object.__setattr__(self, "_cached_sql", _UNSET)

    def __enter__(self) -> SimulationResult:
        return self

    def __exit__(self, *exc: object) -> None:
        self.close()

    @property
    def errors(self) -> ErrorReport:
        """Parsed error report from the .err file (lazily cached).

        Returns:
            Parsed ErrorReport from the simulation's .err output.
        """
        cached = object.__getattribute__(self, "_cached_errors")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        err = self.err_path
        if err is None:
            report = ErrorReport.from_string("")
        elif self.fs is not None:
            text = self.fs.read_text(str(err), encoding="latin-1")
            report = ErrorReport.from_string(text)
        else:
            report = ErrorReport.from_file(err)
        object.__setattr__(self, "_cached_errors", report)
        return report

    @property
    def sql(self) -> SQLResult | None:
        """Parsed SQL output database (lazily cached).

        Returns:
            An SQLResult for querying time-series and tabular data,
            or None if no .sql file was produced.
        """
        cached = object.__getattribute__(self, "_cached_sql")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = self.sql_path
        if path is None:
            object.__setattr__(self, "_cached_sql", None)
            return None
        from .parsers.sql import SQLResult as _SQLResult

        if self.fs is not None:
            # sqlite3 requires a local file — download to a temp file
            data = self.fs.read_bytes(str(path))
            with tempfile.NamedTemporaryFile(suffix=".sql", delete=False) as tmp_file:
                tmp_file.write(data)
            result: SQLResult = _SQLResult(Path(tmp_file.name), _owns_file=True)
        else:
            result = _SQLResult(path)
        object.__setattr__(self, "_cached_sql", result)
        return result

    @property
    def variables(self) -> OutputVariableIndex | None:
        """Output variable/meter index from .rdd/.mdd files (lazily cached).

        Returns:
            An OutputVariableIndex for searching and injecting output
            variables, or None if no .rdd file was produced.
        """
        cached = object.__getattribute__(self, "_cached_variables")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        rdd = self.rdd_path
        if rdd is None:
            object.__setattr__(self, "_cached_variables", None)
            return None

        if self.fs is not None:
            from .parsers.rdd import parse_mdd, parse_rdd

            rdd_text = self.fs.read_text(str(rdd), encoding="latin-1")
            variables = parse_rdd(rdd_text)
            mdd = self.mdd_path
            meters = parse_mdd(self.fs.read_text(str(mdd), encoding="latin-1")) if mdd is not None else ()
            from .outputs import OutputVariableIndex as _OutputVariableIndex

            result: OutputVariableIndex = _OutputVariableIndex(variables=variables, meters=meters)
        else:
            from .outputs import OutputVariableIndex as _OutputVariableIndex

            result = _OutputVariableIndex.from_files(rdd, self.mdd_path)
        object.__setattr__(self, "_cached_variables", result)
        return result

    @property
    def csv(self) -> CSVResult | None:
        """Parsed CSV output (lazily cached).

        Returns:
            A CSVResult with extracted column metadata and values,
            or None if no .csv file was produced.
        """
        cached = object.__getattribute__(self, "_cached_csv")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = self.csv_path
        if path is None:
            object.__setattr__(self, "_cached_csv", None)
            return None
        from .parsers.csv import CSVResult as _CSVResult

        if self.fs is not None:
            text = self.fs.read_text(str(path), encoding="latin-1")
            result: CSVResult = _CSVResult.from_string(text)
        else:
            result = _CSVResult.from_file(path)
        object.__setattr__(self, "_cached_csv", result)
        return result

    @property
    def html(self) -> HTMLResult | None:
        """Parsed HTML tabular output (lazily cached).

        Returns:
            An HTMLResult with extracted tables and titles,
            or None if no HTML file was produced.
        """
        cached = object.__getattribute__(self, "_cached_html")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = self.html_path
        if path is None:
            object.__setattr__(self, "_cached_html", None)
            return None
        from .parsers.html import HTMLResult as _HTMLResult

        if self.fs is not None:
            text = self.fs.read_text(str(path), encoding="latin-1")
            result: HTMLResult = _HTMLResult.from_string(text)
        else:
            result = _HTMLResult.from_file(path)
        object.__setattr__(self, "_cached_html", result)
        return result

    def _load_eso_sync(self, path: Path) -> ESOResult:
        """Read and parse an ESO/MTR file from disk or the sync file system."""
        from .parsers.eso import ESOResult as _ESOResult

        if self.fs is not None:
            return _ESOResult.from_bytes(self.fs.read_bytes(str(path)))
        return _ESOResult.from_file(path)

    @property
    def eso(self) -> ESOResult | None:
        """Parsed ESO time-series output (lazily cached).

        Returns:
            An ESOResult for extracting variable time series, or None if no
            .eso file was produced.
        """
        cached = object.__getattribute__(self, "_cached_eso")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = self.eso_path
        if path is None:
            object.__setattr__(self, "_cached_eso", None)
            return None
        result = self._load_eso_sync(path)
        object.__setattr__(self, "_cached_eso", result)
        return result

    @property
    def mtr(self) -> ESOResult | None:
        """Parsed MTR meter time-series output (lazily cached).

        The .mtr meter file uses the same format as .eso, so it is parsed by the
        same reader.

        Returns:
            An ESOResult for extracting meter time series, or None if no .mtr
            file was produced.
        """
        cached = object.__getattribute__(self, "_cached_mtr")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = self.mtr_path
        if path is None:
            object.__setattr__(self, "_cached_mtr", None)
            return None
        result = self._load_eso_sync(path)
        object.__setattr__(self, "_cached_mtr", result)
        return result

    @property
    def sql_path(self) -> Path | None:
        """Path to the SQLite output file, if present."""
        return self._find_output_file(".sql")

    @property
    def err_path(self) -> Path | None:
        """Path to the .err output file, if present."""
        return self._find_output_file(".err")

    @property
    def eso_path(self) -> Path | None:
        """Path to the .eso output file, if present."""
        return self._find_output_file(".eso")

    @property
    def mtr_path(self) -> Path | None:
        """Path to the .mtr meter output file, if present."""
        return self._find_output_file(".mtr")

    @property
    def csv_path(self) -> Path | None:
        """Path to the .csv output file, if present."""
        return self._find_output_file(".csv")

    @property
    def html_path(self) -> Path | None:
        """Path to the HTML tabular output file, if present."""
        return (
            self._find_output_file("Table.htm")
            or self._find_output_file("Table.html")
            or self._find_output_file(".htm")
            or self._find_output_file(".html")
        )

    @property
    def rdd_path(self) -> Path | None:
        """Path to the .rdd output file, if present."""
        return self._find_output_file(".rdd")

    @property
    def mdd_path(self) -> Path | None:
        """Path to the .mdd output file, if present."""
        return self._find_output_file(".mdd")

    def _find_output_file(self, suffix: str) -> Path | None:
        """Find an output file by suffix.

        Looks for ``{prefix}out{suffix}`` first, then falls back to
        scanning the run directory for any file with the given suffix.

        Args:
            suffix: File suffix to look for (e.g. ".sql", ".err").

        Returns:
            Path to the file, or None if not found.

        Raises:
            RuntimeError: If only [async_fs][idfkit.simulation.result.SimulationResult.async_fs] is set (no sync access
                available).  Use the ``async_*`` methods instead.
        """
        if self.async_fs is not None and self.fs is None:
            msg = (
                "This SimulationResult was created with an AsyncFileSystem. "
                "Use the async accessors (e.g. async_errors(), async_sql()) "
                "instead of the sync properties."
            )
            raise RuntimeError(msg)

        primary = self.run_dir / f"{self.output_prefix}out{suffix}"

        if self.fs is not None:
            if self.fs.exists(str(primary)):
                return primary
            # Fallback: glob for matching files
            matches = self.fs.glob(str(self.run_dir), f"*{suffix}")
            if matches:
                return Path(matches[0])
            return None

        # Local path-based lookup
        if primary.is_file():
            return primary

        # Fallback: scan directory
        for p in self.run_dir.iterdir():
            if p.is_file() and p.name.endswith(suffix):
                return p

        return None

    # ------------------------------------------------------------------
    # Async accessors — non-blocking counterparts to the sync properties
    # ------------------------------------------------------------------

    async def async_errors(self) -> ErrorReport:
        """Parsed error report from the .err file (async, lazily cached).

        Non-blocking counterpart to [errors][idfkit.simulation.result.SimulationResult.errors] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            Parsed ErrorReport from the simulation's .err output.
        """
        cached = object.__getattribute__(self, "_cached_errors")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        err = await self._async_find_output_file(".err")
        if err is None:
            report = ErrorReport.from_string("")
        elif self.async_fs is not None:
            text = await self.async_fs.read_text(str(err), encoding="latin-1")
            report = ErrorReport.from_string(text)
        elif self.fs is not None:
            text = self.fs.read_text(str(err), encoding="latin-1")
            report = ErrorReport.from_string(text)
        else:
            report = ErrorReport.from_file(err)
        object.__setattr__(self, "_cached_errors", report)
        return report

    async def async_sql(self) -> SQLResult | None:
        """Parsed SQL output database (async, lazily cached).

        Non-blocking counterpart to [sql][idfkit.simulation.result.SimulationResult.sql] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            An SQLResult for querying time-series and tabular data,
            or None if no .sql file was produced.
        """
        cached = object.__getattribute__(self, "_cached_sql")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = await self._async_find_output_file(".sql")
        if path is None:
            object.__setattr__(self, "_cached_sql", None)
            return None
        from .parsers.sql import SQLResult as _SQLResult

        if self.async_fs is not None:
            data = await self.async_fs.read_bytes(str(path))
            with tempfile.NamedTemporaryFile(suffix=".sql", delete=False) as tmp_file:
                tmp_file.write(data)
            result: SQLResult = _SQLResult(Path(tmp_file.name), _owns_file=True)
        elif self.fs is not None:
            data = self.fs.read_bytes(str(path))
            with tempfile.NamedTemporaryFile(suffix=".sql", delete=False) as tmp_file:
                tmp_file.write(data)
            result = _SQLResult(Path(tmp_file.name), _owns_file=True)
        else:
            result = _SQLResult(path)
        object.__setattr__(self, "_cached_sql", result)
        return result

    async def async_variables(self) -> OutputVariableIndex | None:
        """Output variable/meter index (async, lazily cached).

        Non-blocking counterpart to [variables][idfkit.simulation.result.SimulationResult.variables] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            An OutputVariableIndex for searching and injecting output
            variables, or None if no .rdd file was produced.
        """
        cached = object.__getattribute__(self, "_cached_variables")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        rdd = await self._async_find_output_file(".rdd")
        if rdd is None:
            object.__setattr__(self, "_cached_variables", None)
            return None

        if self.async_fs is not None:
            from .parsers.rdd import parse_mdd, parse_rdd

            rdd_text = await self.async_fs.read_text(str(rdd), encoding="latin-1")
            variables = parse_rdd(rdd_text)
            mdd = await self._async_find_output_file(".mdd")
            meters = parse_mdd(await self.async_fs.read_text(str(mdd), encoding="latin-1")) if mdd is not None else ()
            from .outputs import OutputVariableIndex as _OutputVariableIndex

            result: OutputVariableIndex = _OutputVariableIndex(variables=variables, meters=meters)
        elif self.fs is not None:
            from .parsers.rdd import parse_mdd, parse_rdd

            rdd_text = self.fs.read_text(str(rdd), encoding="latin-1")
            variables = parse_rdd(rdd_text)
            mdd = self._find_output_file(".mdd")
            meters = parse_mdd(self.fs.read_text(str(mdd), encoding="latin-1")) if mdd is not None else ()
            from .outputs import OutputVariableIndex as _OutputVariableIndex

            result = _OutputVariableIndex(variables=variables, meters=meters)
        else:
            from .outputs import OutputVariableIndex as _OutputVariableIndex

            result = _OutputVariableIndex.from_files(rdd, self.mdd_path)
        object.__setattr__(self, "_cached_variables", result)
        return result

    async def async_csv(self) -> CSVResult | None:
        """Parsed CSV output (async, lazily cached).

        Non-blocking counterpart to [csv][idfkit.simulation.result.SimulationResult.csv] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            A CSVResult with extracted column metadata and values,
            or None if no .csv file was produced.
        """
        cached = object.__getattribute__(self, "_cached_csv")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = await self._async_find_output_file(".csv")
        if path is None:
            object.__setattr__(self, "_cached_csv", None)
            return None
        from .parsers.csv import CSVResult as _CSVResult

        if self.async_fs is not None:
            text = await self.async_fs.read_text(str(path), encoding="latin-1")
            result: CSVResult = _CSVResult.from_string(text)
        elif self.fs is not None:
            text = self.fs.read_text(str(path), encoding="latin-1")
            result = _CSVResult.from_string(text)
        else:
            result = _CSVResult.from_file(path)
        object.__setattr__(self, "_cached_csv", result)
        return result

    async def async_html(self) -> HTMLResult | None:
        """Parsed HTML tabular output (async, lazily cached).

        Non-blocking counterpart to [html][idfkit.simulation.result.SimulationResult.html] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            An HTMLResult with extracted tables and titles,
            or None if no HTML file was produced.
        """
        cached = object.__getattribute__(self, "_cached_html")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = (
            await self._async_find_output_file("Table.htm")
            or await self._async_find_output_file("Table.html")
            or await self._async_find_output_file(".htm")
            or await self._async_find_output_file(".html")
        )
        if path is None:
            object.__setattr__(self, "_cached_html", None)
            return None
        from .parsers.html import HTMLResult as _HTMLResult

        if self.async_fs is not None:
            text = await self.async_fs.read_text(str(path), encoding="latin-1")
            result: HTMLResult = _HTMLResult.from_string(text)
        elif self.fs is not None:
            text = self.fs.read_text(str(path), encoding="latin-1")
            result = _HTMLResult.from_string(text)
        else:
            result = _HTMLResult.from_file(path)
        object.__setattr__(self, "_cached_html", result)
        return result

    async def _load_eso_async(self, path: Path) -> ESOResult:
        """Read and parse an ESO/MTR file via the async/sync file system or disk."""
        from .parsers.eso import ESOResult as _ESOResult

        if self.async_fs is not None:
            return _ESOResult.from_bytes(await self.async_fs.read_bytes(str(path)))
        if self.fs is not None:
            return _ESOResult.from_bytes(self.fs.read_bytes(str(path)))
        return _ESOResult.from_file(path)

    async def async_eso(self) -> ESOResult | None:
        """Parsed ESO time-series output (async, lazily cached).

        Non-blocking counterpart to [eso][idfkit.simulation.result.SimulationResult.eso] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            An ESOResult, or None if no .eso file was produced.
        """
        cached = object.__getattribute__(self, "_cached_eso")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = await self._async_find_output_file(".eso")
        if path is None:
            object.__setattr__(self, "_cached_eso", None)
            return None
        result = await self._load_eso_async(path)
        object.__setattr__(self, "_cached_eso", result)
        return result

    async def async_mtr(self) -> ESOResult | None:
        """Parsed MTR meter time-series output (async, lazily cached).

        Non-blocking counterpart to [mtr][idfkit.simulation.result.SimulationResult.mtr] that uses
        [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

        Returns:
            An ESOResult, or None if no .mtr file was produced.
        """
        cached = object.__getattribute__(self, "_cached_mtr")
        if cached is not _UNSET:
            return cached  # type: ignore[no-any-return]
        path = await self._async_find_output_file(".mtr")
        if path is None:
            object.__setattr__(self, "_cached_mtr", None)
            return None
        result = await self._load_eso_async(path)
        object.__setattr__(self, "_cached_mtr", result)
        return result

    async def _async_find_output_file(self, suffix: str) -> Path | None:
        """Async counterpart to [_find_output_file][].

        Uses [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for non-blocking file lookups, falling back
        to [fs][] or local path checks.

        Args:
            suffix: File suffix to look for (e.g. ".sql", ".err").

        Returns:
            Path to the file, or None if not found.
        """
        primary = self.run_dir / f"{self.output_prefix}out{suffix}"

        if self.async_fs is not None:
            if await self.async_fs.exists(str(primary)):
                return primary
            matches = await self.async_fs.glob(str(self.run_dir), f"*{suffix}")
            if matches:
                return Path(matches[0])
            return None

        if self.fs is not None:
            if self.fs.exists(str(primary)):
                return primary
            matches = self.fs.glob(str(self.run_dir), f"*{suffix}")
            if matches:
                return Path(matches[0])
            return None

        # Local path-based lookup
        if primary.is_file():
            return primary

        for p in self.run_dir.iterdir():
            if p.is_file() and p.name.endswith(suffix):
                return p

        return None

    @classmethod
    def from_directory(
        cls,
        path: str | Path,
        *,
        output_prefix: str = "eplus",
        fs: FileSystem | None = None,
        async_fs: AsyncFileSystem | None = None,
    ) -> SimulationResult:
        """Reconstruct a SimulationResult from an existing output directory.

        Useful for inspecting results from a previous simulation run.

        Args:
            path: Path to the simulation output directory.
            output_prefix: Output file prefix used during the run.
            fs: Optional sync file system backend for reading output files.
            async_fs: Optional async file system backend for non-blocking reads.

        Returns:
            SimulationResult pointing to the existing output.
        """
        run_dir = Path(path) if (fs is not None or async_fs is not None) else Path(path).resolve()
        return cls(
            run_dir=run_dir,
            success=True,
            exit_code=0,
            stdout="",
            stderr="",
            runtime_seconds=0.0,
            output_prefix=output_prefix,
            fs=fs,
            async_fs=async_fs,
        )

async_fs = field(default=None, repr=False) class-attribute instance-attribute

csv property

Parsed CSV output (lazily cached).

Returns:

Type	Description
CSVResult | None	A CSVResult with extracted column metadata and values,
CSVResult | None	or None if no .csv file was produced.

csv_path property

Path to the .csv output file, if present.

err_path property

Path to the .err output file, if present.

errors property

Parsed error report from the .err file (lazily cached).

Returns:

Type	Description
ErrorReport	Parsed ErrorReport from the simulation's .err output.

eso property

Parsed ESO time-series output (lazily cached).

Returns:

Type	Description
ESOResult | None	An ESOResult for extracting variable time series, or None if no
ESOResult | None	.eso file was produced.

eso_path property

Path to the .eso output file, if present.

exit_code instance-attribute

fs = field(default=None, repr=False) class-attribute instance-attribute

html property

Parsed HTML tabular output (lazily cached).

Returns:

Type	Description
HTMLResult | None	An HTMLResult with extracted tables and titles,
HTMLResult | None	or None if no HTML file was produced.

html_path property

Path to the HTML tabular output file, if present.

mdd_path property

Path to the .mdd output file, if present.

migration_report = field(default=None, repr=False) class-attribute instance-attribute

mtr property

Parsed MTR meter time-series output (lazily cached).

The .mtr meter file uses the same format as .eso, so it is parsed by the same reader.

Returns:

Type	Description
ESOResult | None	An ESOResult for extracting meter time series, or None if no .mtr
ESOResult | None	file was produced.

mtr_path property

Path to the .mtr meter output file, if present.

output_prefix = 'eplus' class-attribute instance-attribute

rdd_path property

Path to the .rdd output file, if present.

run_dir instance-attribute

runtime_seconds instance-attribute

sql property

Parsed SQL output database (lazily cached).

Returns:

Type	Description
SQLResult | None	An SQLResult for querying time-series and tabular data,
SQLResult | None	or None if no .sql file was produced.

sql_path property

Path to the SQLite output file, if present.

stderr instance-attribute

stdout instance-attribute

success instance-attribute

variables property

Output variable/meter index from .rdd/.mdd files (lazily cached).

Returns:

Type	Description
OutputVariableIndex | None	An OutputVariableIndex for searching and injecting output
OutputVariableIndex | None	variables, or None if no .rdd file was produced.

async_csv() async

Parsed CSV output (async, lazily cached).

Non-blocking counterpart to csv that uses async_fs for file reads.

Returns:

Type	Description
CSVResult | None	A CSVResult with extracted column metadata and values,
CSVResult | None	or None if no .csv file was produced.

Source code in idfkit/simulation/result.py

async def async_csv(self) -> CSVResult | None:
    """Parsed CSV output (async, lazily cached).

    Non-blocking counterpart to [csv][idfkit.simulation.result.SimulationResult.csv] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        A CSVResult with extracted column metadata and values,
        or None if no .csv file was produced.
    """
    cached = object.__getattribute__(self, "_cached_csv")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    path = await self._async_find_output_file(".csv")
    if path is None:
        object.__setattr__(self, "_cached_csv", None)
        return None
    from .parsers.csv import CSVResult as _CSVResult

    if self.async_fs is not None:
        text = await self.async_fs.read_text(str(path), encoding="latin-1")
        result: CSVResult = _CSVResult.from_string(text)
    elif self.fs is not None:
        text = self.fs.read_text(str(path), encoding="latin-1")
        result = _CSVResult.from_string(text)
    else:
        result = _CSVResult.from_file(path)
    object.__setattr__(self, "_cached_csv", result)
    return result

async_errors() async

Parsed error report from the .err file (async, lazily cached).

Non-blocking counterpart to errors that uses async_fs for file reads.

Returns:

Type	Description
ErrorReport	Parsed ErrorReport from the simulation's .err output.

Source code in idfkit/simulation/result.py

async def async_errors(self) -> ErrorReport:
    """Parsed error report from the .err file (async, lazily cached).

    Non-blocking counterpart to [errors][idfkit.simulation.result.SimulationResult.errors] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        Parsed ErrorReport from the simulation's .err output.
    """
    cached = object.__getattribute__(self, "_cached_errors")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    err = await self._async_find_output_file(".err")
    if err is None:
        report = ErrorReport.from_string("")
    elif self.async_fs is not None:
        text = await self.async_fs.read_text(str(err), encoding="latin-1")
        report = ErrorReport.from_string(text)
    elif self.fs is not None:
        text = self.fs.read_text(str(err), encoding="latin-1")
        report = ErrorReport.from_string(text)
    else:
        report = ErrorReport.from_file(err)
    object.__setattr__(self, "_cached_errors", report)
    return report

async_eso() async

Parsed ESO time-series output (async, lazily cached).

Non-blocking counterpart to eso that uses async_fs for file reads.

Returns:

Type	Description
ESOResult | None	An ESOResult, or None if no .eso file was produced.

Source code in idfkit/simulation/result.py

async def async_eso(self) -> ESOResult | None:
    """Parsed ESO time-series output (async, lazily cached).

    Non-blocking counterpart to [eso][idfkit.simulation.result.SimulationResult.eso] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        An ESOResult, or None if no .eso file was produced.
    """
    cached = object.__getattribute__(self, "_cached_eso")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    path = await self._async_find_output_file(".eso")
    if path is None:
        object.__setattr__(self, "_cached_eso", None)
        return None
    result = await self._load_eso_async(path)
    object.__setattr__(self, "_cached_eso", result)
    return result

async_html() async

Parsed HTML tabular output (async, lazily cached).

Non-blocking counterpart to html that uses async_fs for file reads.

Returns:

Type	Description
HTMLResult | None	An HTMLResult with extracted tables and titles,
HTMLResult | None	or None if no HTML file was produced.

Source code in idfkit/simulation/result.py

async def async_html(self) -> HTMLResult | None:
    """Parsed HTML tabular output (async, lazily cached).

    Non-blocking counterpart to [html][idfkit.simulation.result.SimulationResult.html] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        An HTMLResult with extracted tables and titles,
        or None if no HTML file was produced.
    """
    cached = object.__getattribute__(self, "_cached_html")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    path = (
        await self._async_find_output_file("Table.htm")
        or await self._async_find_output_file("Table.html")
        or await self._async_find_output_file(".htm")
        or await self._async_find_output_file(".html")
    )
    if path is None:
        object.__setattr__(self, "_cached_html", None)
        return None
    from .parsers.html import HTMLResult as _HTMLResult

    if self.async_fs is not None:
        text = await self.async_fs.read_text(str(path), encoding="latin-1")
        result: HTMLResult = _HTMLResult.from_string(text)
    elif self.fs is not None:
        text = self.fs.read_text(str(path), encoding="latin-1")
        result = _HTMLResult.from_string(text)
    else:
        result = _HTMLResult.from_file(path)
    object.__setattr__(self, "_cached_html", result)
    return result

async_mtr() async

Parsed MTR meter time-series output (async, lazily cached).

Non-blocking counterpart to mtr that uses async_fs for file reads.

Returns:

Type	Description
ESOResult | None	An ESOResult, or None if no .mtr file was produced.

Source code in idfkit/simulation/result.py

async def async_mtr(self) -> ESOResult | None:
    """Parsed MTR meter time-series output (async, lazily cached).

    Non-blocking counterpart to [mtr][idfkit.simulation.result.SimulationResult.mtr] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        An ESOResult, or None if no .mtr file was produced.
    """
    cached = object.__getattribute__(self, "_cached_mtr")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    path = await self._async_find_output_file(".mtr")
    if path is None:
        object.__setattr__(self, "_cached_mtr", None)
        return None
    result = await self._load_eso_async(path)
    object.__setattr__(self, "_cached_mtr", result)
    return result

async_sql() async

Parsed SQL output database (async, lazily cached).

Non-blocking counterpart to sql that uses async_fs for file reads.

Returns:

Type	Description
SQLResult | None	An SQLResult for querying time-series and tabular data,
SQLResult | None	or None if no .sql file was produced.

Source code in idfkit/simulation/result.py

async def async_sql(self) -> SQLResult | None:
    """Parsed SQL output database (async, lazily cached).

    Non-blocking counterpart to [sql][idfkit.simulation.result.SimulationResult.sql] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        An SQLResult for querying time-series and tabular data,
        or None if no .sql file was produced.
    """
    cached = object.__getattribute__(self, "_cached_sql")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    path = await self._async_find_output_file(".sql")
    if path is None:
        object.__setattr__(self, "_cached_sql", None)
        return None
    from .parsers.sql import SQLResult as _SQLResult

    if self.async_fs is not None:
        data = await self.async_fs.read_bytes(str(path))
        with tempfile.NamedTemporaryFile(suffix=".sql", delete=False) as tmp_file:
            tmp_file.write(data)
        result: SQLResult = _SQLResult(Path(tmp_file.name), _owns_file=True)
    elif self.fs is not None:
        data = self.fs.read_bytes(str(path))
        with tempfile.NamedTemporaryFile(suffix=".sql", delete=False) as tmp_file:
            tmp_file.write(data)
        result = _SQLResult(Path(tmp_file.name), _owns_file=True)
    else:
        result = _SQLResult(path)
    object.__setattr__(self, "_cached_sql", result)
    return result

async_variables() async

Output variable/meter index (async, lazily cached).

Non-blocking counterpart to variables that uses async_fs for file reads.

Returns:

Type	Description
OutputVariableIndex | None	An OutputVariableIndex for searching and injecting output
OutputVariableIndex | None	variables, or None if no .rdd file was produced.

Source code in idfkit/simulation/result.py

async def async_variables(self) -> OutputVariableIndex | None:
    """Output variable/meter index (async, lazily cached).

    Non-blocking counterpart to [variables][idfkit.simulation.result.SimulationResult.variables] that uses
    [async_fs][idfkit.simulation.result.SimulationResult.async_fs] for file reads.

    Returns:
        An OutputVariableIndex for searching and injecting output
        variables, or None if no .rdd file was produced.
    """
    cached = object.__getattribute__(self, "_cached_variables")
    if cached is not _UNSET:
        return cached  # type: ignore[no-any-return]
    rdd = await self._async_find_output_file(".rdd")
    if rdd is None:
        object.__setattr__(self, "_cached_variables", None)
        return None

    if self.async_fs is not None:
        from .parsers.rdd import parse_mdd, parse_rdd

        rdd_text = await self.async_fs.read_text(str(rdd), encoding="latin-1")
        variables = parse_rdd(rdd_text)
        mdd = await self._async_find_output_file(".mdd")
        meters = parse_mdd(await self.async_fs.read_text(str(mdd), encoding="latin-1")) if mdd is not None else ()
        from .outputs import OutputVariableIndex as _OutputVariableIndex

        result: OutputVariableIndex = _OutputVariableIndex(variables=variables, meters=meters)
    elif self.fs is not None:
        from .parsers.rdd import parse_mdd, parse_rdd

        rdd_text = self.fs.read_text(str(rdd), encoding="latin-1")
        variables = parse_rdd(rdd_text)
        mdd = self._find_output_file(".mdd")
        meters = parse_mdd(self.fs.read_text(str(mdd), encoding="latin-1")) if mdd is not None else ()
        from .outputs import OutputVariableIndex as _OutputVariableIndex

        result = _OutputVariableIndex(variables=variables, meters=meters)
    else:
        from .outputs import OutputVariableIndex as _OutputVariableIndex

        result = _OutputVariableIndex.from_files(rdd, self.mdd_path)
    object.__setattr__(self, "_cached_variables", result)
    return result

close()

Release any open file handles held by cached parsers.

Closes the SQLite connection opened lazily by sql / async_sql (and removes the temporary copy made for remote file systems). The other parsers read their files eagerly and hold no handles, so this is currently a no-op for them.

Call this — or use the result as a context manager — before deleting the run directory. On Windows an open SQLite connection locks eplus.sql and blocks shutil.rmtree / TemporaryDirectory cleanup with PermissionError [WinError 32]. Safe to call more than once; the cached connection is reopened on next access if needed.

Source code in idfkit/simulation/result.py

def close(self) -> None:
    """Release any open file handles held by cached parsers.

    Closes the SQLite connection opened lazily by [sql][idfkit.simulation.result.SimulationResult.sql] /
    [async_sql][idfkit.simulation.result.SimulationResult.async_sql] (and removes the temporary copy made
    for remote file systems). The other parsers read their files eagerly
    and hold no handles, so this is currently a no-op for them.

    Call this — or use the result as a context manager — before deleting
    the run directory. On Windows an open SQLite connection locks
    ``eplus.sql`` and blocks ``shutil.rmtree`` / ``TemporaryDirectory``
    cleanup with ``PermissionError [WinError 32]``. Safe to call more
    than once; the cached connection is reopened on next access if needed.
    """
    cached = object.__getattribute__(self, "_cached_sql")
    if cached is not _UNSET and cached is not None:
        cached.close()
    object.__setattr__(self, "_cached_sql", _UNSET)

from_directory(path, *, output_prefix='eplus', fs=None, async_fs=None) classmethod

Reconstruct a SimulationResult from an existing output directory.

Useful for inspecting results from a previous simulation run.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the simulation output directory.	required
output_prefix	str	Output file prefix used during the run.	'eplus'
fs	FileSystem | None	Optional sync file system backend for reading output files.	None
async_fs	AsyncFileSystem | None	Optional async file system backend for non-blocking reads.	None

Returns:

Type	Description
SimulationResult	SimulationResult pointing to the existing output.

Source code in idfkit/simulation/result.py

@classmethod
def from_directory(
    cls,
    path: str | Path,
    *,
    output_prefix: str = "eplus",
    fs: FileSystem | None = None,
    async_fs: AsyncFileSystem | None = None,
) -> SimulationResult:
    """Reconstruct a SimulationResult from an existing output directory.

    Useful for inspecting results from a previous simulation run.

    Args:
        path: Path to the simulation output directory.
        output_prefix: Output file prefix used during the run.
        fs: Optional sync file system backend for reading output files.
        async_fs: Optional async file system backend for non-blocking reads.

    Returns:
        SimulationResult pointing to the existing output.
    """
    run_dir = Path(path) if (fs is not None or async_fs is not None) else Path(path).resolve()
    return cls(
        run_dir=run_dir,
        success=True,
        exit_code=0,
        stdout="",
        stderr="",
        runtime_seconds=0.0,
        output_prefix=output_prefix,
        fs=fs,
        async_fs=async_fs,
    )

ErrorReport

idfkit.simulation.parsers.err.ErrorReport dataclass

Parsed contents of an EnergyPlus .err file.

Attributes:

Name	Type	Description
fatal	tuple[ErrorMessage, ...]	Fatal error messages.
severe	tuple[ErrorMessage, ...]	Severe error messages.
warnings	tuple[ErrorMessage, ...]	Warning messages.
info	tuple[ErrorMessage, ...]	Informational messages.
warmup_converged	bool	Whether warmup convergence was reported.
simulation_complete	bool	Whether the simulation completed successfully.
raw_text	str	The original unparsed file text.

Source code in idfkit/simulation/parsers/err.py

@dataclass(frozen=True, slots=True)
class ErrorReport:
    """Parsed contents of an EnergyPlus .err file.

    Attributes:
        fatal: Fatal error messages.
        severe: Severe error messages.
        warnings: Warning messages.
        info: Informational messages.
        warmup_converged: Whether warmup convergence was reported.
        simulation_complete: Whether the simulation completed successfully.
        raw_text: The original unparsed file text.
    """

    fatal: tuple[ErrorMessage, ...]
    severe: tuple[ErrorMessage, ...]
    warnings: tuple[ErrorMessage, ...]
    info: tuple[ErrorMessage, ...]
    warmup_converged: bool
    simulation_complete: bool
    raw_text: str

    @property
    def has_fatal(self) -> bool:
        """Whether any fatal errors were found."""
        return len(self.fatal) > 0

    @property
    def has_severe(self) -> bool:
        """Whether any severe errors were found."""
        return len(self.severe) > 0

    @property
    def fatal_count(self) -> int:
        """Number of fatal errors."""
        return len(self.fatal)

    @property
    def severe_count(self) -> int:
        """Number of severe errors."""
        return len(self.severe)

    @property
    def error_count(self) -> int:
        """Total number of fatal + severe errors."""
        return len(self.fatal) + len(self.severe)

    @property
    def warning_count(self) -> int:
        """Total number of warnings."""
        return len(self.warnings)

    def summary(self) -> str:
        """Return a human-readable summary of the error report.

        Returns:
            A multi-line summary string.
        """
        lines: list[str] = []
        lines.append(
            f"Fatal: {len(self.fatal)}, Severe: {len(self.severe)}, "
            f"Warnings: {len(self.warnings)}, Info: {len(self.info)}"
        )
        if self.warmup_converged:
            lines.append("Warmup: converged")
        if self.simulation_complete:
            lines.append("Simulation: completed successfully")
        elif self.has_fatal:
            lines.append("Simulation: terminated with fatal error(s)")
        return "\n".join(lines)

    @classmethod
    def from_file(cls, path: str | Path) -> ErrorReport:
        """Parse an .err file from disk.

        Args:
            path: Path to the .err file.

        Returns:
            Parsed ErrorReport.
        """
        text = Path(path).read_text(encoding="latin-1")
        return _parse_err(text)

    @classmethod
    def from_string(cls, text: str) -> ErrorReport:
        """Parse .err content from a string.

        Args:
            text: Raw .err file contents.

        Returns:
            Parsed ErrorReport.
        """
        return _parse_err(text)

error_count property

Total number of fatal + severe errors.

fatal instance-attribute

fatal_count property

Number of fatal errors.

has_fatal property

Whether any fatal errors were found.

has_severe property

Whether any severe errors were found.

info instance-attribute

raw_text instance-attribute

severe instance-attribute

severe_count property

Number of severe errors.

simulation_complete instance-attribute

warmup_converged instance-attribute

warning_count property

Total number of warnings.

warnings instance-attribute

from_file(path) classmethod

Parse an .err file from disk.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the .err file.	required

Returns:

Type	Description
ErrorReport	Parsed ErrorReport.

Source code in idfkit/simulation/parsers/err.py

@classmethod
def from_file(cls, path: str | Path) -> ErrorReport:
    """Parse an .err file from disk.

    Args:
        path: Path to the .err file.

    Returns:
        Parsed ErrorReport.
    """
    text = Path(path).read_text(encoding="latin-1")
    return _parse_err(text)

from_string(text) classmethod

Parse .err content from a string.

Parameters:

Name	Type	Description	Default
text	str	Raw .err file contents.	required

Returns:

Type	Description
ErrorReport	Parsed ErrorReport.

Source code in idfkit/simulation/parsers/err.py

@classmethod
def from_string(cls, text: str) -> ErrorReport:
    """Parse .err content from a string.

    Args:
        text: Raw .err file contents.

    Returns:
        Parsed ErrorReport.
    """
    return _parse_err(text)

summary()

Return a human-readable summary of the error report.

Returns:

Type	Description
str	A multi-line summary string.

Source code in idfkit/simulation/parsers/err.py

def summary(self) -> str:
    """Return a human-readable summary of the error report.

    Returns:
        A multi-line summary string.
    """
    lines: list[str] = []
    lines.append(
        f"Fatal: {len(self.fatal)}, Severe: {len(self.severe)}, "
        f"Warnings: {len(self.warnings)}, Info: {len(self.info)}"
    )
    if self.warmup_converged:
        lines.append("Warmup: converged")
    if self.simulation_complete:
        lines.append("Simulation: completed successfully")
    elif self.has_fatal:
        lines.append("Simulation: terminated with fatal error(s)")
    return "\n".join(lines)

ErrorMessage

idfkit.simulation.parsers.err.ErrorMessage dataclass

A single error/warning message from EnergyPlus.

Attributes:

Name	Type	Description
severity	str	One of "Fatal", "Severe", "Warning", "Info".
message	str	The primary message text.
details	tuple[str, ...]	Additional continuation lines (** ~~~ ** lines).

Source code in idfkit/simulation/parsers/err.py

@dataclass(frozen=True, slots=True)
class ErrorMessage:
    """A single error/warning message from EnergyPlus.

    Attributes:
        severity: One of "Fatal", "Severe", "Warning", "Info".
        message: The primary message text.
        details: Additional continuation lines (``** ~~~   **`` lines).
    """

    severity: str
    message: str
    details: tuple[str, ...]

details instance-attribute

message instance-attribute

severity instance-attribute

HTMLResult

idfkit.simulation.parsers.html.HTMLResult dataclass

Parsed HTML tabular output from an EnergyPlus simulation.

Attributes:

Name	Type	Description
tables	list[HTMLTable]	All tables extracted from the file, in document order.

Source code in idfkit/simulation/parsers/html.py

@dataclass(slots=True)
class HTMLResult:
    """Parsed HTML tabular output from an EnergyPlus simulation.

    Attributes:
        tables: All tables extracted from the file, in document order.
    """

    tables: list[HTMLTable] = field(default_factory=lambda: [])

    @classmethod
    def from_file(cls, path: Path | str, encoding: str = "latin-1") -> HTMLResult:
        """Parse an EnergyPlus HTML output file.

        Args:
            path: Path to the HTML file (typically ``eplustblTable.html``
                or ``eplusoutTable.html``).
            encoding: File encoding (default ``latin-1``).

        Returns:
            Parsed [HTMLResult][idfkit.simulation.parsers.html.HTMLResult].
        """
        with open(path, encoding=encoding, errors="replace") as f:
            return cls.from_string(f.read())

    @classmethod
    def from_string(cls, html: str) -> HTMLResult:
        """Parse an HTML string.

        Args:
            html: The raw HTML content.

        Returns:
            Parsed [HTMLResult][idfkit.simulation.parsers.html.HTMLResult].
        """
        parser = _EnergyPlusHTMLParser()
        parser.feed(html)
        return cls(tables=parser.tables)

    def __len__(self) -> int:
        return len(self.tables)

    def __getitem__(self, index: int) -> HTMLTable:
        return self.tables[index]

    def __iter__(self) -> Iterator[HTMLTable]:
        return iter(self.tables)

    # ------------------------------------------------------------------
    # Convenience accessors (eppy-compatible patterns)
    # ------------------------------------------------------------------

    def titletable(self) -> list[tuple[str, list[list[str]]]]:
        """Return ``(title, rows)`` pairs like eppy's ``readhtml.titletable``.

        Each entry is ``(bold_title, [header_row, *data_rows])``.
        """
        result: list[tuple[str, list[list[str]]]] = []
        for t in self.tables:
            combined = [t.header, *t.rows] if t.header else list(t.rows)
            result.append((t.title, combined))
        return result

    def tablebyname(self, name: str) -> HTMLTable | None:
        """Find first table whose title contains *name* (case-insensitive)."""
        lower = name.lower()
        for t in self.tables:
            if lower in t.title.lower():
                return t
        return None

    def tablebyindex(self, index: int) -> HTMLTable | None:
        """Get a table by its zero-based position."""
        if 0 <= index < len(self.tables):
            return self.tables[index]
        return None

    def tablesbyreport(self, report_name: str) -> list[HTMLTable]:
        """Get all tables belonging to a specific report."""
        lower = report_name.lower()
        return [t for t in self.tables if lower in t.report_name.lower()]

tables = field(default_factory=lambda: []) class-attribute instance-attribute

from_file(path, encoding='latin-1') classmethod

Parse an EnergyPlus HTML output file.

Parameters:

Name	Type	Description	Default
path	Path | str	Path to the HTML file (typically eplustblTable.html or eplusoutTable.html).	required
encoding	str	File encoding (default latin-1).	'latin-1'

Returns:

Type	Description
HTMLResult	Parsed HTMLResult.

Source code in idfkit/simulation/parsers/html.py

@classmethod
def from_file(cls, path: Path | str, encoding: str = "latin-1") -> HTMLResult:
    """Parse an EnergyPlus HTML output file.

    Args:
        path: Path to the HTML file (typically ``eplustblTable.html``
            or ``eplusoutTable.html``).
        encoding: File encoding (default ``latin-1``).

    Returns:
        Parsed [HTMLResult][idfkit.simulation.parsers.html.HTMLResult].
    """
    with open(path, encoding=encoding, errors="replace") as f:
        return cls.from_string(f.read())

from_string(html) classmethod

Parse an HTML string.

Parameters:

Name	Type	Description	Default
html	str	The raw HTML content.	required

Returns:

Type	Description
HTMLResult	Parsed HTMLResult.

Source code in idfkit/simulation/parsers/html.py

@classmethod
def from_string(cls, html: str) -> HTMLResult:
    """Parse an HTML string.

    Args:
        html: The raw HTML content.

    Returns:
        Parsed [HTMLResult][idfkit.simulation.parsers.html.HTMLResult].
    """
    parser = _EnergyPlusHTMLParser()
    parser.feed(html)
    return cls(tables=parser.tables)

tablebyindex(index)

Get a table by its zero-based position.

Source code in idfkit/simulation/parsers/html.py

def tablebyindex(self, index: int) -> HTMLTable | None:
    """Get a table by its zero-based position."""
    if 0 <= index < len(self.tables):
        return self.tables[index]
    return None

tablebyname(name)

Find first table whose title contains name (case-insensitive).

Source code in idfkit/simulation/parsers/html.py

def tablebyname(self, name: str) -> HTMLTable | None:
    """Find first table whose title contains *name* (case-insensitive)."""
    lower = name.lower()
    for t in self.tables:
        if lower in t.title.lower():
            return t
    return None

tablesbyreport(report_name)

Get all tables belonging to a specific report.

Source code in idfkit/simulation/parsers/html.py

def tablesbyreport(self, report_name: str) -> list[HTMLTable]:
    """Get all tables belonging to a specific report."""
    lower = report_name.lower()
    return [t for t in self.tables if lower in t.report_name.lower()]

titletable()

Return (title, rows) pairs like eppy's readhtml.titletable.

Each entry is (bold_title, [header_row, *data_rows]).

Source code in idfkit/simulation/parsers/html.py

def titletable(self) -> list[tuple[str, list[list[str]]]]:
    """Return ``(title, rows)`` pairs like eppy's ``readhtml.titletable``.

    Each entry is ``(bold_title, [header_row, *data_rows])``.
    """
    result: list[tuple[str, list[list[str]]]] = []
    for t in self.tables:
        combined = [t.header, *t.rows] if t.header else list(t.rows)
        result.append((t.title, combined))
    return result

HTMLTable

idfkit.simulation.parsers.html.HTMLTable dataclass

A single table extracted from the EnergyPlus HTML output.

Attributes:

Name	Type	Description
title	str	The bold title preceding the table (e.g. "Site and Source Energy").
header	list[str]	Column headers (first <tr> with <th> cells).
rows	list[list[str]]	Data rows as lists of strings.
report_name	str	The top-level report name (e.g. "Annual Building Utility Performance Summary").
for_string	str	The "For:" qualifier (e.g. "Entire Facility").

Source code in idfkit/simulation/parsers/html.py

@dataclass(slots=True)
class HTMLTable:
    """A single table extracted from the EnergyPlus HTML output.

    Attributes:
        title: The bold title preceding the table (e.g.
            ``"Site and Source Energy"``).
        header: Column headers (first ``<tr>`` with ``<th>`` cells).
        rows: Data rows as lists of strings.
        report_name: The top-level report name (e.g.
            ``"Annual Building Utility Performance Summary"``).
        for_string: The ``"For:"`` qualifier (e.g. ``"Entire Facility"``).
    """

    title: str
    header: list[str]
    rows: list[list[str]]
    report_name: str = ""
    for_string: str = ""

    def to_dict(self) -> dict[str, dict[str, str]]:
        """Convert to a dict mapping row headers to {col_header: value}.

        The first column is treated as the row key.  Remaining columns
        are keyed by their respective column headers (starting at
        index 1).  Duplicate row keys are silently overwritten by the
        last occurrence.

        This gives convenient dict-style access similar to eppy's
        ``readhtml.named_grid_h``.
        """
        result: dict[str, dict[str, str]] = {}
        for row in self.rows:
            if not row:
                continue
            row_key = row[0]
            entry: dict[str, str] = {}
            for i in range(1, len(self.header)):
                if i < len(row):
                    entry[self.header[i]] = row[i]
            result[row_key] = entry
        return result

for_string = '' class-attribute instance-attribute

header instance-attribute

report_name = '' class-attribute instance-attribute

rows instance-attribute

title instance-attribute

to_dict()

Convert to a dict mapping row headers to {col_header: value}.

The first column is treated as the row key. Remaining columns are keyed by their respective column headers (starting at index 1). Duplicate row keys are silently overwritten by the last occurrence.

This gives convenient dict-style access similar to eppy's readhtml.named_grid_h.

Source code in idfkit/simulation/parsers/html.py

def to_dict(self) -> dict[str, dict[str, str]]:
    """Convert to a dict mapping row headers to {col_header: value}.

    The first column is treated as the row key.  Remaining columns
    are keyed by their respective column headers (starting at
    index 1).  Duplicate row keys are silently overwritten by the
    last occurrence.

    This gives convenient dict-style access similar to eppy's
    ``readhtml.named_grid_h``.
    """
    result: dict[str, dict[str, str]] = {}
    for row in self.rows:
        if not row:
            continue
        row_key = row[0]
        entry: dict[str, str] = {}
        for i in range(1, len(self.header)):
            if i < len(row):
                entry[self.header[i]] = row[i]
        result[row_key] = entry
    return result