energyplus-toolkit 0.2.0__tar.gz → 0.2.2__tar.gz

energyplus_toolkit-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Julien Marrec
+
+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.

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: energyplus-toolkit
-Version: 0.2.0
+Version: 0.2.2
 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
+License-Expression: 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: Intended Audience :: Science/Research
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Provides-Extra: test
 Requires-Dist: pytest>=9.0.2; extra == "test"
 Requires-Dist: pytest-cov>=7.0.0; extra == "test"
@@ -29,6 +30,7 @@ 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"
+Dynamic: license-file
 
 # energyplus-toolkit
 
@@ -42,8 +44,8 @@ Tools for [EnergyPlus](https://energyplus.net) input files:
 - 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/>
+- GitHub: <https://github.com/jmarrec/energyplus-toolkit>
+- PyPI: <https://pypi.org/project/energyplus-toolkit/>
 
 ## Installation
 
@@ -86,18 +88,22 @@ parametric file, C++ code building the IDF...) is left unchanged, with a warning
 
 ```yaml
 - repo: https://github.com/jmarrec/energyplus-toolkit
-  rev: v0.2.0
+  rev: v0.2.2
   hooks:
   - id: energyplus-format-idd
-    args: [--idd, idd/Energy+.idd.in]
+    args: [-q]
+    # Example to limit to a specific file
+    files: ^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.
+The IDF and unit test hooks need the IDD to use (`--idd`); the IDD hook doesn't take it.
+`files` is optional: it limits a hook to the paths matching this regex, here the one IDD to format.
+
+**Note:** For unit tests, put the hook before clang-format: reformatting then clang-format is stable.
 
 ## Library
 
@@ -113,7 +119,7 @@ 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)
+idf = IdfFile.load(Path("in.idf"), idd_file=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)
@@ -125,20 +131,25 @@ print(zone)
 # Zone,
 #   Z3,                      !- Name
 #   45.0;                    !- Direction of Relative North {deg}
+idf.add_object(obj=zone)
 
 # 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"])
 
+idf.remove_object(zone)
+idf.add_objects(objs=[zone, branch])
+assert idf.objects[-2:] == [zone, branch]
+
 # 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...).
+Values are validated against the IDD when set: types, choices (the casing is normalized), bounds.
+The IDF is written with its comments (`!- Field Name {units}`) and the layout the IDD asks for (`\format`: vertices, compact schedules...).
 
 ## Layout
 

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/README.md

@@ -10,8 +10,8 @@ Tools for [EnergyPlus](https://energyplus.net) input files:
 - 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/>
+- GitHub: <https://github.com/jmarrec/energyplus-toolkit>
+- PyPI: <https://pypi.org/project/energyplus-toolkit/>
 
 ## Installation
 
@@ -54,18 +54,22 @@ parametric file, C++ code building the IDF...) is left unchanged, with a warning
 
 ```yaml
 - repo: https://github.com/jmarrec/energyplus-toolkit
-  rev: v0.2.0
+  rev: v0.2.2
   hooks:
   - id: energyplus-format-idd
-    args: [--idd, idd/Energy+.idd.in]
+    args: [-q]
+    # Example to limit to a specific file
+    files: ^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.
+The IDF and unit test hooks need the IDD to use (`--idd`); the IDD hook doesn't take it.
+`files` is optional: it limits a hook to the paths matching this regex, here the one IDD to format.
+
+**Note:** For unit tests, put the hook before clang-format: reformatting then clang-format is stable.
 
 ## Library
 
@@ -81,7 +85,7 @@ 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)
+idf = IdfFile.load(Path("in.idf"), idd_file=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)
@@ -93,20 +97,25 @@ print(zone)
 # Zone,
 #   Z3,                      !- Name
 #   45.0;                    !- Direction of Relative North {deg}
+idf.add_object(obj=zone)
 
 # 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"])
 
+idf.remove_object(zone)
+idf.add_objects(objs=[zone, branch])
+assert idf.objects[-2:] == [zone, branch]
+
 # 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...).
+Values are validated against the IDD when set: types, choices (the casing is normalized), bounds.
+The IDF is written with its comments (`!- Field Name {units}`) and the layout the IDD asks for (`\format`: vertices, compact schedules...).
 
 ## Layout
 

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/energyplus_toolkit/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """Julien Marrec"""
 __email__ = 'contact@effibem.com'
-__version__ = '0.2.0'
+__version__ = '0.2.2'

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/energyplus_toolkit/input/idd/idd_field.py

@@ -272,6 +272,20 @@ class IddField:
         # Where the group number goes in its name, for an extensible field
         self._extensible_group_numbering: ExtensibleGroupNumbering | None = None
 
