energyplus-toolkit 0.1.0__tar.gz

energyplus_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: energyplus-toolkit
+Version: 0.1.0
+Summary: Tools for EnergyPlus input files: parse, write back and reformat IDD and IDF files, and the IDF in EnergyPlus C++ unit tests.
+Author-email: Julien Marrec <contact@effibem.com>
+License: MIT
+Project-URL: Homepage, https://effibem.com
+Project-URL: Repository, https://github.com/jmarrec/energyplus-toolkit
+Project-URL: Issues, https://github.com/jmarrec/energyplus-toolkit/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.2; extra == "test"
+Requires-Dist: pytest-cov>=7.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.5.0; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Requires-Dist: bump2version>=1.0.1; extra == "dev"
+Requires-Dist: mypy>=1.19.0; extra == "dev"
+Requires-Dist: flake8>=7.3.0; extra == "dev"
+Requires-Dist: flake8-docstrings>=1.7.0; extra == "dev"
+Requires-Dist: black>=25.12.0; extra == "dev"
+Requires-Dist: isort>=7.0.0; extra == "dev"
+
+# energyplus-toolkit
+
+[![pypi](https://img.shields.io/pypi/v/energyplus-toolkit.svg)](https://pypi.org/project/energyplus-toolkit/)
+[![python](https://img.shields.io/pypi/pyversions/energyplus-toolkit.svg)](https://pypi.org/project/energyplus-toolkit/)
+[![Build Status](https://github.com/jmarrec/energyplus-toolkit/actions/workflows/dev.yml/badge.svg)](https://github.com/jmarrec/energyplus-toolkit/actions/workflows/dev.yml)
+
+Tools for [EnergyPlus](https://energyplus.net) input files:
+
+- parse IDD and IDF files, link each IDF object and field to its IDD definition, and write them back faithfully;
+- reformat IDF and IDD files, and the IDF embedded in EnergyPlus C++ unit tests, from the command line or as
+  pre-commit hooks.
+
+* GitHub: <https://github.com/jmarrec/energyplus-toolkit>
+* PyPI: <https://pypi.org/project/energyplus-toolkit/>
+
+## Installation
+
+```bash
+pip install energyplus-toolkit
+```
+
+Requires Python 3.11+.
+
+For development:
+
+```bash
+pip install -e ".[dev,test]"  # With the dev tools (pre-commit, black, isort, flake8, mypy) and the tests (pytest)
+pre-commit install
+```
+
+## Command line
+
+```shell
+# Reformat in place, like black: files and/or folders (searched recursively), in parallel
+energyplus-toolkit format idf --idd Energy+.idd testfiles/
+energyplus-toolkit format idd Energy+.idd
+energyplus-toolkit format unit-test --idd Energy+.idd tst/EnergyPlus/unit
+
+# Only look: list the files that would change (exit 1 if any), or print a diff
+energyplus-toolkit format idf --idd Energy+.idd --check testfiles/
+energyplus-toolkit format idf --idd Energy+.idd --diff testfiles/1ZoneUncontrolled.idf
+```
+
+Options (see `--help`): `--exclude REGEX`, `-j N` workers, `-q` quiet, `-o OUTPUT` (single file, `-` for stdout),
+and for IDF / unit tests `--leading N` (spaces before object names) and `--keep-integer-reals` (keep `8` instead of
+writing `8.0` in a real field).
+
+Exit codes: 0 when done, 1 if `--check` found files to reformat, 123 on error.
+
+Content is never lost: a file or block that can't be reformatted safely (unknown object, text outside a field, IMF or
+parametric file, C++ code building the IDF...) is left unchanged, with a warning.
+
+## pre-commit hooks
+
+```yaml
+- repo: https://github.com/jmarrec/energyplus-toolkit
+  rev: v0.1.0
+  hooks:
+  - id: energyplus-format-idd
+    args: [--idd, idd/Energy+.idd.in]
+  - id: energyplus-format-idf
+    args: [--idd, idd/Energy+.idd.in, -q]
+  - id: energyplus-format-unit-test
+    args: [--idd, idd/Energy+.idd.in, -q]
+```
+
+Each hook needs the IDD to use (`--idd`). For unit tests, put the hook before clang-format: reformatting then
+clang-format is stable.
+
+## Library
+
+The IDD gives each IDF object and field its definition: type, units, default, choices, extensible groups...
+
+```python
+from pathlib import Path
+
+from energyplus_toolkit.input.idd.idd_file import IddFile
+from energyplus_toolkit.input.idf.idf_file import IdfFile
+from energyplus_toolkit.input.idf.idf_object import IdfObject
+
+idd = IddFile.load(Path("Energy+.idd"))
+
+# A whole IDF file: each object is linked to its IDD object
+idf = IdfFile.load("in.idf", idd)  # or IdfFile.loads(text, idd)
+for zone in idf.get_objects_by_type("Zone"):
+    print(zone.name, zone.getDouble(1), zone.getDouble(1, return_default=True))  # "Z2 None 0.0" if left blank
+idf.save("out.idf", overwrite=True)  # or str(idf)
+
+# A single object, from its text and its IDD object
+zone = IdfObject.load(idd_object=idd.getObject("Zone"), text="Zone,Z3,90;")
+zone.setDouble(1, 45.0)
+print(zone)
+# Zone,
+#   Z3,                      !- Name
+#   45.0;                    !- Direction of Relative North {deg}
+
+# Or built from scratch, with extensible groups
+branch = IdfObject(idd_object=idd.getObject("Branch"))
+branch.setString(0, "Supply Branch")
+branch.push_extensible_group(["Pump:VariableSpeed", "Pump", "Pump-Inlet", "Pump-Outlet"])
+
+# The IDD side
+field = idd.getObject("Zone").fields[1]
+print(field.name, field.properties.type, field.properties.units, field.properties.stringDefault)
+# Direction of Relative North real deg 0
+```
+
+Values are validated against the IDD when set (types, choices, bounds), and the IDF is written with its comments
+(`!- Field Name {units}`) and the layout the IDD asks for (`\format`: vertices, compact schedules...).
+
+## Layout
+
+- `energyplus_toolkit/input`: the EnergyPlus input data model (IDD and IDF objects, fields, their types), read from and
+  written to files. It doesn't depend on the tools, so it can become its own package.
+- `energyplus_toolkit/format`: the formatter (parallel runner, C++ unit tests: see `format/cpp/README.md`).
+- `energyplus_toolkit/cli.py`: the `energyplus-toolkit` command.

energyplus_toolkit-0.1.0/README.md

@@ -0,0 +1,116 @@
+# energyplus-toolkit
+
+[![pypi](https://img.shields.io/pypi/v/energyplus-toolkit.svg)](https://pypi.org/project/energyplus-toolkit/)
+[![python](https://img.shields.io/pypi/pyversions/energyplus-toolkit.svg)](https://pypi.org/project/energyplus-toolkit/)
+[![Build Status](https://github.com/jmarrec/energyplus-toolkit/actions/workflows/dev.yml/badge.svg)](https://github.com/jmarrec/energyplus-toolkit/actions/workflows/dev.yml)
+
+Tools for [EnergyPlus](https://energyplus.net) input files:
+
+- parse IDD and IDF files, link each IDF object and field to its IDD definition, and write them back faithfully;
+- reformat IDF and IDD files, and the IDF embedded in EnergyPlus C++ unit tests, from the command line or as
+  pre-commit hooks.
+
+* GitHub: <https://github.com/jmarrec/energyplus-toolkit>
+* PyPI: <https://pypi.org/project/energyplus-toolkit/>
+
+## Installation
+
+```bash
+pip install energyplus-toolkit
+```
+
+Requires Python 3.11+.
+
+For development:
+
+```bash
+pip install -e ".[dev,test]"  # With the dev tools (pre-commit, black, isort, flake8, mypy) and the tests (pytest)
+pre-commit install
+```
+
+## Command line
+
+```shell
+# Reformat in place, like black: files and/or folders (searched recursively), in parallel
+energyplus-toolkit format idf --idd Energy+.idd testfiles/
+energyplus-toolkit format idd Energy+.idd
+energyplus-toolkit format unit-test --idd Energy+.idd tst/EnergyPlus/unit
+
+# Only look: list the files that would change (exit 1 if any), or print a diff
+energyplus-toolkit format idf --idd Energy+.idd --check testfiles/
+energyplus-toolkit format idf --idd Energy+.idd --diff testfiles/1ZoneUncontrolled.idf
+```
+
+Options (see `--help`): `--exclude REGEX`, `-j N` workers, `-q` quiet, `-o OUTPUT` (single file, `-` for stdout),
+and for IDF / unit tests `--leading N` (spaces before object names) and `--keep-integer-reals` (keep `8` instead of
+writing `8.0` in a real field).
+
+Exit codes: 0 when done, 1 if `--check` found files to reformat, 123 on error.
+
+Content is never lost: a file or block that can't be reformatted safely (unknown object, text outside a field, IMF or
+parametric file, C++ code building the IDF...) is left unchanged, with a warning.
+
+## pre-commit hooks
+
+```yaml
+- repo: https://github.com/jmarrec/energyplus-toolkit
+  rev: v0.1.0
+  hooks:
+  - id: energyplus-format-idd
+    args: [--idd, idd/Energy+.idd.in]
+  - id: energyplus-format-idf
+    args: [--idd, idd/Energy+.idd.in, -q]
+  - id: energyplus-format-unit-test
+    args: [--idd, idd/Energy+.idd.in, -q]
+```
+
+Each hook needs the IDD to use (`--idd`). For unit tests, put the hook before clang-format: reformatting then
+clang-format is stable.
+
+## Library
+
+The IDD gives each IDF object and field its definition: type, units, default, choices, extensible groups...
+
+```python
+from pathlib import Path
+
+from energyplus_toolkit.input.idd.idd_file import IddFile
+from energyplus_toolkit.input.idf.idf_file import IdfFile
+from energyplus_toolkit.input.idf.idf_object import IdfObject
+
+idd = IddFile.load(Path("Energy+.idd"))
+
+# A whole IDF file: each object is linked to its IDD object
+idf = IdfFile.load("in.idf", idd)  # or IdfFile.loads(text, idd)
+for zone in idf.get_objects_by_type("Zone"):
+    print(zone.name, zone.getDouble(1), zone.getDouble(1, return_default=True))  # "Z2 None 0.0" if left blank
+idf.save("out.idf", overwrite=True)  # or str(idf)
+
+# A single object, from its text and its IDD object
+zone = IdfObject.load(idd_object=idd.getObject("Zone"), text="Zone,Z3,90;")
+zone.setDouble(1, 45.0)
+print(zone)
+# Zone,
+#   Z3,                      !- Name
+#   45.0;                    !- Direction of Relative North {deg}
+
+# Or built from scratch, with extensible groups
+branch = IdfObject(idd_object=idd.getObject("Branch"))
+branch.setString(0, "Supply Branch")
+branch.push_extensible_group(["Pump:VariableSpeed", "Pump", "Pump-Inlet", "Pump-Outlet"])
+
+# The IDD side
+field = idd.getObject("Zone").fields[1]
+print(field.name, field.properties.type, field.properties.units, field.properties.stringDefault)
+# Direction of Relative North real deg 0
+```
+
+Values are validated against the IDD when set (types, choices, bounds), and the IDF is written with its comments
+(`!- Field Name {units}`) and the layout the IDD asks for (`\format`: vertices, compact schedules...).
+
+## Layout
+
+- `energyplus_toolkit/input`: the EnergyPlus input data model (IDD and IDF objects, fields, their types), read from and
+  written to files. It doesn't depend on the tools, so it can become its own package.
+- `energyplus_toolkit/format`: the formatter (parallel runner, C++ unit tests: see `format/cpp/README.md`).
+- `energyplus_toolkit/cli.py`: the `energyplus-toolkit` command.

energyplus_toolkit-0.1.0/energyplus_toolkit/__init__.py

@@ -0,0 +1,5 @@
+"""Top-level package for energyplus-toolkit."""
+
+__author__ = """Julien Marrec"""
+__email__ = 'contact@effibem.com'
+__version__ = '0.1.0'

energyplus_toolkit-0.1.0/energyplus_toolkit/cli.py

@@ -0,0 +1,150 @@
+"""Command-line interface: energyplus-toolkit COMMAND ...
+
+energyplus-toolkit format idf|idd|unit-test PATH...: works like black, give it files and/or folders, they are
+reformatted in place, in parallel. Use --check or --diff to only see what would change.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from energyplus_toolkit.format import runner
+from energyplus_toolkit.format.runner import Job, Kind, Mode
+from energyplus_toolkit.input.idf import idf_constants
+
+DESCRIPTIONS = {
+    Kind.IDF: "Reformat EnergyPlus IDF files.",
+    Kind.IDD: "Reformat EnergyPlus IDD files.",
+    Kind.UNIT_TEST: (
+        'Reformat the IDF embedded in EnergyPlus C++ unit tests, in delimited_string({...}) and R"IDF(...)IDF" blocks.'
+    ),
+}
+
+
+def _add_format_subcommand(subparsers, name: str, kind: Kind) -> None:
+    p = subparsers.add_parser(name, help=DESCRIPTIONS[kind], description=DESCRIPTIONS[kind])
+    patterns = ", ".join(f"*{s}" for s in kind.suffixes)
+    p.add_argument(
+        "paths",
+        type=Path,
+        nargs="+",
+        metavar="PATH",
+        help=f"Files or folders. Folders are searched recursively for {patterns}.",
+    )
+    if kind.needs_idd:
+        p.add_argument(
+            "--idd", dest="idd_path", type=Path, required=True, metavar="IDD_PATH", help="Path to the IDD file."
+        )
+    mode = p.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--check", action="store_true", help="Don't write: list the files that would change, exit 1 if any."
+    )
+    mode.add_argument("--diff", action="store_true", help="Don't write: print a unified diff of the changes.")
+    mode.add_argument(
+        "-o",
+        "--output",
+        dest="output_path",
+        type=Path,
+        metavar="OUTPUT_PATH",
+        help="Write to this file instead of in place ('-' for stdout). Only with a single input file.",
+    )
+    p.add_argument(
+        "--exclude",
+        type=re.compile,
+        metavar="REGEX",
+        help="Skip files found in folders whose path matches this regex. Files given explicitly are always processed.",
+    )
+    p.add_argument(
+        "-j",
+        "--workers",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Number of parallel processes (default: number of CPUs).",
+    )
+    p.add_argument("-q", "--quiet", action="store_true", help="Only print errors and the summary.")
+    if kind is not Kind.IDD:
+        p.add_argument(
+            "--leading",
+            dest="idf_leading",
+            type=int,
+            default=None,
+            metavar="N",
+            help=f"Leading spaces before each object-type line (default: {idf_constants.IDF_LEADING}).",
+        )
+        p.add_argument(
+            "--keep-integer-reals",
+            action="store_true",
+            help='Keep a number written as an integer as is in a real field ("8" instead of "8.0").',
+        )
+    p.set_defaults(kind=kind)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="energyplus-toolkit", description="Tools for EnergyPlus input files.")
+    commands = parser.add_subparsers(dest="command", metavar="COMMAND")
+    commands.required = True
+
+    format_parser = commands.add_parser(
+        "format", help="Reformat EnergyPlus files.", description="Reformat EnergyPlus files."
+    )
+    kinds = format_parser.add_subparsers(dest="kind_name", metavar="KIND")
+    kinds.required = True
+    _add_format_subcommand(kinds, "idf", Kind.IDF)
+    _add_format_subcommand(kinds, "idd", Kind.IDD)
+    _add_format_subcommand(kinds, "unit-test", Kind.UNIT_TEST)
+    return parser
+
+
+def _make_job(args, parser: argparse.ArgumentParser) -> Job:
+    kind: Kind = args.kind
+    idd_path = getattr(args, "idd_path", None)
+    if idd_path is not None and not idd_path.is_file():
+        parser.error(f"IDD file not found: {idd_path}")
+    constants: list[tuple[str, object]] = []
+    if getattr(args, "idf_leading", None) is not None:
+        if args.idf_leading < 0:
+            parser.error("--leading must be a non-negative integer.")
+        constants.append(("IDF_LEADING", args.idf_leading))
+    if getattr(args, "keep_integer_reals", False):
+        constants.append(("IDF_KEEP_INTEGER_REALS", True))
+    mode = Mode.CHECK if args.check else Mode.DIFF if args.diff else Mode.WRITE
+    return Job(kind=kind, mode=mode, idd_path=idd_path, constants=tuple(constants))
+
+
+def main(args_: list[str] | None = None) -> int:
+    parser = get_parser()
+    args = parser.parse_args(args_)
+
+    for path in args.paths:
+        if not path.exists():
+            parser.error(f"path not found: {path}")
+    if args.workers is not None and args.workers < 1:
+        parser.error("--workers must be at least 1.")
+    job = _make_job(args, parser)
+
+    if args.output_path is not None:
+        # Single file, written elsewhere
+        if len(args.paths) != 1 or args.paths[0].is_dir():
+            parser.error("-o/--output needs exactly one input file.")
+        runner.init_worker(job)
+        text = runner.reformat_text(job.kind, args.paths[0].read_text(encoding="utf-8"))
+        if str(args.output_path) == "-":
+            sys.stdout.write(text)
+        else:
+            args.output_path.write_text(text, encoding="utf-8")
+        return 0
+
+    files = runner.collect_files(args.paths, job.kind, args.exclude)
+    if not files:
+        print("No files to reformat.", file=sys.stderr)
+        return 0
+    results = runner.run(files, job, workers=args.workers)
+    return runner.report(results, job, quiet=args.quiet)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

energyplus_toolkit-0.1.0/energyplus_toolkit/format/__init__.py

@@ -0,0 +1 @@
+"""Formatting EnergyPlus files: IDF, IDD, and the IDF in EnergyPlus C++ unit tests."""