idfpy 25.1.0__py3-none-any.whl

idfpy/__init__.py

@@ -0,0 +1,23 @@
+"""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 26.1.
+"""
+
+from importlib.metadata import version
+
+from idfpy.idf import IDF
+from idfpy.models._base import IDFBaseModel
+from idfpy.models._errors import RefError, RefValidationError, UnknownObjectTypeError
+
+__version__ = version('idfpy')
+__all__ = [
+    'IDF',
+    'IDFBaseModel',
+    'RefError',
+    'RefValidationError',
+    'UnknownObjectTypeError',
+    '__version__',
+]

idfpy/__main__.py

@@ -0,0 +1,3 @@
+from idfpy.cli import app
+
+app()

idfpy/cli.py

@@ -0,0 +1,49 @@
+"""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('idfpy/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,
+    readvars: Annotated[
+        bool, Option('--readvars', '-r', help='Run ReadVarsESO to convert ESO to CSV')
+    ] = False,
+) -> None:
+    """Run EnergyPlus simulation."""
+    from idfpy.sim import simulate
+
+    result = simulate(idf, weather=weather, output_dir=output, readvars=readvars)
+    raise SystemExit(result.return_code)

idfpy/codegen/__init__.py

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

idfpy/codegen/field_parser.py

@@ -0,0 +1,264 @@
+"""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
+    reference: list[str] | None = None
+    reference_class_name: 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
+    is_name: bool = False
+
+
+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'),
+            reference=field_schema.get('reference'),
+            reference_class_name=field_schema.get('reference-class-name'),
+            note=field_schema.get('note'),
+            data_type=field_schema.get('data_type'),
+        )
+
+        # Normalize: string field with numeric default → convert to str
+        # (e.g., Version.version_identifier has type="string" but default=25.1)
+        if spec.field_type == 'string' and type(spec.default) in (int, float):
+            spec.default = str(spec.default)
+
+        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)
+
+        default = field_schema.get('default', _UNSET)
+        # Normalize: string field with numeric default → convert to str
+        if primary_type == 'string' and type(default) in (int, float):
+            default = str(default)
+
+        return FieldSpec(
+            name=name,
+            python_name=python_name,
+            field_type=primary_type,
+            default=default,
+            units=field_schema.get('units'),
+            reference=field_schema.get('reference'),
+            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