+    def _format_error(self, error_msg: str) -> str:
+        """Prefix ``error_msg`` with where it happened. The field name isn't known yet at the start of parsing."""
+        where = f"In '{self.objectName}'"
+        if self.name:
+            where += f", field '{self.name}'"
+        return f"{where}: {error_msg}"
+
+    def _parse_float(self, tag: str, value: str) -> float:
+        """Parse the numeric value of the ``tag`` property (default, minimum, maximum)."""
+        try:
+            return float(value)
+        except ValueError:
+            raise ValueError(self._format_error(f"Invalid \\{tag} value '{value}'")) from None
+
     def _parse_property(self, text: str):
         if not text:
             return
@@ -306,7 +320,7 @@ class IddField:
                     if any(x in lower_text for x in ['autosize', 'autocalculate']):
                         self.properties.numericDefault = AUTOSIZE_VALUE
                     else:
-                        self.properties.numericDefault = float(string_default)
+                        self.properties.numericDefault = self._parse_float(tag=tag, value=string_default)
 
             elif lower_text.startswith("deprecated"):
                 self.properties.deprecated = True
@@ -323,9 +337,7 @@ class IddField:
         elif index == 'f':
             if lower_text.startswith("field"):
                 # The name is on the field's first line ("A1 , \field Name"): another \field line is malformed
-                raise IddFieldParseError(
-                    f"Duplicate \\field line '\\{text}' in field '{self.name}' of object '{self.objectName}'"
-                )
+                raise IddFieldParseError(self._format_error(f"Duplicate \\field line '\\{text}'"))
 
         # === i ===
         elif index == 'i':
@@ -338,7 +350,7 @@ class IddField:
             if lower_text.startswith(tag := "key"):
                 key_name = text[len(tag) :].split('!')[0].strip()
                 if not key_name:
-                    raise ValueError(f"Key name is empty in field '{self.name}' of object '{self.objectName}'")
+                    raise ValueError(self._format_error("Key name is empty"))
                 key_note = ""
                 if '!' in text:
                     key_note = text.split('!')[1].strip()
@@ -353,7 +365,7 @@ class IddField:
                     rest = rest[1:].strip()
                 else:
                     self.properties.minBoundType = BoundTypes.InclusiveBound
-                self.properties.minBoundValue = float(rest)
+                self.properties.minBoundValue = self._parse_float(tag=tag, value=rest)
                 not_handled = False
             elif lower_text.startswith(tag := "maximum"):
                 rest = text[len(tag) :].split('!')[0].strip()
@@ -362,11 +374,17 @@ class IddField:
                     rest = rest[1:].strip()
                 else:
                     self.properties.maxBoundType = BoundTypes.InclusiveBound
-                self.properties.maxBoundValue = float(rest)
+                self.properties.maxBoundValue = self._parse_float(tag=tag, value=rest)
                 not_handled = False
 
-            elif lower_text.startswith("memo"):
-                raise ValueError("Memo property is deprecated; use Note property instead.")
+            elif lower_text.startswith(tag := "memo"):
+                LOG.warning(self._format_error("Memo property is deprecated; use Note property instead."))
+                note = text[len(tag) :].strip()
+                if not self.properties.note:
+                    self.properties.note = note
+                else:
+                    self.properties.note += "\n" + note
+                not_handled = False
         # === n ===
         elif index == 'n':
             if lower_text.startswith(tag := "note"):
@@ -421,7 +439,7 @@ class IddField:
 
         # === if none matched ===
         if not_handled:
-            raise ValueError(f"Unknown field property text '{text}' detected in field '{self.name}'")
+            raise ValueError(self._format_error(f"Unknown field property text '{text}'"))
 
     @staticmethod
     def load(objectName: str, field_lines: list[str]) -> "IddField":
@@ -431,7 +449,7 @@ class IddField:
 
     def _parse(self, field_lines: list[str]) -> None:
         if not field_lines:
-            raise ValueError(f"No lines provided to parse for field in object '{self.objectName}'")
+            raise ValueError(self._format_error("No lines provided to parse for field"))
 
         field_lines = [x.strip() for x in field_lines]
         n_lines = len(field_lines)
@@ -439,7 +457,9 @@ class IddField:
         line_number = 0
         self.is_last_field = ';' in field_lines[line_number]
         if '\\field' not in field_lines[line_number]:
-            raise IddFieldParseError(f"First line of field does not contain '\\field': '{field_lines[line_number]}'")
+            raise IddFieldParseError(
+                self._format_error(f"First line of field does not contain '\\field': '{field_lines[line_number]}'")
+            )
         self.field_id = field_lines[line_number].replace(',', ';').split(';', maxsplit=1)[0]
         self.field_id = self.field_id.strip()
 
@@ -456,14 +476,14 @@ class IddField:
             # Default numerics to real
             self.properties.type = IddFieldType.RealType
         else:
-            raise IddFieldParseError(f"Unknown field type identifier found: '{fieldTypeChar}'")
+            raise IddFieldParseError(self._format_error(f"Unknown field type identifier found: '{fieldTypeChar}'"))
 
         # Parse each metadata comment line (\keyword ...)
         while line_number < n_lines:
             line = field_lines[line_number]
-            line_number += 1
             if not line.startswith('\\'):
                 break
