idfpy 25.2.0__tar.gz

idfpy-25.2.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "!latest" # Exclude latest tag
+
+permissions:
+  id-token: write # Required for trusted publishing
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

idfpy-25.2.0/.github/workflows/update-models.yml

@@ -0,0 +1,123 @@
+name: Update EnergyPlus Models
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Weekly Monday 6AM UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update-models:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need full history for tags
+
+      - name: Get latest EnergyPlus release
+        id: ep
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          RELEASE_JSON=$(gh api repos/NREL/EnergyPlus/releases/latest)
+          TAG=$(echo "$RELEASE_JSON" | jq -r '.tag_name')
+          VERSION=${TAG#v}
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+          # Pick Ubuntu 24.04 x86_64 tar.gz
+          ASSET_URL=$(echo "$RELEASE_JSON" | jq -r '
+            .assets[]
+            | select(.name | test("Linux-Ubuntu24\\.04-x86_64\\.tar\\.gz$"))
+            | .browser_download_url
+          ')
+          if [ -z "$ASSET_URL" ]; then
+            # Fallback: any Linux x86_64 tar.gz
+            ASSET_URL=$(echo "$RELEASE_JSON" | jq -r '
+              .assets[]
+              | select(.name | test("Linux.*x86_64\\.tar\\.gz$"))
+              | .browser_download_url
+            ' | head -1)
+          fi
+          echo "asset_url=$ASSET_URL" >> "$GITHUB_OUTPUT"
+          echo "EnergyPlus $VERSION -> $ASSET_URL"
+
+      - name: Check if update needed
+        id: check
+        run: |
+          EP="${{ steps.ep.outputs.version }}"
+          TAG="v${EP}"
+          if git tag -l "$TAG" | grep -q "$TAG"; then
+            echo "Tag $TAG already exists, skipping"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Tag $TAG not found, will update"
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Download and extract schema
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          curl -L -o ep.tar.gz "${{ steps.ep.outputs.asset_url }}"
+          tar -xzf ep.tar.gz --wildcards '*/Energy+.schema.epJSON' --strip-components=1
+          rm ep.tar.gz
+          ls -lh 'Energy+.schema.epJSON'
+
+      - uses: astral-sh/setup-uv@v4
+        if: steps.check.outputs.skip == 'false'
+
+      - name: Generate models
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          uv sync --all-groups
+          uv run idfpy codegen --schema 'Energy+.schema.epJSON' --output idfpy/models
+          uv run ruff check --fix .
+          uv run ruff format .
+          uv run ty check .
+          rm 'Energy+.schema.epJSON'
+
+      - name: Run tests
+        if: steps.check.outputs.skip == 'false'
+        run: uv run pytest tests/ -v
+
+      - name: Update version and README
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          EP_VERSION="${{ steps.ep.outputs.version }}"
+
+          # Update pyproject.toml version
+          sed -i "s/^version = .*/version = \"${EP_VERSION}\"/" pyproject.toml
+
+          # Count object types and ref types from generated code
+          OBJ_COUNT=$(grep -r '_idf_object_type: ClassVar' idfpy/models/*.py | grep -cv '_base.py')
+          REF_COUNT=$(grep -c 'Ref = Annotated' idfpy/models/_refs.py)
+
+          # Update README
+          sed -i "s/version \*\*[0-9.]*\*\*/version **${EP_VERSION}**/" README.md
+          sed -i "s/\*\*[0-9]* object types\*\*/\*\*${OBJ_COUNT} object types\*\*/" README.md
+          sed -i "s/\*\*[0-9]* reference types\*\*/\*\*${REF_COUNT} reference types\*\*/" README.md
+
+      - name: Commit, tag and push
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          EP_VERSION="${{ steps.ep.outputs.version }}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add -A
+          if git diff --cached --quiet; then
+            echo "No changes detected"
+            exit 0
+          fi
+
+          git commit -m "feat(models): update to EnergyPlus ${EP_VERSION}"
+
+          TAG="v${EP_VERSION}"
+          git tag -a "$TAG" -m "EnergyPlus ${EP_VERSION} models"
+          git tag -f latest -m "Latest EnergyPlus models (${EP_VERSION})"
+
+          git push origin HEAD
+          git push origin "$TAG"
+          git push origin latest --force

idfpy-25.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.lock
+
+.claude/

idfpy-25.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ITOTI-Y
+
+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.

idfpy-25.2.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: idfpy
+Version: 25.2.0
+Summary: Type-safe Pydantic models for all EnergyPlus IDF objects
+Project-URL: Repository, https://github.com/ITOTI-Y/idfpy
+Project-URL: Issues, https://github.com/ITOTI-Y/idfpy/issues
+Author: ITOTI-Y
+License-Expression: MIT
+License-File: LICENSE
+Keywords: building-simulation,energyplus,idf,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.21.1
+Description-Content-Type: text/markdown
+
+# idfpy
+
+Type-safe [Pydantic](https://docs.pydantic.dev/) models for **all** [EnergyPlus](https://energyplus.net/) IDF object types, plus IDF file read/write and simulation execution.
+
+Auto-generated from `Energy+.schema.epJSON` version **25.2.0**.
+
+## Features
+
+- **858 object types** as Pydantic v2 models with full validation
+- **275 reference types** with cross-object validation
+- **Case-insensitive** Literal field matching (EnergyPlus IDF is case-insensitive)
+- **Extensible field** support (vertices, schedule data, etc.)
+- **IDF read/write** with positional field ordering
+- **EnergyPlus simulation** execution with ExpandObjects support
+- Accepts both `snake_case` and original EnergyPlus schema key names
+
+## Installation
+
+```bash
+pip install idfpy
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from idfpy import IDF
+from idfpy.models.simulation import Version, Building
+from idfpy.models.thermal_zones import Zone
+
+# Create an IDF
+idf = IDF()
+idf.add(Version())
+idf.add(Building(name='MyBuilding', north_axis=0.0))
+idf.add(Zone(name='Zone1'))
+
+# Save
+idf.save(Path('output.idf'))
+
+# Load existing IDF
+idf = IDF.load(Path('existing.idf'))
+print(f'{len(idf)} objects loaded')
+
+# Run simulation
+idf.run(
+    idf_path=Path('model.idf'),
+    weather_path=Path('weather.epw'),
+    output_dir=Path('results/'),
+)
+```
+
+## License
+
+MIT

idfpy-25.2.0/README.md

@@ -0,0 +1,54 @@
+# idfpy
+
+Type-safe [Pydantic](https://docs.pydantic.dev/) models for **all** [EnergyPlus](https://energyplus.net/) IDF object types, plus IDF file read/write and simulation execution.
+
+Auto-generated from `Energy+.schema.epJSON` version **25.2.0**.
+
+## Features
+
+- **858 object types** as Pydantic v2 models with full validation
+- **275 reference types** with cross-object validation
+- **Case-insensitive** Literal field matching (EnergyPlus IDF is case-insensitive)
+- **Extensible field** support (vertices, schedule data, etc.)
+- **IDF read/write** with positional field ordering
+- **EnergyPlus simulation** execution with ExpandObjects support
+- Accepts both `snake_case` and original EnergyPlus schema key names
+
+## Installation
+
+```bash
+pip install idfpy
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from idfpy import IDF
+from idfpy.models.simulation import Version, Building
+from idfpy.models.thermal_zones import Zone
+
+# Create an IDF
+idf = IDF()
+idf.add(Version())
+idf.add(Building(name='MyBuilding', north_axis=0.0))
+idf.add(Zone(name='Zone1'))
+
+# Save
+idf.save(Path('output.idf'))
+
+# Load existing IDF
+idf = IDF.load(Path('existing.idf'))
+print(f'{len(idf)} objects loaded')
+
+# Run simulation
+idf.run(
+    idf_path=Path('model.idf'),
+    weather_path=Path('weather.epw'),
+    output_dir=Path('results/'),
+)
+```
+
+## License
+
+MIT

idfpy-25.2.0/idfpy/__init__.py

@@ -0,0 +1,15 @@
+"""idfpy - EnergyPlus IDF models and file handling.
+
+Type-safe Pydantic models for all EnergyPlus IDF object types,
+plus IDF file read/write functionality.
+
+Generated from Energy+.schema.epJSON version 25.1.
+"""
+
+from importlib.metadata import version
+
+from idfpy.idf import IDF
+from idfpy.models._base import IDFBaseModel
+
+__version__ = version('idfpy')
+__all__ = ['IDF', 'IDFBaseModel', '__version__']

idfpy-25.2.0/idfpy/cli.py

@@ -0,0 +1,47 @@
+"""idfpy command-line interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+from typer import Option, Typer
+
+app = Typer(name='idfpy', help='EnergyPlus IDF toolkit')
+
+
+@app.command()
+def codegen(
+    schema: Annotated[
+        Path, Option('--schema', '-s', help='Path to Energy+.schema.epJSON')
+    ],
+    output: Annotated[
+        Path, Option('--output', '-o', help='Output directory for generated models')
+    ] = Path('generated_models'),
+) -> None:
+    """Generate Pydantic models from EnergyPlus schema."""
+    from idfpy.codegen import ModelGenerator, SchemaParser
+
+    parser = SchemaParser(schema_path=schema)
+    specs = parser.parse()
+    schema_version = parser.get_version()
+    generator = ModelGenerator(output_dir=output)
+    generator.generate_all(specs, schema_version=schema_version)
+
+
+@app.command()
+def run(
+    idf: Annotated[Path, Option('--idf', '-i', help='Path to IDF file')],
+    weather: Annotated[
+        Path, Option('--weather', '-w', help='Path to EPW weather file')
+    ],
+    output: Annotated[
+        Path | None, Option('--output', '-o', help='Output directory')
+    ] = None,
+) -> None:
+    """Run EnergyPlus simulation."""
+    from idfpy.idf import IDF
+
+    idf_runner = IDF()
+    rc = idf_runner.run(idf_path=idf, weather_path=weather, output_dir=output)
+    raise SystemExit(rc)

idfpy-25.2.0/idfpy/codegen/__init__.py

@@ -0,0 +1,4 @@
+from .model_generator import ModelGenerator
+from .schema_parser import SchemaParser
+
+__all__ = ['ModelGenerator', 'SchemaParser']

idfpy-25.2.0/idfpy/codegen/field_parser.py

@@ -0,0 +1,248 @@
+"""EnergyPlus JSON Schema parser for code generation.
+
+This module parses Energy+.schema.epJSON to extract field and object
+specifications for generating type-safe Pydantic models.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+_UNSET = object()
+
+
+@dataclass
+class FieldSpec:
+    """EnergyPlus field specification.
+
+    Represents a single field definition extracted from the schema,
+    including type information, constraints, and metadata.
+
+    Attributes:
+        name: Original field name from schema (e.g., "direction_of_relative_north").
+        python_name: Python-compatible name in snake_case.
+        field_type: JSON schema type ("number", "string", "integer", "array").
+        default: Default value if specified.
+        required: Whether the field is required.
+        enum_values: List of allowed values for enum fields.
+        units: Physical units (e.g., "m", "deg", "W").
+        minimum: Minimum allowed value (inclusive).
+        maximum: Maximum allowed value (inclusive).
+        exclusive_minimum: Exclusive minimum value.
+        exclusive_maximum: Exclusive maximum value.
+        object_list: Reference to other object types (for object_list fields).
+        items_spec: Nested FieldSpec for array item types.
+        note: Field description/note from schema.
+        data_type: Additional data type hint (e.g., "object_list").
+        anyof_specs: List of alternative type specs for anyOf fields.
+        nested_fields: List of nested field specs for object fields.
+    """
+
+    name: str
+    python_name: str
+    field_type: str
+    default: Any = _UNSET
+    required: bool = False
+    enum_values: list[str] | None = None
+    units: str | None = None
+    minimum: float | None = None
+    maximum: float | None = None
+    exclusive_minimum: float | None = None
+    exclusive_maximum: float | None = None
+    object_list: list[str] | None = None
+    items_spec: FieldSpec | None = None
+    item_class_name: str | None = None
+    note: str | None = None
+    data_type: str | None = None
+    anyof_specs: list[FieldSpec] | None = None
+    nested_fields: list[FieldSpec] | None = None
+
+
+class FieldParser:
+    """Parser for EnergyPlus schema field definitions.
+
+    Extracts FieldSpec instances from JSON schema field definitions,
+    handling various field types including nested objects and arrays.
+    """
+
+    _CAMEL_TO_SNAKE_PATTERN = re.compile(r'(?<!^)(?=[A-Z])')
+
+    def parse_field(self, name: str, field_schema: dict[str, Any]) -> FieldSpec:
+        """Parse a single field definition from schema.
+
+        Args:
+            name: Original field name.
+            field_schema: Field definition dictionary from schema.
+
+        Returns:
+            Parsed FieldSpec instance.
+        """
+        python_name = self._to_python_name(name)
+
+        if 'anyOf' in field_schema:
+            return self._parse_anyof_field(name, python_name, field_schema)
+
+        field_type = field_schema.get('type', 'string')
+
+        spec = FieldSpec(
+            name=name,
+            python_name=python_name,
+            field_type=field_type,
+            default=field_schema.get('default', _UNSET),
+            enum_values=field_schema.get('enum'),
+            units=field_schema.get('units'),
+            minimum=field_schema.get('minimum'),
+            maximum=field_schema.get('maximum'),
+            exclusive_minimum=field_schema.get('exclusiveMinimum'),
+            exclusive_maximum=field_schema.get('exclusiveMaximum'),
+            object_list=field_schema.get('object_list'),
+            note=field_schema.get('note'),
+            data_type=field_schema.get('data_type'),
+        )
+
+        if field_type == 'array' and 'items' in field_schema:
+            spec.items_spec = self._parse_array_items(field_schema['items'])
+
+        return spec
+
+    def _parse_anyof_field(
+        self, name: str, python_name: str, field_schema: dict[str, Any]
+    ) -> FieldSpec:
+        """Parse a field with anyOf type alternatives.
+
+        Args:
+            name: Original field name.
+            python_name: Python-compatible field name.
+            field_schema: Field definition with anyOf.
+
+        Returns:
+            FieldSpec with anyof_specs populated.
+        """
+        anyof_specs = []
+        primary_type = 'string'  # Default fallback
+
+        for alt_schema in field_schema.get('anyOf', []):
+            alt_type = alt_schema.get('type', 'string')
+
+            if alt_type != 'null' and primary_type == 'string':
+                primary_type = alt_type
+
+            alt_spec = FieldSpec(
+                name=name,
+                python_name=python_name,
+                field_type=alt_type,
+                enum_values=alt_schema.get('enum'),
+                minimum=alt_schema.get('minimum'),
+                maximum=alt_schema.get('maximum'),
+            )
+            anyof_specs.append(alt_spec)
+
+        return FieldSpec(
+            name=name,
+            python_name=python_name,
+            field_type=primary_type,
+            default=field_schema.get('default', _UNSET),
+            units=field_schema.get('units'),
+            note=field_schema.get('note'),
+            anyof_specs=anyof_specs,
+        )
+
+    def _parse_array_items(self, items_schema: dict[str, Any]) -> FieldSpec:
+        """Parse array items specification.
+
+        Handles nested object definitions within array items,
+        such as vertices with x/y/z coordinates.
+
+        Args:
+            items_schema: Array items definition from schema.
+
+        Returns:
+            FieldSpec representing the array item type.
+        """
+        item_type = items_schema.get('type', 'object')
+
+        if item_type == 'object' and 'properties' in items_schema:
+            nested_fields = []
+            required_set = set(items_schema.get('required', []))
+            for prop_name, prop_schema in items_schema['properties'].items():
+                nested_spec = self.parse_field(prop_name, prop_schema)
+                nested_spec.required = prop_name in required_set
+                nested_fields.append(nested_spec)
+
+            return FieldSpec(
+                name='_item',
+                python_name='_item',
+                field_type='object',
+                nested_fields=nested_fields,
+            )
+
+        return FieldSpec(
+            name='_item',
+            python_name='_item',
+            field_type=item_type,
+            enum_values=items_schema.get('enum'),
+            minimum=items_schema.get('minimum'),
+            maximum=items_schema.get('maximum'),
+        )
+
+    def _to_python_name(self, name: str) -> str:
+        """Convert field name to Python snake_case.
+
+        Args:
+            name: Original field name (may contain spaces, hyphens, etc.).
+
+        Returns:
+            Python-compatible snake_case name.
+
+        Examples:
+            >>> parser = FieldParser()
+            >>> parser._to_python_name('direction_of_relative_north')
+            'direction_of_relative_north'
+            >>> parser._to_python_name('X Origin')
+            'x_origin'
+            >>> parser._to_python_name('vertex-x-coordinate')
+            'vertex_x_coordinate'
+            >>> parser._to_python_name('100% Outdoor Air in Cooling')
+            'n100_outdoor_air_in_cooling'
+        """
+        result = name.replace(' ', '_').replace('-', '_')
+
+        result = self._CAMEL_TO_SNAKE_PATTERN.sub('_', result)
+
+        result = result.lower()
+
+        result = re.sub(r'_+', '_', result)
+
+        result = result.strip('_')
+
+        # Python identifiers cannot start with a digit - prefix with 'n'
+        if result and result[0].isdigit():
+            result = 'n' + result
+
+        return result
+
+    def parse_fields_from_properties(
+        self,
+        properties: dict[str, Any],
+        required_fields: list[str] | None = None,
+    ) -> list[FieldSpec]:
+        """Parse all fields from a properties dictionary.
+
+        Args:
+            properties: Dictionary of field name to field schema.
+            required_fields: List of required field names.
+
+        Returns:
+            List of parsed FieldSpec instances.
+        """
+        required_set = set(required_fields or [])
+        fields = []
+
+        for name, schema in properties.items():
+            spec = self.parse_field(name, schema)
+            spec.required = name in required_set
+            fields.append(spec)
+
+        return fields