+            line_number += 1
 
             # Delegate actual parsing
             self._parse_property(text=line[1:])
@@ -474,19 +494,16 @@ class IddField:
             line_number += 1
             if not line or line.startswith('!'):
                 continue
-            raise IddFieldParseError(
-                f"Unexpected content found after field properties: '{line}', "
-                f"in field '{self.name}' of object '{self.objectName}'"
-            )
+            raise IddFieldParseError(self._format_error(f"Unexpected content found after field properties: '{line}'"))
 
         # Validation
         if self.properties.type == IddFieldType.ChoiceType and not self.keys:
-            LOG.error(f"Field is of type choice but keys are empty: '{self.name}'")
+            LOG.error(self._format_error("Field is of type choice but keys are empty"))
         elif self.properties.type != IddFieldType.ChoiceType and self.keys:
-            LOG.error(f"Field is not of type choice but has non-empty keys: '{self.name}'")
+            LOG.error(self._format_error("Field is not of type choice but has non-empty keys"))
 
         if self.properties.type == IddFieldType.UnknownType:
-            raise IddFieldParseError(f"Field is of unknown type after parsing: '{self.name}'")
+            raise IddFieldParseError(self._format_error("Field is of unknown type after parsing"))
 
     def is_name_field(self) -> bool:
         """Return True if this field represents the name of the object.
@@ -511,7 +528,7 @@ class IddField:
         ``name_for_group`` appends it.
         """
         if self.extensible:
-            raise ValueError(f"Field '{self.name}' of object '{self.objectName}' is already marked extensible")
+            raise ValueError(self._format_error("Field is already marked extensible"))
         self.extensible = True
         self._extensible_group_numbering = ExtensibleGroupNumbering.parse(name=self.name)
         self.name = self._extensible_group_numbering.base_name

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/energyplus_toolkit/input/idf/idf_field.py

@@ -2,12 +2,16 @@ import logging
 import re
 from abc import ABC, abstractmethod
 from enum import StrEnum
+from typing import TYPE_CHECKING
 
 from energyplus_toolkit.input.idd.idd_constants import AUTOSIZE_VALUE
 from energyplus_toolkit.input.idd.idd_field import BoundTypes, IddField, IddFieldProperties, IddFieldType
 from energyplus_toolkit.input.idf import idf_constants
 from energyplus_toolkit.input.idf.idf_constants import format_idf_field
 
+if TYPE_CHECKING:
+    from energyplus_toolkit.input.idf.idf_object import IdfObject
+
 LOG = logging.getLogger("IdfField")
 
 
@@ -22,13 +26,31 @@ class FieldValidationError(ValueError):
 
 
 class IdfField(ABC):
-    def __init__(self, idd_field: IddField) -> None:
+    def __init__(self, idd_field: IddField, parent: "IdfObject | None" = None, group_index: int | None = None) -> None:
         self._value: str | float | int | None = None
         self._default_value: str | float | int | None = None
         self.idd_field: IddField = idd_field
         self._default_value = idd_field.properties.stringDefault
         self.is_last_field = idd_field.is_last_field
         self.comment: str | None = None  # user-provided field comment; None = use IDD field name
+        # The IdfObject that owns this field, to say where an error happened
+        self.parent: "IdfObject | None" = parent
+        # for an extensible field: its group in the parent
+        self.group_index: int | None = group_index
+
+    @property
+    def name(self) -> str:
+        """The field name, numbered by group for an extensible field: "Vertex 3 X-coordinate"."""
+        if self.group_index is None:
+            return self.idd_field.name
+        return self.idd_field.name_for_group(self.group_index)
+
+    def _format_error(self, error_msg: str) -> str:
+        """Prefix ``error_msg`` with where it happened."""
+        where = f"In '{self.idd_field.objectName}'"
+        if self.parent is not None and (object_name := self.parent.name):
+            where += f" named '{object_name}'"
+        return f"{where}, field '{self.name}': {error_msg}"
 
     @property
     def required(self):
@@ -37,35 +59,37 @@ class IdfField(ABC):
         return props.required and not props.stringDefault
 
     @staticmethod
-    def from_idd_field(idd_field) -> "IdfField":
+    def from_idd_field(
+        idd_field: IddField, parent: "IdfObject | None" = None, group_index: int | None = None
+    ) -> "IdfField":
         field_type = idd_field.properties.type
 
-        field: IdfField
+        field_class: type[IdfField]
         if field_type == IddFieldType.AlphaType:
-            field = AlphaField(idd_field=idd_field)
+            field_class = AlphaField
         elif field_type == IddFieldType.IntegerType:
-            field = IntegerField(idd_field=idd_field)
+            field_class = IntegerField
         elif field_type == IddFieldType.RealType:
-            field = RealField(idd_field=idd_field)
+            field_class = RealField
         elif field_type == IddFieldType.ChoiceType:
             if (idd_field.objectName.lower(), idd_field.name.lower()) == ("schedule:week:compact", "daytype list"):
-                field = DayTypeListField(idd_field=idd_field)
+                field_class = DayTypeListField
             else:
-                field = ChoiceField(idd_field=idd_field)
+                field_class = ChoiceField
         elif field_type == IddFieldType.NodeType:
-            field = NodeField(idd_field=idd_field)
+            field_class = NodeField
         elif field_type == IddFieldType.ObjectListType:
-            field = ObjectListField(idd_field=idd_field)
+            field_class = ObjectListField
         elif field_type == IddFieldType.ExternalListType:
-            field = ExternalListField(idd_field=idd_field)
+            field_class = ExternalListField
         elif field_type == IddFieldType.URLType:
-            field = URLField(idd_field=idd_field)
+            field_class = URLField
         elif field_type == IddFieldType.HandleType:
-            field = HandleField(idd_field=idd_field)
+            field_class = HandleField
         else:
-            raise ValueError(f"Unknown field type: {field_type} for field {idd_field.name}")
+            raise ValueError(f"In '{idd_field.objectName}', field '{idd_field.name}': Unknown field type: {field_type}")
 
-        return field
+        return field_class(idd_field=idd_field, parent=parent, group_index=group_index)
 
     @abstractmethod
     def setString(self, value: str):
@@ -74,7 +98,7 @@ class IdfField(ABC):
     @abstractmethod
     def validate(self):
         if self.required and self.value(return_default=True) is None:
-            raise FieldValidationError("Required field with no default value")
+            raise FieldValidationError(self._format_error("Required field with no default value"))
 
     def value(self, return_default: bool = False) -> str | float | int | None:
         if self._value is not None:
@@ -88,7 +112,7 @@ class IdfField(ABC):
 
     def reset(self):
         if self.required and self.value(return_default=True) is None:
-            raise FieldValidationError("Cannot reset a required field with no default value")
+            raise FieldValidationError(self._format_error("Cannot reset a required field with no default value"))
         self._value = None
 
     def value_text(self) -> str:
@@ -96,12 +120,12 @@ class IdfField(ABC):
         v = self.value(return_default=False)
         return "" if v is None else str(v)
 
-    def text(self, is_last_field: bool = False, field_name: str | None = None) -> str:
-        """The field's IDF line. ``field_name`` (for the ``!-`` comment) defaults to the IDD field name."""
+    def text(self, is_last_field: bool = False) -> str:
+        """The field's IDF line."""
         return format_idf_field(
             value=self.value_text(),
             is_last_field=is_last_field,
-            field_name=self.idd_field.name if field_name is None else field_name,
+            field_name=self.name,
             comment=self.comment,
             units=self.idd_field.properties.units,
         )
@@ -115,9 +139,6 @@ class IdfField(ABC):
 
 
 class AlphaField(IdfField):
-    def __init__(self, idd_field: IddField) -> None:
-        super().__init__(idd_field=idd_field)
-
     def setString(self, value: str):
         self._value = value.strip()
 
@@ -153,13 +174,13 @@ class DayTypeListField(AlphaField):
     def setString(self, value: str):
         v = value.strip()
         if v and not any(day in v.upper() for day in self.DAY_TYPES):
-            raise FieldValidationError(f"Field '{self.idd_field.name}' - No valid day type in: {v}")
+            raise FieldValidationError(self._format_error(f"No valid day type in: {v}"))
         self._value = v
 
 
 class NumericField(IdfField):
-    def __init__(self, idd_field: IddField) -> None:
-        super().__init__(idd_field=idd_field)
+    def __init__(self, idd_field: IddField, parent: "IdfObject | None" = None, group_index: int | None = None) -> None:
+        super().__init__(idd_field=idd_field, parent=parent, group_index=group_index)
         self._value: float | int | None = None
 
         self.autocalculatable: bool = False
@@ -204,8 +225,8 @@ class NumericField(IdfField):
         # on an autosizable-only field, but switch it to the keyword the field actually supports.
         if not self.autocalculatable:
             if not self.autosizable:
-                raise FieldValidationError("Autocalculate not allowed")
-            LOG.warning(f"Field '{self.idd_field.name}' is autosizable, not autocalculatable — switching to Autosize")
+                raise FieldValidationError(self._format_error("Autocalculate not allowed"))
+            LOG.warning(self._format_error("Field is autosizable, not autocalculatable — switching to Autosize"))
             self.autosize()
             return
         self._mode = NumericMode.AUTOCALCULATE
@@ -214,10 +235,8 @@ class NumericField(IdfField):
     def autosize(self):
         if not self.autosizable:
             if not self.autocalculatable:
-                raise FieldValidationError("Autosize not allowed")
-            LOG.warning(
-                f"Field '{self.idd_field.name}' is autocalculatable, not autosizable — switching to Autocalculate"
-            )
+                raise FieldValidationError(self._format_error("Autosize not allowed"))
+            LOG.warning(self._format_error("Field is autocalculatable, not autosizable — switching to Autocalculate"))
             self.autocalculate()
             return
         self._mode = NumericMode.AUTOSIZE
@@ -234,7 +253,7 @@ class NumericField(IdfField):
 
         if not v:
             if self.required:
-                raise FieldValidationError("Cannot set required numeric field to empty value")
+                raise FieldValidationError(self._format_error("Cannot set required numeric field to empty value"))
             self._value = None
             self._mode = NumericMode.NORMAL
             return
@@ -258,9 +277,8 @@ class NumericField(IdfField):
         if self._mode == NumericMode.NORMAL and self._value is not None:
             self._validate_range(self._value)
 
-    @classmethod
     @abstractmethod
-    def _parse_number(cls, value: str) -> int | float:
+    def _parse_number(self, value: str) -> int | float:
         """Parse a string into a number of the appropriate type.
 
         This should throw FieldValidationError if the string cannot be parsed.
@@ -271,29 +289,29 @@ class NumericField(IdfField):
         if self.minimum_value is not None:
             if self.min_bound_type == BoundTypes.InclusiveBound:
                 if value < self.minimum_value:
-                    raise FieldValidationError(f"{value} must be >= {self.minimum_value}")
+                    raise FieldValidationError(self._format_error(f"{value} must be >= {self.minimum_value}"))
             elif self.min_bound_type == BoundTypes.ExclusiveBound:
                 if value <= self.minimum_value:
-                    raise FieldValidationError(f"{value} must be > {self.minimum_value}")
+                    raise FieldValidationError(self._format_error(f"{value} must be > {self.minimum_value}"))
 
         if self.maximum_value is not None:
             if self.max_bound_type == BoundTypes.InclusiveBound:
                 if value > self.maximum_value:
-                    raise FieldValidationError(f"{value} must be <= {self.maximum_value}")
+                    raise FieldValidationError(self._format_error(f"{value} must be <= {self.maximum_value}"))
             elif self.max_bound_type == BoundTypes.ExclusiveBound:
                 if value >= self.maximum_value:
-                    raise FieldValidationError(f"{value} must be < {self.maximum_value}")
+                    raise FieldValidationError(self._format_error(f"{value} must be < {self.maximum_value}"))
 
     def reset(self):
         if self.required and self.value(return_default=True) is None:
-            raise FieldValidationError("Cannot reset a required field with no default value")
+            raise FieldValidationError(self._format_error("Cannot reset a required field with no default value"))
         self._value = None
         self._mode = NumericMode.NORMAL
 
 
 class IntegerField(NumericField):
-    def __init__(self, idd_field: IddField) -> None:
-        super().__init__(idd_field=idd_field)
+    def __init__(self, idd_field: IddField, parent: "IdfObject | None" = None, group_index: int | None = None) -> None:
+        super().__init__(idd_field=idd_field, parent=parent, group_index=group_index)
         self._value: int | None = None
         if self.minimum_value is not None:
             self.minimum_value = int(self.minimum_value)
@@ -304,23 +322,22 @@ class IntegerField(NumericField):
 
     def setInt(self, value: int) -> None:
         if not isinstance(value, (float, int)):
-            raise TypeError("IntegerField value must be an int")
+            raise TypeError(self._format_error("IntegerField value must be an int"))
         # Accept a float with no fractional part, eg 512.0, but don't truncate 512.5
         if isinstance(value, float) and not value.is_integer():  # also False for nan and inf
-            raise FieldValidationError(f"Invalid integer: {value}")
+            raise FieldValidationError(self._format_error(f"Invalid integer: {value}"))
         v = int(value)
         self._validate_range(value=v)
         self._value = v
         self._mode = NumericMode.NORMAL
 
-    @classmethod
-    def _parse_number(cls, value: str) -> int:
+    def _parse_number(self, value: str) -> int:
         """Parse an integer, also accepting a float with no fractional part, eg "512.0".
 
         Anything else is invalid. This is stricter than EnergyPlus, which rounds any number (2.1 -> 2).
         """
         if "_" in value:  # Python's int() and float() accept "1_000", IDF doesn't
-            raise FieldValidationError(f"Invalid integer: {value}")
+            raise FieldValidationError(self._format_error(f"Invalid integer: {value}"))
         try:
             return int(value)
         except ValueError:
@@ -328,15 +345,15 @@ class IntegerField(NumericField):
         try:
             as_float = float(value)
         except ValueError:
-            raise FieldValidationError(f"Invalid integer: {value}") from None
+            raise FieldValidationError(self._format_error(f"Invalid integer: {value}")) from None
         if not as_float.is_integer():  # also False for nan and inf
-            raise FieldValidationError(f"Invalid integer: {value}")
+            raise FieldValidationError(self._format_error(f"Invalid integer: {value}"))
         return int(as_float)
 
 
 class RealField(NumericField):
-    def __init__(self, idd_field: IddField) -> None:
-        super().__init__(idd_field=idd_field)
+    def __init__(self, idd_field: IddField, parent: "IdfObject | None" = None, group_index: int | None = None) -> None:
+        super().__init__(idd_field=idd_field, parent=parent, group_index=group_index)
         self._value: float | None = None
         self._written_as_integer = False  # set by setString, see idf_constants.IDF_KEEP_INTEGER_REALS
 
@@ -346,7 +363,7 @@ class RealField(NumericField):
 
     def setDouble(self, value: float) -> None:
         if not isinstance(value, (float, int)):
-            raise TypeError("RealField value must be a float")
+            raise TypeError(self._format_error("RealField value must be a float"))
         v = float(value)
         self._validate_range(value=v)
         self._value = v
@@ -363,17 +380,16 @@ class RealField(NumericField):
             return str(int(v))
         return super().value_text()
 
-    @classmethod
-    def _parse_number(cls, value: str) -> float:
+    def _parse_number(self, value: str) -> float:
         try:
             return float(value)
         except ValueError:
-            raise FieldValidationError(f"Invalid float: {value}")
+            raise FieldValidationError(self._format_error(f"Invalid float: {value}")) from None
 
 
 class ChoiceField(IdfField):
-    def __init__(self, idd_field: IddField) -> None:
-        super().__init__(idd_field=idd_field)
+    def __init__(self, idd_field: IddField, parent: "IdfObject | None" = None, group_index: int | None = None) -> None:
+        super().__init__(idd_field=idd_field, parent=parent, group_index=group_index)
 
         self.valid_choices: set[str] = {k.name for k in idd_field.keys}
         self._canonical_map: dict[str, str] = {k.lower(): k for k in self.valid_choices}
@@ -388,7 +404,7 @@ class ChoiceField(IdfField):
 
     def setBool(self, value: bool):
         if not self.is_boolean:
-            raise FieldValidationError("This choice field '{self.idd_field.name}' is not a boolean field")
+            raise FieldValidationError(self._format_error("This choice field is not a boolean field"))
         self._value = "Yes" if value else "No"
 
     def validate(self):
@@ -400,7 +416,7 @@ class ChoiceField(IdfField):
         v = self._canonical_map.get(value.lower(), None)
         if v is None:
             raise FieldValidationError(
-                f"Field '{self.idd_field.name}' - Invalid choice: {value}. Valid choices are: {self.valid_choices}"
+                self._format_error(f"Invalid choice: {value}. Valid choices are: {self.valid_choices}")
             )
         return v
 

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/energyplus_toolkit/input/idf/idf_object.py

@@ -1,7 +1,6 @@
 import itertools
 import logging
 import re
-from typing import NamedTuple
 
 from energyplus_toolkit.input.idd.idd_constants import COMMENT_ONLY_OBJECT_NAME
 from energyplus_toolkit.input.idd.idd_object import IddObject, IddObjectFormat
@@ -13,14 +12,6 @@ LOG = logging.getLogger("IdfObject")
 LOG.setLevel(logging.INFO)
 
 
-class FieldToWrite(NamedTuple):
-    """A field, with the name for its "!-" comment: numbered by group for an extensible field
-    ("Vertex 3 X-coordinate")."""
-
-    field: IdfField
-    name: str
-
-
 _VERTEX_FIELD_RE = re.compile(r"Vertex ([0-9]+) ([XYZ])-coordinate", re.IGNORECASE)
 
 
@@ -48,48 +39,46 @@ def _vertex_line(fields: tuple[IdfField, IdfField, IdfField], vertex: str, is_la
     return f"{indent}{values}  !- X,Y,Z ==> Vertex {vertex}" + (f" {{{units}}}" if units else "")
 
 
-def _vertices_format_lines(entries: list[FieldToWrite]) -> list[str]:
+def _vertices_format_lines(fields: list[IdfField]) -> list[str]:
     """\\format vertices: the X, Y and Z of a vertex on one line, the other fields one per line."""
-    last_field = entries[-1].field
+    last_field = fields[-1]
     lines = []
     # groupby only groups CONSECUTIVE entries with the same key (unlike pandas), so the order is kept: the regular
     # fields before, between and after the vertices each make their own group (key None), and each vertex its own
-    for vertex, group in itertools.groupby(entries, key=lambda entry: _vertex_number(entry.name)):
-        group_entries = list(group)
-        fields = tuple(entry.field for entry in group_entries)
+    for vertex, group in itertools.groupby(fields, key=lambda field: _vertex_number(field.name)):
+        group_fields = tuple(group)
         # A custom comment ends up on the last field of a line: only Z's can be kept on the vertex line
-        if vertex is not None and len(fields) == 3 and all(f.comment is None for f in fields[:2]):
-            lines.append(_vertex_line(fields, vertex, is_last_field=fields[-1] is last_field))
+        if vertex is not None and len(group_fields) == 3 and all(f.comment is None for f in group_fields[:2]):
+            lines.append(_vertex_line(group_fields, vertex, is_last_field=group_fields[-1] is last_field))
         else:
-            lines.extend(f.text(is_last_field=f is last_field, field_name=name) for f, name in group_entries)
+            lines.extend(f.text(is_last_field=f is last_field) for f in group_fields)
     return lines
 
 
-def _compact_schedule_format_lines(entries: list[FieldToWrite]) -> list[str]:
+def _compact_schedule_format_lines(fields: list[IdfField]) -> list[str]:
     """\\format compactSchedule: an "Until: HH:MM" field shares its line with the value after it, like EnergyPlus'
     Transition writes it: "Until: 24:00,1.0,  !- Field 3". The other fields are one per line."""
-    last_field = entries[-1].field
+    last_field = fields[-1]
     lines = []
-    entries_iter = iter(entries)
-    for entry in entries_iter:
-        field = entry.field
+    fields_iter = iter(fields)
+    for field in fields_iter:
         # A custom comment ends up on the last field of a line: the Until field's can't be kept if the value follows it.
         # next() only takes the value when the Until field can share its line
         if (
             field.value_text().strip().lower().startswith("until")
             and field.comment is None
-            and (value := next(entries_iter, None)) is not None
+            and (value := next(fields_iter, None)) is not None
         ):
             lines.append(
                 format_idf_field(
-                    value=f"{field.value_text()},{value.field.value_text()}",
-                    is_last_field=value.field is last_field,
-                    field_name=entry.name,
-                    comment=value.field.comment,
+                    value=f"{field.value_text()},{value.value_text()}",
+                    is_last_field=value is last_field,
+                    field_name=field.name,
+                    comment=value.comment,
                 )
             )
         else:
-            lines.append(field.text(is_last_field=field is last_field, field_name=entry.name))
+            lines.append(field.text(is_last_field=field is last_field))
     return lines
 
 
@@ -102,28 +91,27 @@ _VALUES_PER_LINE = {IddObjectFormat.FluidProperty: 7, IddObjectFormat.Spectral:
 _NUMBERED_FIELD_RE = re.compile(r"[0-9]+$")
 
 
-def _values_per_line_format_lines(entries: list[FieldToWrite], per_line: int) -> list[str]:
+def _values_per_line_format_lines(fields: list[IdfField], per_line: int) -> list[str]:
     """\\format FluidProperty and Spectral: the data fields ``per_line`` values per line, without comments
     ("0.300,0.000,0.045,0.045,"), the other fields (name, property type...) one per line."""
-    last_field = entries[-1].field
+    last_field = fields[-1]
     indent = " " * (idf_constants.IDF_LEADING + idf_constants.IDF_INDENT)
     lines: list[str] = []
     # groupby only groups CONSECUTIVE entries with the same key: the fields before the data, then the data
-    for is_data, group in itertools.groupby(entries, key=lambda entry: bool(_NUMBERED_FIELD_RE.search(entry.name))):
-        group_entries = list(group)
+    for is_data, group in itertools.groupby(fields, key=lambda field: bool(_NUMBERED_FIELD_RE.search(field.name))):
+        group_fields = list(group)
         if not is_data:
-            lines.extend(e.field.text(is_last_field=e.field is last_field, field_name=e.name) for e in group_entries)
+            lines.extend(f.text(is_last_field=f is last_field) for f in group_fields)
             continue
-        for start in range(0, len(group_entries), per_line):
-            chunk = group_entries[start : start + per_line]
-            fields = [entry.field for entry in chunk]
+        for start in range(0, len(group_fields), per_line):
+            chunk = group_fields[start : start + per_line]
             # A custom comment ends up on the last field of a line: only that one can be kept on a line of values
-            if any(f.comment is not None for f in fields[:-1]):
-                lines.extend(e.field.text(is_last_field=e.field is last_field, field_name=e.name) for e in chunk)
+            if any(f.comment is not None for f in chunk[:-1]):
+                lines.extend(f.text(is_last_field=f is last_field) for f in chunk)
                 continue
-            line = indent + ",".join(f.value_text() for f in fields) + (";" if fields[-1] is last_field else ",")
-            if fields[-1].comment is not None:
-                line += f"  ! {fields[-1].comment}"
+            line = indent + ",".join(f.value_text() for f in chunk) + (";" if chunk[-1] is last_field else ",")
+            if chunk[-1].comment is not None:
+                line += f"  ! {chunk[-1].comment}"
             lines.append(line)
     return lines
 
@@ -151,7 +139,7 @@ class IdfObject:
         self.idd_object: IddObject = idd_object
         self.comment: str = ""
         # Fixed (non-extensible) fields, one per idd_object.fields entry.
-        self._fields: list[IdfField] = [IdfField.from_idd_field(f) for f in idd_object.fields]
+        self._fields: list[IdfField] = [IdfField.from_idd_field(f, parent=self) for f in idd_object.fields]
         # Each inner list is one extensible group, sized to numExtensible.
         self._extensible_groups: list[list[IdfField]] = []
         # Number of fixed fields included in serialisation.  Starts at minFields,
@@ -166,7 +154,10 @@ class IdfObject:
     # ------------------------------------------------------------------
 
     def _new_extensible_group(self) -> list[IdfField]:
-        return [IdfField.from_idd_field(f) for f in self.idd_object.extensible_fields]
+        group_index = len(self._extensible_groups)
+        return [
+            IdfField.from_idd_field(f, parent=self, group_index=group_index) for f in self.idd_object.extensible_fields
+        ]
 
     # ------------------------------------------------------------------
     # Parsing
@@ -482,23 +473,17 @@ class IdfObject:
             lines.append(f"{indent}{self.idd_object.name},{','.join(vals)};")
         else:
             lines.append(f"{indent}{self.idd_object.name},")
-            # Extensible fields are numbered by group, like in the IDD: "Vertex 1 X-coordinate", "Vertex 2 X-coordinate"
-            entries = [FieldToWrite(field=f, name=f.idd_field.name) for f in active_fixed] + [
-                FieldToWrite(field=f, name=f.idd_field.name_for_group(i))
-                for i, group in enumerate(self._extensible_groups)
-                for f in group
-            ]
             if self.idd_object.properties.format == IddObjectFormat.Vertices:
-                lines.extend(_vertices_format_lines(entries))
+                lines.extend(_vertices_format_lines(all_fields))
             elif self.idd_object.properties.format == IddObjectFormat.CompactSchedule:
-                lines.extend(_compact_schedule_format_lines(entries))
+                lines.extend(_compact_schedule_format_lines(all_fields))
             elif self.idd_object.properties.format in _VALUES_PER_LINE:
                 lines.extend(
-                    _values_per_line_format_lines(entries, _VALUES_PER_LINE[self.idd_object.properties.format])
+                    _values_per_line_format_lines(all_fields, _VALUES_PER_LINE[self.idd_object.properties.format])
                 )
             else:
-                for i, (field, name) in enumerate(entries):
-                    lines.append(field.text(is_last_field=i == len(entries) - 1, field_name=name))
+                for i, field in enumerate(all_fields):
+                    lines.append(field.text(is_last_field=i == len(all_fields) - 1))
 
         lines.append("")  # blank line at end
         return "\n".join(lines)

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/energyplus_toolkit.egg-info/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: energyplus-toolkit
-Version: 0.2.0
+Version: 0.2.2
 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
+License-Expression: 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: Intended Audience :: Science/Research
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Provides-Extra: test
 Requires-Dist: pytest>=9.0.2; extra == "test"
 Requires-Dist: pytest-cov>=7.0.0; extra == "test"
@@ -29,6 +30,7 @@ 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"
+Dynamic: license-file
 
 # energyplus-toolkit
 
@@ -42,8 +44,8 @@ Tools for [EnergyPlus](https://energyplus.net) input files:
 - 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/>
+- GitHub: <https://github.com/jmarrec/energyplus-toolkit>
+- PyPI: <https://pypi.org/project/energyplus-toolkit/>
 
 ## Installation
 
@@ -86,18 +88,22 @@ parametric file, C++ code building the IDF...) is left unchanged, with a warning
 
 ```yaml
 - repo: https://github.com/jmarrec/energyplus-toolkit
-  rev: v0.2.0
+  rev: v0.2.2
   hooks:
   - id: energyplus-format-idd
-    args: [--idd, idd/Energy+.idd.in]
+    args: [-q]
+    # Example to limit to a specific file
+    files: ^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.
+The IDF and unit test hooks need the IDD to use (`--idd`); the IDD hook doesn't take it.
+`files` is optional: it limits a hook to the paths matching this regex, here the one IDD to format.
+
+**Note:** For unit tests, put the hook before clang-format: reformatting then clang-format is stable.
 
 ## Library
 
@@ -113,7 +119,7 @@ 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)
+idf = IdfFile.load(Path("in.idf"), idd_file=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)
@@ -125,20 +131,25 @@ print(zone)
 # Zone,
 #   Z3,                      !- Name
 #   45.0;                    !- Direction of Relative North {deg}
+idf.add_object(obj=zone)
 
 # 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"])
 
+idf.remove_object(zone)
+idf.add_objects(objs=[zone, branch])
+assert idf.objects[-2:] == [zone, branch]
+
 # 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...).
+Values are validated against the IDD when set: types, choices (the casing is normalized), bounds.
+The IDF is written with its comments (`!- Field Name {units}`) and the layout the IDD asks for (`\format`: vertices, compact schedules...).
 
 ## Layout
 

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/energyplus_toolkit.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 README.md
 pyproject.toml
 energyplus_toolkit/__init__.py

{energyplus_toolkit-0.2.0 → energyplus_toolkit-0.2.2}/pyproject.toml

@@ -4,18 +4,19 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "energyplus-toolkit"
-version = "0.2.0"
+version = "0.2.2"
 description = "Tools for EnergyPlus input files: parse, write back and reformat IDD and IDF files, and the IDF in EnergyPlus C++ unit tests."
+readme = "README.md"
 authors = [
     {name = "Julien Marrec", email = "contact@effibem.com"},
 ]
-readme = "README.md"
-license = {text = "MIT"}
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.11"
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
     "Natural Language :: English",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",