I/O -- Parsers & Writers

Functions and classes for reading and writing EnergyPlus models in IDF (text) and epJSON (JSON) formats.

Convenience Loaders

Top-level convenience functions:

• load_idf(path, version=None, *, strict_parsing=True, strict=False, preserve_formatting=False) for IDF files. Strict parsing is on by default.
• load_epjson(path, version=None, *, strict=False, preserve_formatting=False) for epJSON files.

Load an IDF file and return an IDFDocument.

Parameters:

Name	Type	Description	Default
path	str	Path to the IDF file	required
version	tuple[int, int, int] | None	Optional version override (major, minor, patch)	None
strict_parsing	bool	If True, fail fast on malformed IDF objects (default: True)	True
strict	bool	When True, accessing or setting an unknown field name on any IDFObject raises :class:~idfkit.exceptions.InvalidFieldError instead of returning None.	True
preserve_formatting	bool	When True, build a Concrete Syntax Tree (CST) so that :func:write_idf reproduces the original formatting, comments, and whitespace for unmodified objects.	False

Returns:

Type	Description
IDFDocument[bool]	Parsed IDFDocument

Examples:

Load a DOE reference building and list its zones:

```python
model = load_idf("RefBldgSmallOfficeNew2004.idf")
print(f"Loaded {len(model)} objects")
for zone in model["Zone"]:
    print(zone.name)
```

Override the version for a legacy model:

```python
model = load_idf("pre_v9_building.idf", version=(9, 6, 0))
```

Lossless round-trip:

```python
model = load_idf("building.idf", preserve_formatting=True)
write_idf(model, "building_copy.idf")  # byte-identical
```

Source code in src/idfkit/__init__.py

def load_idf(  # type: ignore[misc]  # overload implementation
    path: str,
    version: tuple[int, int, int] | None = None,
    *,
    strict_parsing: bool = True,
    strict: bool = True,
    preserve_formatting: bool = False,
) -> IDFDocument[bool]:
    """
    Load an IDF file and return an IDFDocument.

    Args:
        path: Path to the IDF file
        version: Optional version override (major, minor, patch)
        strict_parsing: If True, fail fast on malformed IDF objects (default: True)
        strict: When ``True``, accessing or setting an unknown field name on any
            IDFObject raises :class:`~idfkit.exceptions.InvalidFieldError` instead
            of returning ``None``.
        preserve_formatting: When ``True``, build a Concrete Syntax Tree
            (CST) so that :func:`write_idf` reproduces the original
            formatting, comments, and whitespace for unmodified objects.

    Returns:
        Parsed IDFDocument

    Examples:
        Load a DOE reference building and list its zones:

            ```python
            model = load_idf("RefBldgSmallOfficeNew2004.idf")
            print(f"Loaded {len(model)} objects")
            for zone in model["Zone"]:
                print(zone.name)
            ```

        Override the version for a legacy model:

            ```python
            model = load_idf("pre_v9_building.idf", version=(9, 6, 0))
            ```

        Lossless round-trip:

            ```python
            model = load_idf("building.idf", preserve_formatting=True)
            write_idf(model, "building_copy.idf")  # byte-identical
            ```
    """
    from pathlib import Path

    if version is not None:
        _check_version(version)
    return parse_idf(
        Path(path),
        version=version,
        strict_parsing=strict_parsing,
        strict=strict,
        preserve_formatting=preserve_formatting,
    )

Load an epJSON file and return an IDFDocument.

Parameters:

Name	Type	Description	Default
path	str	Path to the epJSON file	required
version	tuple[int, int, int] | None	Optional version override (major, minor, patch)	None
strict	bool	When True, accessing or setting an unknown field name on any IDFObject raises :class:~idfkit.exceptions.InvalidFieldError instead of returning None.	True
preserve_formatting	bool	When True, store the raw JSON text so that :func:write_epjson can reproduce it byte-for-byte when no objects have been modified.	False

Returns:

Type	Description
IDFDocument[bool]	Parsed IDFDocument

Examples:

Load an epJSON model and iterate over zones:

```python
model = load_epjson("SmallOffice.epJSON")
for zone in model["Zone"]:
    print(zone.name, zone.x_origin)
```

Specify an explicit EnergyPlus version:

```python
model = load_epjson("SmallOffice.epJSON", version=(24, 1, 0))
```

Source code in src/idfkit/__init__.py

def load_epjson(  # type: ignore[misc]  # overload implementation
    path: str,
    version: tuple[int, int, int] | None = None,
    *,
    strict: bool = True,
    preserve_formatting: bool = False,
) -> IDFDocument[bool]:
    """
    Load an epJSON file and return an IDFDocument.

    Args:
        path: Path to the epJSON file
        version: Optional version override (major, minor, patch)
        strict: When ``True``, accessing or setting an unknown field name on any
            IDFObject raises :class:`~idfkit.exceptions.InvalidFieldError` instead
            of returning ``None``.
        preserve_formatting: When ``True``, store the raw JSON text so
            that :func:`write_epjson` can reproduce it byte-for-byte
            when no objects have been modified.

    Returns:
        Parsed IDFDocument

    Examples:
        Load an epJSON model and iterate over zones:

            ```python
            model = load_epjson("SmallOffice.epJSON")
            for zone in model["Zone"]:
                print(zone.name, zone.x_origin)
            ```

        Specify an explicit EnergyPlus version:

            ```python
            model = load_epjson("SmallOffice.epJSON", version=(24, 1, 0))
            ```
    """
    from pathlib import Path

    if version is not None:
        _check_version(version)
    return parse_epjson(Path(path), version=version, strict=strict, preserve_formatting=preserve_formatting)

IDF Parser

Streaming IDF parser - parses EnergyPlus IDF files into IDFDocument.

Features: - Memory-efficient streaming for large files - Regex-based tokenization - Direct parsing into IDFDocument (no intermediate structures) - Type coercion based on schema - Optional CST (Concrete Syntax Tree) for lossless round-tripping

IDFParser

Streaming parser for IDF files.

Uses memory mapping for large files and regex for tokenization.

Source code in src/idfkit/idf_parser.py

class IDFParser:
    """
    Streaming parser for IDF files.

    Uses memory mapping for large files and regex for tokenization.
    """

    __slots__ = ("_content", "_encoding", "_filepath", "_schema", "_strict_parsing")

    _filepath: Path
    _schema: EpJSONSchema | None
    _encoding: str
    _content: bytes | None
    _strict_parsing: bool

    def __init__(
        self,
        filepath: Path,
        schema: EpJSONSchema | None = None,
        encoding: str = "latin-1",
        strict_parsing: bool = True,
    ):
        self._filepath = filepath
        self._schema = schema
        self._encoding = encoding
        self._strict_parsing = strict_parsing
        self._content: bytes | None = None

    def parse(
        self,
        version: tuple[int, int, int] | None = None,
        *,
        strict: bool = True,
        preserve_formatting: bool = False,
    ) -> IDFDocument:
        """
        Parse the IDF file into an IDFDocument.

        Args:
            version: Optional version override
            strict: Enforce strict field access on the resulting document.
            preserve_formatting: Build a CST for lossless round-tripping.

        Returns:
            Parsed IDFDocument
        """
        t0 = time.perf_counter()
        logger.debug("Parsing IDF file %s", self._filepath)

        # Load content (with mmap for large files)
        content = self._load_content()

        # Detect version if not provided
        if version is None:
            version = self._detect_version(content)
            logger.debug("Detected version %d.%d.%d", *version)

        # Load schema if not provided
        schema = self._schema
        if schema is None:
            from .schema import get_schema

            schema = get_schema(version)

        # Create document
        doc = IDFDocument(version=version, schema=schema, filepath=self._filepath, strict=strict)  # type: ignore[reportCallIssue]  # .pyi uses covariant Strict

        # Parse objects
        self._parse_objects(content, doc, schema)

        # Build CST for lossless round-tripping (opt-in, no cost when False)
        if preserve_formatting:
            original_text = content.decode(self._encoding)
            cst = _build_idf_cst(original_text)
            if _link_cst_to_objects(cst, doc):
                doc._cst = cst  # pyright: ignore[reportAttributeAccessIssue]
                doc._raw_text = original_text  # pyright: ignore[reportAttributeAccessIssue]
            else:
                logger.warning("CST discarded due to linking failure — lossless round-trip disabled")

        elapsed = time.perf_counter() - t0
        logger.info("Parsed %d objects from %s in %.3fs", len(doc), self._filepath, elapsed)

        return doc

    def _load_content(self) -> bytes:
        """Load file content, using mmap for large files."""
        file_size = self._filepath.stat().st_size
        use_mmap = file_size > _MMAP_THRESHOLD

        if use_mmap:
            logger.debug("Using mmap for large file (%d bytes)", file_size)
            # Use memory mapping for large files
            with open(self._filepath, "rb") as f:
                mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
                content = bytes(mm)
                mm.close()
        else:
            with open(self._filepath, "rb") as f:
                content = f.read()

        return content

    def _detect_version(self, content: bytes) -> tuple[int, int, int]:
        """Detect EnergyPlus version from file content."""
        # Only search first 10KB for version
        header = content[:10240]

        match = _VERSION_PATTERN.search(header)
        if match:
            major = int(match.group(1))
            minor = int(match.group(2))
            patch = int(match.group(3)) if match.group(3) else 0
            return (major, minor, patch)

        raise VersionNotFoundError(str(self._filepath))

    def _parse_objects(
        self,
        content: bytes,
        doc: IDFDocument,
        schema: EpJSONSchema | None,
    ) -> None:
        """Parse all objects from content into document."""
        # Strip comments before matching to prevent phantom objects
        # (e.g. "!- X,Y,Z Origin" matching "X," as an object type)
        content = _COMMENT_PATTERN.sub(b"", content)

        # Local per-type caches avoid repeated schema lookups
        type_cache: dict[str, ParsingCache | None] = {}
        canonical_cache: dict[str, str] = {}
        encoding = self._encoding
        addidfobject = doc.addidfobject
        skipped_types: set[str] = set()

        for match in _OBJECT_PATTERN.finditer(content):
            match_offset = match.start(1)
            obj_type: str | None = None
            obj_name: str | None = None

            try:
                decoded_obj_type = match.group(1).decode(encoding).strip()
                obj_type = decoded_obj_type

                obj_name = self._extract_object_name(match, encoding)

                pc, should_skip, decoded_obj_type = self._resolve_type_cache(
                    content=content,
                    schema=schema,
                    type_cache=type_cache,
                    canonical_cache=canonical_cache,
                    skipped_types=skipped_types,
                    obj_type=decoded_obj_type,
                    obj_name=obj_name,
                    match_offset=match_offset,
                )
                if should_skip:
                    continue

                obj = self._parse_object_cached(match, pc, encoding, obj_type_override=decoded_obj_type)
                if obj:
                    addidfobject(obj)
            except IDFParseError:
                raise
            except Exception as exc:
                if self._strict_parsing:
                    self._raise_parse_error(
                        content,
                        match_offset,
                        f"Failed to parse object: {exc}",
                        obj_type=obj_type,
                        obj_name=obj_name,
                    )
                logger.warning("Skipping malformed object %r: %s", obj_type or "<decode_error>", exc)

        if skipped_types:
            logger.warning(
                "Skipped %d unknown object type(s): %s", len(skipped_types), ", ".join(sorted(skipped_types))
            )

    def _parse_object_cached(
        self,
        match: re.Match[bytes],
        pc: ParsingCache | None,
        encoding: str,
        *,
        obj_type_override: str | None = None,
    ) -> IDFObject | None:
        """Parse a single object from regex match using cached metadata."""
        obj_type = obj_type_override or match.group(1).decode(encoding).strip()
        fields_raw = match.group(2).decode(encoding)

        fields = self._parse_fields(fields_raw)
        if not fields:
            return None

        if pc is not None:
            has_name = pc.has_name
            # Mutable copy since extensible parsing appends to it
            field_names: list[str] = list(pc.field_names) if has_name else list(pc.all_field_names)

            name, remaining_fields = (fields[0], fields[1:]) if has_name else ("", fields)

            data = self._build_data_dict_cached(remaining_fields, field_names, pc)

            return IDFObject(
                obj_type=obj_type,
                name=name,
                data=data,
                schema=pc.obj_schema,
                field_order=field_names,
                ref_fields=pc.ref_fields,
                extensibles=frozenset(pc.ext_field_names),
            )

        # No-schema fallback
        name = fields[0] if fields else ""
        remaining = fields[1:]
        data: dict[str, Any] = {}
        for i, value in enumerate(remaining):
            if value:
                data[f"field_{i + 1}"] = value
        return IDFObject(obj_type=obj_type, name=name, data=data)

    def _build_data_dict_cached(
        self,
        remaining_fields: list[str],
        field_names: list[str],
        pc: ParsingCache,
    ) -> dict[str, Any]:
        """Build the data dict using pre-computed field types from the cache."""
        data: dict[str, Any] = {}
        field_types = pc.field_types
        num_named = len(field_names)

        for i, value in enumerate(remaining_fields):
            if i < num_named:
                field_name = field_names[i]
                if value:
                    data[field_name] = _coerce_value_fast(field_types.get(field_name), value)
                else:
                    data[field_name] = ""

        if not pc.extensible and len(remaining_fields) > num_named and self._strict_parsing:
            overflow = len(remaining_fields) - num_named
            msg = (
                f"Object has {overflow} extra field(s) but type is not extensible "
                f"(expected at most {num_named}, got {len(remaining_fields)})"
            )
            raise ValueError(msg)

        if pc.extensible and num_named < len(remaining_fields):
            extra = remaining_fields[num_named:]
            self._append_extensible_fields(
                data=data,
                extra=extra,
                field_names=field_names,
                field_types=field_types,
                pc=pc,
            )

        return data

    def _append_extensible_fields(
        self,
        *,
        data: dict[str, Any],
        extra: list[str],
        field_names: list[str],
        field_types: dict[str, str | None],
        pc: ParsingCache,
    ) -> None:
        """Append extensible field groups to parsed data."""
        ext_size = pc.ext_size
        if ext_size <= 0:
            if self._strict_parsing:
                msg = "Object is marked extensible but extensible group size is invalid"
                raise ValueError(msg)
            return

        ext_names = pc.ext_field_names
        num_ext = len(ext_names)

        # Pre-compute type per extensible index — avoids a dict lookup per field.
        ext_types = tuple(field_types.get(name) for name in ext_names)

        # First group (group_idx=0): field names are just ext_names — no suffix,
        # no f-string allocation.
        first_group = extra[:ext_size]
        for j, value in enumerate(first_group):
            if j >= num_ext:
                continue
            ext_field = ext_names[j]
            if value:
                data[ext_field] = _coerce_value_fast(ext_types[j], value)
            else:
                data[ext_field] = ""
            field_names.append(ext_field)

        # Remaining groups: need a suffix.
        for group_idx in range(ext_size, len(extra), ext_size):
            suffix = f"_{group_idx // ext_size + 1}"
            group = extra[group_idx : group_idx + ext_size]
            for j, value in enumerate(group):
                if j >= num_ext:
                    continue
                ext_field = f"{ext_names[j]}{suffix}"
                if value:
                    data[ext_field] = _coerce_value_fast(ext_types[j], value)
                else:
                    data[ext_field] = ""
                field_names.append(ext_field)

    def _parse_fields(self, fields_raw: str) -> list[str]:
        """Parse and clean field values from raw string."""
        # Fast path: comments already stripped by _COMMENT_PATTERN in _parse_objects
        if "!" not in fields_raw:
            return [part.strip() for part in fields_raw.split(",")]

        # Slow path: strip inline comments (safety fallback)
        lines: list[str] = []
        for line in fields_raw.split("\n"):
            idx = line.find("!")
            if idx >= 0:
                line = line[:idx]
            lines.append(line)
        clean_text = " ".join(lines)
        return [part.strip() for part in clean_text.split(",")]

    @staticmethod
    def _line_and_column(content: bytes, offset: int) -> tuple[int, int]:
        """Convert a byte offset to 1-based (line, column)."""
        line = content.count(b"\n", 0, offset) + 1
        previous_newline = content.rfind(b"\n", 0, offset)
        if previous_newline < 0:
            return (line, offset + 1)
        return (line, offset - previous_newline)

    @staticmethod
    def _extract_object_name(match: re.Match[bytes], encoding: str) -> str | None:
        """Best-effort extraction of the raw first field (typically object name)."""
        fields_raw = match.group(2).decode(encoding)
        first = fields_raw.split(",", maxsplit=1)[0].strip()
        return first or None

    def _raise_parse_error(
        self,
        content: bytes,
        offset: int,
        message: str,
        *,
        obj_type: str | None = None,
        obj_name: str | None = None,
    ) -> None:
        """Raise a ParseError with contextual diagnostics."""
        line, column = self._line_and_column(content, offset)
        diagnostic = ParseDiagnostic(
            message=message,
            filepath=str(self._filepath),
            obj_type=obj_type,
            obj_name=obj_name,
            line=line,
            column=column,
        )
        summary = "Failed to parse IDF"
        raise IDFParseError(summary, diagnostics=[diagnostic])

    def _resolve_type_cache(
        self,
        *,
        content: bytes,
        schema: EpJSONSchema | None,
        type_cache: dict[str, ParsingCache | None],
        canonical_cache: dict[str, str],
        skipped_types: set[str],
        obj_type: str,
        obj_name: str | None,
        match_offset: int,
    ) -> tuple[ParsingCache | None, bool, str]:
        """Resolve and cache parsing metadata for an object type.

        Returns ``(cache, should_skip, canonical_type)`` where *canonical_type*
        is the PascalCase schema name (may differ from the raw IDF casing).
        """
        if schema is None:
            return (None, False, obj_type)

        pc = type_cache.get(obj_type)
        if pc is None and obj_type not in type_cache:
            pc = schema.get_parsing_cache(obj_type)
            type_cache[obj_type] = pc

        if pc is not None:
            # Return cached canonical name (resolved once per raw type).
            canonical = canonical_cache.get(obj_type)
            if canonical is None:
                canonical = schema.resolve_type_name(obj_type) or obj_type
                canonical_cache[obj_type] = canonical
            return (pc, False, canonical)

        if self._strict_parsing:
            msg = f"Unknown object type '{obj_type}'"
            self._raise_parse_error(content, match_offset, msg, obj_type=obj_type, obj_name=obj_name)
        skipped_types.add(obj_type)
        return (None, True, obj_type)

parse(version=None, *, strict=True, preserve_formatting=False)

Parse the IDF file into an IDFDocument.

Parameters:

Name	Type	Description	Default
version	tuple[int, int, int] | None	Optional version override	None
strict	bool	Enforce strict field access on the resulting document.	True
preserve_formatting	bool	Build a CST for lossless round-tripping.	False

Returns:

Type	Description
IDFDocument	Parsed IDFDocument

Source code in src/idfkit/idf_parser.py

def parse(
    self,
    version: tuple[int, int, int] | None = None,
    *,
    strict: bool = True,
    preserve_formatting: bool = False,
) -> IDFDocument:
    """
    Parse the IDF file into an IDFDocument.

    Args:
        version: Optional version override
        strict: Enforce strict field access on the resulting document.
        preserve_formatting: Build a CST for lossless round-tripping.

    Returns:
        Parsed IDFDocument
    """
    t0 = time.perf_counter()
    logger.debug("Parsing IDF file %s", self._filepath)

    # Load content (with mmap for large files)
    content = self._load_content()

    # Detect version if not provided
    if version is None:
        version = self._detect_version(content)
        logger.debug("Detected version %d.%d.%d", *version)

    # Load schema if not provided
    schema = self._schema
    if schema is None:
        from .schema import get_schema

        schema = get_schema(version)

    # Create document
    doc = IDFDocument(version=version, schema=schema, filepath=self._filepath, strict=strict)  # type: ignore[reportCallIssue]  # .pyi uses covariant Strict

    # Parse objects
    self._parse_objects(content, doc, schema)

    # Build CST for lossless round-tripping (opt-in, no cost when False)
    if preserve_formatting:
        original_text = content.decode(self._encoding)
        cst = _build_idf_cst(original_text)
        if _link_cst_to_objects(cst, doc):
            doc._cst = cst  # pyright: ignore[reportAttributeAccessIssue]
            doc._raw_text = original_text  # pyright: ignore[reportAttributeAccessIssue]
        else:
            logger.warning("CST discarded due to linking failure — lossless round-trip disabled")

    elapsed = time.perf_counter() - t0
    logger.info("Parsed %d objects from %s in %.3fs", len(doc), self._filepath, elapsed)

    return doc

get_idf_version(filepath)

Quick version detection without full parsing.

Only reads the first 10 KB of the file, making it very fast even for large models.

Parameters:

Name	Type	Description	Default
filepath	Path | str	Path to IDF file	required

Returns:

Type	Description
tuple[int, int, int]	Version tuple (major, minor, patch)

Raises:

Type	Description
VersionNotFoundError	If version cannot be detected

Examples:

Check which EnergyPlus version a model was created for (reads only the first 10 KB for speed):

```python
from idfkit import get_idf_version

version = get_idf_version("5ZoneAirCooled.idf")
print(f"EnergyPlus v{version[0]}.{version[1]}.{version[2]}")
```

Source code in src/idfkit/idf_parser.py

def get_idf_version(filepath: Path | str) -> tuple[int, int, int]:
    """
    Quick version detection without full parsing.

    Only reads the first 10 KB of the file, making it very fast
    even for large models.

    Args:
        filepath: Path to IDF file

    Returns:
        Version tuple (major, minor, patch)

    Raises:
        VersionNotFoundError: If version cannot be detected

    Examples:
        Check which EnergyPlus version a model was created for
        (reads only the first 10 KB for speed):

            ```python
            from idfkit import get_idf_version

            version = get_idf_version("5ZoneAirCooled.idf")
            print(f"EnergyPlus v{version[0]}.{version[1]}.{version[2]}")
            ```
    """
    filepath = Path(filepath)

    with open(filepath, "rb") as f:
        header = f.read(10240)

    match = _VERSION_PATTERN.search(header)
    if match:
        major = int(match.group(1))
        minor = int(match.group(2))
        patch = int(match.group(3)) if match.group(3) else 0
        return (major, minor, patch)

    raise VersionNotFoundError(str(filepath))

iter_idf_objects(filepath, encoding='latin-1')

Iterate over objects in an IDF file without loading into document.

Yields:

Type	Description
tuple[str, str, list[str]]	Tuples of (object_type, name, [field_values])

This is useful for quick scanning or filtering without full parsing.

Note

Type names are returned exactly as they appear in the IDF file (no schema-based case normalization). Use case-insensitive comparisons when filtering: obj_type.upper() == "ZONE".

Examples:

Count thermal zones without loading the full document (useful for quickly sizing batch runs):

```python
from idfkit import iter_idf_objects

zone_count = sum(
    1 for obj_type, name, _
    in iter_idf_objects("5ZoneAirCooled.idf")
    if obj_type == "Zone"
)
```

Collect all material names for an audit report:

```python
materials = [
    name for obj_type, name, _
    in iter_idf_objects("LargeOffice.idf")
    if obj_type == "Material"
]
```

Source code in src/idfkit/idf_parser.py

def iter_idf_objects(
    filepath: Path | str,
    encoding: str = "latin-1",
) -> Iterator[tuple[str, str, list[str]]]:
    """
    Iterate over objects in an IDF file without loading into document.

    Yields:
        Tuples of (object_type, name, [field_values])

    This is useful for quick scanning or filtering without full parsing.

    Note:
        Type names are returned exactly as they appear in the IDF file
        (no schema-based case normalization).  Use case-insensitive
        comparisons when filtering: ``obj_type.upper() == "ZONE"``.

    Examples:
        Count thermal zones without loading the full document
        (useful for quickly sizing batch runs):

            ```python
            from idfkit import iter_idf_objects

            zone_count = sum(
                1 for obj_type, name, _
                in iter_idf_objects("5ZoneAirCooled.idf")
                if obj_type == "Zone"
            )
            ```

        Collect all material names for an audit report:

            ```python
            materials = [
                name for obj_type, name, _
                in iter_idf_objects("LargeOffice.idf")
                if obj_type == "Material"
            ]
            ```
    """
    filepath = Path(filepath)

    with open(filepath, "rb") as f:
        content = f.read()

    # Strip comments before matching to prevent phantom objects
    content = _COMMENT_PATTERN.sub(b"", content)

    for match in _OBJECT_PATTERN.finditer(content):
        obj_type = match.group(1).decode(encoding).strip()
        fields_raw = match.group(2).decode(encoding)

        # Split and clean fields
        fields: list[str] = []
        for part in fields_raw.split(","):
            if "!" in part:
                part = part[: part.index("!")]
            fields.append(part.strip())

        obj_name = fields[0] if fields else ""
        yield (obj_type, obj_name, fields[1:])

parse_idf(filepath, schema=None, version=None, encoding='latin-1', strict_parsing=True, strict=True, *, preserve_formatting=False)

Parse an IDF file into an IDFDocument.

Parameters:

Name	Type	Description	Default
filepath	Path | str	Path to the IDF file	required
schema	EpJSONSchema | None	Optional EpJSONSchema for field ordering and type coercion	None
version	tuple[int, int, int] | None	Optional version override (auto-detected if not provided)	None
encoding	str	File encoding (default: latin-1 for compatibility)	'latin-1'
strict_parsing	bool	If True, fail fast on malformed objects (default: True)	True
strict	bool	When True, accessing or setting an unknown field name on any IDFObject raises :class:~idfkit.exceptions.InvalidFieldError instead of returning None.	True
preserve_formatting	bool	If True, build a Concrete Syntax Tree (CST) so that writing the document back preserves original formatting, comments, and whitespace for unmodified objects. The default code path is unchanged — no performance penalty when False.	False

Returns:

Type	Description
IDFDocument	Parsed IDFDocument

Raises:

Type	Description
VersionNotFoundError	If version cannot be detected
IdfKitError	If parsing fails

Examples:

Load and inspect a DOE reference building:

```python
from idfkit import parse_idf

model = parse_idf("RefBldgSmallOfficeNew2004.idf")
for zone in model["Zone"]:
    print(zone.name, zone.x_origin)
```

Force a specific EnergyPlus version when auto-detection fails (e.g., a pre-v8.9 file that was manually upgraded):

```python
model = parse_idf("legacy_building.idf", version=(9, 6, 0))
```

Round-trip an IDF file losslessly:

```python
model = parse_idf("building.idf", preserve_formatting=True)
# write_idf(model) reproduces the original byte-for-byte
```

Source code in src/idfkit/idf_parser.py

def parse_idf(
    filepath: Path | str,
    schema: EpJSONSchema | None = None,
    version: tuple[int, int, int] | None = None,
    encoding: str = "latin-1",
    strict_parsing: bool = True,
    strict: bool = True,
    *,
    preserve_formatting: bool = False,
) -> IDFDocument:
    """
    Parse an IDF file into an IDFDocument.

    Args:
        filepath: Path to the IDF file
        schema: Optional EpJSONSchema for field ordering and type coercion
        version: Optional version override (auto-detected if not provided)
        encoding: File encoding (default: latin-1 for compatibility)
        strict_parsing: If True, fail fast on malformed objects (default: True)
        strict: When ``True``, accessing or setting an unknown field name on any
            IDFObject raises :class:`~idfkit.exceptions.InvalidFieldError` instead
            of returning ``None``.
        preserve_formatting: If ``True``, build a Concrete Syntax Tree (CST)
            so that writing the document back preserves original formatting,
            comments, and whitespace for unmodified objects.  The default
            code path is unchanged — no performance penalty when ``False``.

    Returns:
        Parsed IDFDocument

    Raises:
        VersionNotFoundError: If version cannot be detected
        IdfKitError: If parsing fails

    Examples:
        Load and inspect a DOE reference building:

            ```python
            from idfkit import parse_idf

            model = parse_idf("RefBldgSmallOfficeNew2004.idf")
            for zone in model["Zone"]:
                print(zone.name, zone.x_origin)
            ```

        Force a specific EnergyPlus version when auto-detection fails
        (e.g., a pre-v8.9 file that was manually upgraded):

            ```python
            model = parse_idf("legacy_building.idf", version=(9, 6, 0))
            ```

        Round-trip an IDF file losslessly:

            ```python
            model = parse_idf("building.idf", preserve_formatting=True)
            # write_idf(model) reproduces the original byte-for-byte
            ```
    """
    filepath = Path(filepath)

    if not filepath.exists():
        raise FileNotFoundError(f"IDF file not found: {filepath}")  # noqa: TRY003

    parser = IDFParser(filepath, schema, encoding, strict_parsing=strict_parsing)
    return parser.parse(version, strict=strict, preserve_formatting=preserve_formatting)

epJSON Parser

epJSON parser - parses EnergyPlus epJSON files into IDFDocument.

The epJSON format is the native JSON representation of EnergyPlus models. Parsing is straightforward since it's already structured JSON.

EpJSONParser

Parser for epJSON files.

epJSON is the native JSON format for EnergyPlus models, making parsing straightforward - just json.load() and transform.

Source code in src/idfkit/epjson_parser.py

class EpJSONParser:
    """
    Parser for epJSON files.

    epJSON is the native JSON format for EnergyPlus models, making
    parsing straightforward - just json.load() and transform.
    """

    __slots__ = ("_filepath", "_schema")

    def __init__(
        self,
        filepath: Path,
        schema: EpJSONSchema | None = None,
    ):
        self._filepath = filepath
        self._schema = schema

    def parse(
        self,
        version: tuple[int, int, int] | None = None,
        *,
        strict: bool = True,
        preserve_formatting: bool = False,
    ) -> IDFDocument:
        """
        Parse the epJSON file into an IDFDocument.

        Args:
            version: Optional version override
            strict: Enforce strict field access on the resulting document.
            preserve_formatting: Store raw JSON text for lossless round-tripping.

        Returns:
            Parsed IDFDocument
        """
        t0 = time.perf_counter()
        logger.debug("Parsing epJSON file %s", self._filepath)

        # Load JSON
        with open(self._filepath, encoding="utf-8") as f:
            raw_text = f.read()
        data: dict[str, Any] = json.loads(raw_text)

        # Detect version if not provided
        if version is None:
            version = self._detect_version(data)
            logger.debug("Detected version %d.%d.%d", *version)

        # Load schema if not provided
        schema = self._schema
        if schema is None:
            from .schema import get_schema

            schema = get_schema(version)

        # Create document
        doc = IDFDocument(version=version, schema=schema, filepath=self._filepath, strict=strict)  # type: ignore[reportCallIssue]  # .pyi uses covariant Strict

        # Parse objects
        self._parse_objects(data, doc, schema)

        # Store raw text for lossless round-tripping (opt-in).
        if preserve_formatting:
            doc._raw_text = raw_text  # pyright: ignore[reportAttributeAccessIssue]
            # Mark all objects as "pristine" with a sentinel source_text so
            # that the writer can detect mutations.
            for obj in doc.all_objects:
                object.__setattr__(obj, "_source_text", "")

        elapsed = time.perf_counter() - t0
        logger.info("Parsed %d objects from %s in %.3fs", len(doc), self._filepath, elapsed)

        return doc

    def _detect_version(self, data: dict[str, Any]) -> tuple[int, int, int]:
        """Detect EnergyPlus version from epJSON data."""
        # Version is in the "Version" object
        version_obj = data.get("Version")

        if version_obj:
            # epJSON format: {"Version": {"Version 1": {"version_identifier": "23.2"}}}
            for _name, fields in version_obj.items():
                version_str: str = fields.get("version_identifier", "")
                if version_str:
                    return self._parse_version_string(version_str)

        raise VersionNotFoundError(str(self._filepath))

    @staticmethod
    def _parse_version_string(version_str: str) -> tuple[int, int, int]:
        """Parse version string like '23.2' or '9.2.0'."""
        parts = version_str.split(".")
        major = int(parts[0]) if len(parts) > 0 else 0
        minor = int(parts[1]) if len(parts) > 1 else 0
        patch = int(parts[2]) if len(parts) > 2 else 0
        return (major, minor, patch)

    def _parse_objects(
        self,
        data: dict[str, Any],
        doc: IDFDocument,
        schema: EpJSONSchema | None,
    ) -> None:
        """Parse all objects from epJSON data into document."""
        addidfobject = doc.addidfobject

        for obj_type, objects in data.items():
            if not isinstance(objects, dict):
                continue

            # Get schema info from parsing cache
            pc: ParsingCache | None = None
            obj_schema: dict[str, Any] | None = None
            base_field_names: tuple[str, ...] | None = None
            ref_fields: frozenset[str] | None = None
            has_name = True
            if schema:
                pc = schema.get_parsing_cache(obj_type)
                if pc is not None:
                    obj_schema = pc.obj_schema
                    has_name = pc.has_name
                    base_field_names = pc.field_names if has_name else pc.all_field_names
                    ref_fields = pc.ref_fields

            # epJSON format: {"ObjectType": {"obj_name": {fields...}, ...}}
            objects_dict = cast(dict[str, Any], objects)
            for obj_name, fields in objects_dict.items():
                if not isinstance(fields, dict):
                    continue

                # Nameless objects: use empty string instead of epJSON dict key
                name = obj_name if has_name else ""

                # Create per-object field_order copy so extensible fields can be added
                fields_dict = cast(dict[str, Any], fields)
                field_order = self._build_field_order(base_field_names, fields_dict, pc)

                obj = IDFObject(
                    obj_type=obj_type,
                    name=name,
                    data=dict(fields_dict),  # Copy the fields dict
                    schema=obj_schema,
                    field_order=field_order,
                    ref_fields=ref_fields,
                    extensibles=frozenset(pc.ext_field_names) if pc else None,
                )

                addidfobject(obj)

    @staticmethod
    def _build_field_order(
        base_field_names: tuple[str, ...] | None,
        fields_dict: dict[str, Any],
        pc: ParsingCache | None,
    ) -> list[str] | None:
        """Build field_order including extensible fields present in the data."""
        if base_field_names is None:
            return None

        # Start with a copy of the base schema field names
        field_order = list(base_field_names)
        base_set = set(base_field_names)

        # Find extensible fields in the data that aren't in the base field list
        if pc is not None and pc.extensible and pc.ext_field_names:
            ext_names = pc.ext_field_names
            group_idx = 0
            while True:
                suffix = "" if group_idx == 0 else f"_{group_idx + 1}"
                group_fields = [f"{name}{suffix}" for name in ext_names]

                if not any(f in fields_dict for f in group_fields):
                    break

                for f in group_fields:
                    if f not in base_set:
                        field_order.append(f)

                group_idx += 1

        return field_order

parse(version=None, *, strict=True, preserve_formatting=False)

Parse the epJSON file into an IDFDocument.

Parameters:

Name	Type	Description	Default
version	tuple[int, int, int] | None	Optional version override	None
strict	bool	Enforce strict field access on the resulting document.	True
preserve_formatting	bool	Store raw JSON text for lossless round-tripping.	False

Returns:

Type	Description
IDFDocument	Parsed IDFDocument

Source code in src/idfkit/epjson_parser.py

def parse(
    self,
    version: tuple[int, int, int] | None = None,
    *,
    strict: bool = True,
    preserve_formatting: bool = False,
) -> IDFDocument:
    """
    Parse the epJSON file into an IDFDocument.

    Args:
        version: Optional version override
        strict: Enforce strict field access on the resulting document.
        preserve_formatting: Store raw JSON text for lossless round-tripping.

    Returns:
        Parsed IDFDocument
    """
    t0 = time.perf_counter()
    logger.debug("Parsing epJSON file %s", self._filepath)

    # Load JSON
    with open(self._filepath, encoding="utf-8") as f:
        raw_text = f.read()
    data: dict[str, Any] = json.loads(raw_text)

    # Detect version if not provided
    if version is None:
        version = self._detect_version(data)
        logger.debug("Detected version %d.%d.%d", *version)

    # Load schema if not provided
    schema = self._schema
    if schema is None:
        from .schema import get_schema

        schema = get_schema(version)

    # Create document
    doc = IDFDocument(version=version, schema=schema, filepath=self._filepath, strict=strict)  # type: ignore[reportCallIssue]  # .pyi uses covariant Strict

    # Parse objects
    self._parse_objects(data, doc, schema)

    # Store raw text for lossless round-tripping (opt-in).
    if preserve_formatting:
        doc._raw_text = raw_text  # pyright: ignore[reportAttributeAccessIssue]
        # Mark all objects as "pristine" with a sentinel source_text so
        # that the writer can detect mutations.
        for obj in doc.all_objects:
            object.__setattr__(obj, "_source_text", "")

    elapsed = time.perf_counter() - t0
    logger.info("Parsed %d objects from %s in %.3fs", len(doc), self._filepath, elapsed)

    return doc

get_epjson_version(filepath)

Quick version detection from epJSON file.

Parameters:

Name	Type	Description	Default
filepath	Path | str	Path to epJSON file	required

Returns:

Type	Description
tuple[int, int, int]	Version tuple (major, minor, patch)

Raises:

Type	Description
VersionNotFoundError	If version cannot be detected

Examples:

Detect the EnergyPlus version of an epJSON file:

```python
from idfkit.epjson_parser import get_epjson_version

version = get_epjson_version("SmallOffice.epJSON")
print(f"EnergyPlus v{version[0]}.{version[1]}")
```

Source code in src/idfkit/epjson_parser.py

def get_epjson_version(filepath: Path | str) -> tuple[int, int, int]:
    """
    Quick version detection from epJSON file.

    Args:
        filepath: Path to epJSON file

    Returns:
        Version tuple (major, minor, patch)

    Raises:
        VersionNotFoundError: If version cannot be detected

    Examples:
        Detect the EnergyPlus version of an epJSON file:

            ```python
            from idfkit.epjson_parser import get_epjson_version

            version = get_epjson_version("SmallOffice.epJSON")
            print(f"EnergyPlus v{version[0]}.{version[1]}")
            ```
    """
    filepath = Path(filepath)

    with open(filepath, encoding="utf-8") as f:
        # Parse just enough to get version
        data = json.load(f)

    version_obj = data.get("Version")
    if version_obj:
        for _name, fields in version_obj.items():
            version_str: str = fields.get("version_identifier", "")
            if version_str:
                parts = version_str.split(".")
                major = int(parts[0]) if len(parts) > 0 else 0
                minor = int(parts[1]) if len(parts) > 1 else 0
                patch = int(parts[2]) if len(parts) > 2 else 0
                return (major, minor, patch)

    raise VersionNotFoundError(str(filepath))

load_epjson(filepath)

Load raw epJSON data without parsing into document.

Useful for quick inspection or manipulation when you need the raw JSON dict rather than an IDFDocument.

Examples:

Grab the raw JSON dict for custom post-processing:

```python
from idfkit.epjson_parser import load_epjson

data = load_epjson("SmallOffice.epJSON")
zone_names = list(data.get("Zone", {}).keys())
```

Source code in src/idfkit/epjson_parser.py

def load_epjson(filepath: Path | str) -> dict[str, Any]:
    """
    Load raw epJSON data without parsing into document.

    Useful for quick inspection or manipulation when you need the
    raw JSON dict rather than an [IDFDocument][idfkit.document.IDFDocument].

    Examples:
        Grab the raw JSON dict for custom post-processing:

            ```python
            from idfkit.epjson_parser import load_epjson

            data = load_epjson("SmallOffice.epJSON")
            zone_names = list(data.get("Zone", {}).keys())
            ```
    """
    filepath = Path(filepath)
    with open(filepath, encoding="utf-8") as f:
        return json.load(f)

parse_epjson(filepath, schema=None, version=None, strict=True, *, preserve_formatting=False)

Parse an epJSON file into an IDFDocument.

Parameters:

Name	Type	Description	Default
filepath	Path | str	Path to the epJSON file	required
schema	EpJSONSchema | None	Optional EpJSONSchema for validation	None
version	tuple[int, int, int] | None	Optional version override (auto-detected if not provided)	None
strict	bool	When True, accessing or setting an unknown field name on any IDFObject raises :class:~idfkit.exceptions.InvalidFieldError instead of returning None.	True
preserve_formatting	bool	If True, store the raw JSON text so that :func:~idfkit.writers.write_epjson can reproduce it byte-for-byte when no objects have been modified.	False

Returns:

Type	Description
IDFDocument	Parsed IDFDocument

Raises:

Type	Description
VersionNotFoundError	If version cannot be detected
IdfKitError	If parsing fails

Examples:

Load an epJSON model and list its thermal zones:

```python
from idfkit import parse_epjson

model = parse_epjson("SmallOffice.epJSON")
for zone in model["Zone"]:
    print(zone.name)
```

Source code in src/idfkit/epjson_parser.py

def parse_epjson(
    filepath: Path | str,
    schema: EpJSONSchema | None = None,
    version: tuple[int, int, int] | None = None,
    strict: bool = True,
    *,
    preserve_formatting: bool = False,
) -> IDFDocument:
    """
    Parse an epJSON file into an IDFDocument.

    Args:
        filepath: Path to the epJSON file
        schema: Optional EpJSONSchema for validation
        version: Optional version override (auto-detected if not provided)
        strict: When ``True``, accessing or setting an unknown field name on any
            IDFObject raises :class:`~idfkit.exceptions.InvalidFieldError` instead
            of returning ``None``.
        preserve_formatting: If ``True``, store the raw JSON text so that
            :func:`~idfkit.writers.write_epjson` can reproduce it
            byte-for-byte when no objects have been modified.

    Returns:
        Parsed IDFDocument

    Raises:
        VersionNotFoundError: If version cannot be detected
        IdfKitError: If parsing fails

    Examples:
        Load an epJSON model and list its thermal zones:

            ```python
            from idfkit import parse_epjson

            model = parse_epjson("SmallOffice.epJSON")
            for zone in model["Zone"]:
                print(zone.name)
            ```
    """
    filepath = Path(filepath)

    if not filepath.exists():
        raise FileNotFoundError(f"epJSON file not found: {filepath}")  # noqa: TRY003

    parser = EpJSONParser(filepath, schema)
    return parser.parse(version, strict=strict, preserve_formatting=preserve_formatting)

Writers

Writers for IDF and epJSON formats.

Provides serialization of IDFDocument to both formats.

The write_idf function accepts an output_type parameter that mirrors eppy's idf.outputtype options:

• "standard" (default): field comments included (!- Field Name).
• "nocomment": no field comments, one field per line.
• "compressed": entire object on a single line (minimal whitespace).

EpJSONWriter

Writes IDFDocument to epJSON format.

The epJSON format is:

{
  "Version": {
    "Version 1": {
      "version_identifier": "23.2"
    }
  },
  "Zone": {
    "Zone 1": {
      "direction_of_relative_north": 0.0,
      ...
    }
  }
}

Source code in src/idfkit/writers.py

class EpJSONWriter:
    """
    Writes IDFDocument to epJSON format.

    The epJSON format is:
    ```json
    {
      "Version": {
        "Version 1": {
          "version_identifier": "23.2"
        }
      },
      "Zone": {
        "Zone 1": {
          "direction_of_relative_north": 0.0,
          ...
        }
      }
    }
    ```
    """

    def __init__(self, doc: IDFDocument):
        self._doc = doc

    def to_dict(self) -> dict[str, Any]:
        """Convert document to epJSON dict."""
        result: dict[str, Any] = {}

        # Add Version
        result["Version"] = {"Version 1": {"version_identifier": _resolve_version_identifier(self._doc)}}

        # Add objects by type
        for obj_type, collection in self._doc.collections.items():
            if obj_type.upper() == "VERSION":
                continue
            if not collection:
                continue

            result[obj_type] = {}
            nameless_counter = 0
            for obj in collection:
                obj_data = self._object_to_dict(obj)
                if obj.name:
                    key = obj.name
                else:
                    # Generate unique key for nameless objects (e.g. Output:Variable)
                    nameless_counter += 1
                    key = f"{obj_type} {nameless_counter}"
                result[obj_type][key] = obj_data

        return result

    def _object_to_dict(self, obj: IDFObject) -> dict[str, Any]:
        """Convert object to epJSON dict (excluding name)."""
        result: dict[str, Any] = {}

        for field_name, value in obj.data.items():
            if value is not None and value != "":
                result[field_name] = self._format_value(value)

        return result

    def _format_value(self, value: Any) -> Any:
        """Format a field value for epJSON output."""
        # epJSON uses native JSON types
        if isinstance(value, str):
            # Check for special values
            lower = value.lower()
            if lower == "autocalculate":
                return "Autocalculate"
            if lower == "autosize":
                return "Autosize"
            if lower == "yes":
                return "Yes"
            if lower == "no":
                return "No"
        return value

    def write_to_file(self, filepath: Path | str, indent: int = 2) -> None:
        """Write to file."""
        data = self.to_dict()
        with open(filepath, "w", encoding="utf-8") as f:
            json.dump(data, f, indent=indent)

to_dict()

Convert document to epJSON dict.

Source code in src/idfkit/writers.py

def to_dict(self) -> dict[str, Any]:
    """Convert document to epJSON dict."""
    result: dict[str, Any] = {}

    # Add Version
    result["Version"] = {"Version 1": {"version_identifier": _resolve_version_identifier(self._doc)}}

    # Add objects by type
    for obj_type, collection in self._doc.collections.items():
        if obj_type.upper() == "VERSION":
            continue
        if not collection:
            continue

        result[obj_type] = {}
        nameless_counter = 0
        for obj in collection:
            obj_data = self._object_to_dict(obj)
            if obj.name:
                key = obj.name
            else:
                # Generate unique key for nameless objects (e.g. Output:Variable)
                nameless_counter += 1
                key = f"{obj_type} {nameless_counter}"
            result[obj_type][key] = obj_data

    return result

write_to_file(filepath, indent=2)

Write to file.

Source code in src/idfkit/writers.py

def write_to_file(self, filepath: Path | str, indent: int = 2) -> None:
    """Write to file."""
    data = self.to_dict()
    with open(filepath, "w", encoding="utf-8") as f:
        json.dump(data, f, indent=indent)

IDFWriter

Writes IDFDocument to IDF text format.

The IDF format is:

ObjectType,
  field1,    !- Field 1 Name
  field2,    !- Field 2 Name
  field3;    !- Field 3 Name

Supports three output_type modes mirroring eppy's idf.outputtype:

• "standard" — full comments (default).
• "nocomment" — no field comments, one field per line.
• "compressed" — each object on a single line.

Source code in src/idfkit/writers.py

class IDFWriter:
    """
    Writes IDFDocument to IDF text format.

    The IDF format is:
    ```
    ObjectType,
      field1,    !- Field 1 Name
      field2,    !- Field 2 Name
      field3;    !- Field 3 Name
    ```

    Supports three *output_type* modes mirroring eppy's
    ``idf.outputtype``:

    - ``"standard"`` — full comments (default).
    - ``"nocomment"`` — no field comments, one field per line.
    - ``"compressed"`` — each object on a single line.
    """

    def __init__(self, doc: IDFDocument, output_type: OutputType = "standard"):
        self._doc = doc
        self._output_type = output_type

    def to_string(self) -> str:
        """Convert document to IDF string."""
        lines: list[str] = []

        if self._output_type != "compressed":
            # Write header comment
            lines.append("!-Generator archetypal")
            lines.append("!-Option SortedOrder")
            lines.append("")

        # Write Version first
        version_identifier = _resolve_version_identifier(self._doc)
        if self._output_type == "compressed":
            lines.append(f"Version,{version_identifier};")
        else:
            lines.append("Version,")
            if self._output_type == "standard":
                lines.append(f"  {version_identifier};                    !- Version Identifier")
            else:
                lines.append(f"  {version_identifier};")
            lines.append("")

        # Write objects grouped by type
        for obj_type in sorted(self._doc.collections.keys()):
            if obj_type.upper() == "VERSION":
                continue
            collection = self._doc.collections[obj_type]
            if not collection:
                continue

            for obj in collection:
                obj_str = self.format_object(obj)
                lines.append(obj_str)
                if self._output_type != "compressed":
                    lines.append("")

        return "\n".join(lines)

    def _get_field_values_and_comments(self, obj: IDFObject) -> tuple[list[str], list[str]]:
        """Get the ordered field values and comment labels for *obj*."""
        obj_type = obj.obj_type
        schema = self._doc.schema

        obj_has_name = True
        if schema:
            obj_has_name = schema.has_name(obj_type)

        if obj.field_order:
            if obj_has_name:
                field_names: list[str] = ["name", *list(obj.field_order)]
            else:
                field_names = list(obj.field_order)
        elif schema:
            field_names = schema.get_all_field_names(obj_type)
        else:
            field_names = ["name", *list(obj.data.keys())] if obj_has_name else list(obj.data.keys())

        values: list[str] = []
        comments: list[str] = []

        for field_name in field_names:
            if field_name == "name":
                values.append(obj.name or "")
                comments.append("Name")
            else:
                value = obj.data.get(field_name)
                values.append(self._format_value(value))
                comment = field_name.replace("_", " ").title()
                comments.append(comment)

        # Trim trailing empty fields
        while len(values) > 1 and values[-1] == "":
            values.pop()
            comments.pop()

        return values, comments

    def format_object(self, obj: IDFObject) -> str:
        """Convert a single object to IDF string."""
        values, comments = self._get_field_values_and_comments(obj)
        obj_type = obj.obj_type

        if self._output_type == "compressed":
            parts = ",".join(values)
            return f"{obj_type},{parts};"

        lines: list[str] = [f"{obj_type},"]
        for i, (value, comment) in enumerate(zip(values, comments, strict=False)):
            is_last = i == len(values) - 1
            terminator = ";" if is_last else ","

            if self._output_type == "standard":
                field_str = f"  {value}{terminator}"
                field_str = field_str.ljust(30)
                field_str += f"!- {comment}"
            else:
                # nocomment
                field_str = f"  {value}{terminator}"

            lines.append(field_str)

        return "\n".join(lines)

    def _format_value(self, value: Any) -> str:
        """Format a field value for IDF output."""
        if value is None:
            return ""
        if isinstance(value, bool):
            return "Yes" if value else "No"
        if isinstance(value, float):
            if value == 0.0:
                return "0"
            abs_val = abs(value)
            if abs_val >= 1e10 or abs_val < 0.0001:
                return f"{value:.6e}"
            return f"{value:g}"
        if isinstance(value, list):
            # Handle vertex lists etc.
            items = cast(list[Any], value)
            return ", ".join(str(v) for v in items)
        text = str(value)
        if any(ch in text for ch in (",", ";", "!")):
            logger.warning(
                "Field value %r contains IDF delimiter characters (comma, semicolon, or exclamation mark) "
                "that will produce invalid IDF output",
                text,
            )
        return text

    def write_to_file(self, filepath: Path | str, encoding: str = "latin-1") -> None:
        """Write to file."""
        content = self.to_string()
        with open(filepath, "w", encoding=encoding) as f:
            f.write(content)

format_object(obj)

Convert a single object to IDF string.

Source code in src/idfkit/writers.py

def format_object(self, obj: IDFObject) -> str:
    """Convert a single object to IDF string."""
    values, comments = self._get_field_values_and_comments(obj)
    obj_type = obj.obj_type

    if self._output_type == "compressed":
        parts = ",".join(values)
        return f"{obj_type},{parts};"

    lines: list[str] = [f"{obj_type},"]
    for i, (value, comment) in enumerate(zip(values, comments, strict=False)):
        is_last = i == len(values) - 1
        terminator = ";" if is_last else ","

        if self._output_type == "standard":
            field_str = f"  {value}{terminator}"
            field_str = field_str.ljust(30)
            field_str += f"!- {comment}"
        else:
            # nocomment
            field_str = f"  {value}{terminator}"

        lines.append(field_str)

    return "\n".join(lines)

to_string()

Convert document to IDF string.

Source code in src/idfkit/writers.py

def to_string(self) -> str:
    """Convert document to IDF string."""
    lines: list[str] = []

    if self._output_type != "compressed":
        # Write header comment
        lines.append("!-Generator archetypal")
        lines.append("!-Option SortedOrder")
        lines.append("")

    # Write Version first
    version_identifier = _resolve_version_identifier(self._doc)
    if self._output_type == "compressed":
        lines.append(f"Version,{version_identifier};")
    else:
        lines.append("Version,")
        if self._output_type == "standard":
            lines.append(f"  {version_identifier};                    !- Version Identifier")
        else:
            lines.append(f"  {version_identifier};")
        lines.append("")

    # Write objects grouped by type
    for obj_type in sorted(self._doc.collections.keys()):
        if obj_type.upper() == "VERSION":
            continue
        collection = self._doc.collections[obj_type]
        if not collection:
            continue

        for obj in collection:
            obj_str = self.format_object(obj)
            lines.append(obj_str)
            if self._output_type != "compressed":
                lines.append("")

    return "\n".join(lines)

write_to_file(filepath, encoding='latin-1')

Write to file.

Source code in src/idfkit/writers.py

def write_to_file(self, filepath: Path | str, encoding: str = "latin-1") -> None:
    """Write to file."""
    content = self.to_string()
    with open(filepath, "w", encoding=encoding) as f:
        f.write(content)

convert_epjson_to_idf(epjson_path, idf_path=None)

Convert an epJSON file to IDF format.

Parameters:

Name	Type	Description	Default
epjson_path	Path | str	Input epJSON file path	required
idf_path	Path | str | None	Output IDF path (default: same name with .idf extension)	None

Returns:

Type	Description
Path	Path to the output file

Examples:

Convert an epJSON model back to classic IDF format:

```python
output = convert_epjson_to_idf("5ZoneAirCooled.epJSON")
# Creates 5ZoneAirCooled.idf

convert_epjson_to_idf("modern_model.epJSON", "classic_model.idf")
```

Source code in src/idfkit/writers.py

def convert_epjson_to_idf(
    epjson_path: Path | str,
    idf_path: Path | str | None = None,
) -> Path:
    """
    Convert an epJSON file to IDF format.

    Args:
        epjson_path: Input epJSON file path
        idf_path: Output IDF path (default: same name with .idf extension)

    Returns:
        Path to the output file

    Examples:
        Convert an epJSON model back to classic IDF format:

            ```python
            output = convert_epjson_to_idf("5ZoneAirCooled.epJSON")
            # Creates 5ZoneAirCooled.idf

            convert_epjson_to_idf("modern_model.epJSON", "classic_model.idf")
            ```
    """
    from .epjson_parser import parse_epjson

    epjson_path = Path(epjson_path)

    idf_path = epjson_path.with_suffix(".idf") if idf_path is None else Path(idf_path)

    doc = parse_epjson(epjson_path)
    write_idf(doc, idf_path)

    return idf_path

convert_idf_to_epjson(idf_path, epjson_path=None)

Convert an IDF file to epJSON format.

Parameters:

Name	Type	Description	Default
idf_path	Path | str	Input IDF file path	required
epjson_path	Path | str | None	Output epJSON path (default: same name with .epJSON extension)	None

Returns:

Type	Description
Path	Path to the output file

Examples:

Convert an IDF model to native JSON format:

```python
output = convert_idf_to_epjson("5ZoneAirCooled.idf")
# Creates 5ZoneAirCooled.epJSON

convert_idf_to_epjson("legacy_model.idf", "modern_model.epJSON")
```

Source code in src/idfkit/writers.py

def convert_idf_to_epjson(
    idf_path: Path | str,
    epjson_path: Path | str | None = None,
) -> Path:
    """
    Convert an IDF file to epJSON format.

    Args:
        idf_path: Input IDF file path
        epjson_path: Output epJSON path (default: same name with .epJSON extension)

    Returns:
        Path to the output file

    Examples:
        Convert an IDF model to native JSON format:

            ```python
            output = convert_idf_to_epjson("5ZoneAirCooled.idf")
            # Creates 5ZoneAirCooled.epJSON

            convert_idf_to_epjson("legacy_model.idf", "modern_model.epJSON")
            ```
    """
    from .idf_parser import parse_idf

    idf_path = Path(idf_path)

    epjson_path = idf_path.with_suffix(".epJSON") if epjson_path is None else Path(epjson_path)

    doc = parse_idf(idf_path)
    write_epjson(doc, epjson_path)

    return epjson_path

write_epjson(doc, filepath=None, indent=2, *, preserve_formatting=None)

Write document to epJSON format.

Parameters:

Name	Type	Description	Default
doc	IDFDocument[bool]	The document to write	required
filepath	Path | str | None	Output path (if None, returns string)	None
indent	int	JSON indentation	2
preserve_formatting	bool | None	If True, return the original JSON text verbatim when no objects have been modified. When None (the default), automatically uses lossless output if raw text is available and no objects were mutated.	None

Returns:

Type	Description
str | None	JSON string if filepath is None, otherwise None

Examples:

Serialize the model to epJSON for use with EnergyPlus v9.3+:

>>> from idfkit import new_document, write_epjson
>>> model = new_document()
>>> model.add("Zone", "Perimeter_ZN_1")
Zone('Perimeter_ZN_1')
>>> json_str = write_epjson(model)
>>> '"Zone"' in json_str
True

Write to disk:

```python
write_epjson(model, "in.epJSON")
```

Source code in src/idfkit/writers.py

def write_epjson(
    doc: IDFDocument[bool],
    filepath: Path | str | None = None,
    indent: int = 2,
    *,
    preserve_formatting: bool | None = None,
) -> str | None:
    """
    Write document to epJSON format.

    Args:
        doc: The document to write
        filepath: Output path (if None, returns string)
        indent: JSON indentation
        preserve_formatting: If ``True``, return the original JSON text
            verbatim when no objects have been modified.  When ``None``
            (the default), automatically uses lossless output if raw text
            is available and no objects were mutated.

    Returns:
        JSON string if filepath is None, otherwise None

    Examples:
        Serialize the model to epJSON for use with EnergyPlus v9.3+:

        >>> from idfkit import new_document, write_epjson
        >>> model = new_document()
        >>> model.add("Zone", "Perimeter_ZN_1")  # doctest: +ELLIPSIS
        Zone('Perimeter_ZN_1')
        >>> json_str = write_epjson(model)
        >>> '"Zone"' in json_str
        True

        Write to disk:

            ```python
            write_epjson(model, "in.epJSON")
            ```
    """
    # Note: epJSON preservation is all-or-nothing (any mutation or addition
    # falls back to the standard JSON writer), unlike IDF which has per-object
    # granularity via CST nodes.
    use_preserve = preserve_formatting if preserve_formatting is not None else doc.raw_text is not None

    # If preserve_formatting and we have raw text, check whether any object
    # was mutated.  If not, emit the original text verbatim.
    if use_preserve and doc.raw_text is not None:
        all_clean = all(obj.source_text is not None for obj in doc.all_objects)
        if all_clean:
            content = doc.raw_text
            if filepath:
                filepath = Path(filepath)
                with open(filepath, "w", encoding="utf-8") as f:
                    f.write(content)
                logger.info("Wrote epJSON (%d objects, lossless) to %s", len(doc), filepath)
                return None
            logger.debug("Serialized epJSON (%d objects, lossless) to string", len(doc))
            return content

    # Fall back to standard writer.
    writer = EpJSONWriter(doc)
    data = writer.to_dict()

    if filepath:
        filepath = Path(filepath)
        with open(filepath, "w", encoding="utf-8") as f:
            json.dump(data, f, indent=indent)
        logger.info("Wrote epJSON (%d objects) to %s", len(doc), filepath)
        return None

    logger.debug("Serialized epJSON (%d objects) to string", len(doc))
    return json.dumps(data, indent=indent)

write_idf(doc, filepath=None, encoding='latin-1', output_type='standard', *, preserve_formatting=None)

Write document to IDF format.

Parameters:

Name	Type	Description	Default
doc	IDFDocument[bool]	The document to write.	required
filepath	Path | str | None	Output path (if None, returns a string).	None
encoding	str	Output encoding.	'latin-1'
output_type	OutputType	Output formatting mode — "standard" (with comments), "nocomment" (no comments), or "compressed" (single-line objects). Mirrors eppy's idf.outputtype. Ignored when preserve_formatting is explicitly True. When preserve_formatting is None and output_type is not "standard", the explicit output type takes precedence and lossless mode is disabled.	'standard'
preserve_formatting	bool | None	If True, reproduce the original source text for unmodified objects and apply standard formatting only to objects that were mutated or added after parsing. Requires the document to have been parsed with preserve_formatting=True. When None (the default), automatically uses lossless output if a CST is available and output_type is "standard".	None

Returns:

Type	Description
str | None	IDF string if filepath is None, otherwise None.

Examples:

Serialize the model to an IDF string for inspection:

>>> from idfkit import new_document, write_idf
>>> model = new_document()
>>> model.add("Zone", "Perimeter_ZN_1")
Zone('Perimeter_ZN_1')
>>> idf_str = write_idf(model)
>>> "Zone," in idf_str
True

Write to disk for EnergyPlus simulation:

```python
write_idf(model, "in.idf")
```

Use compressed format for batch parametric runs:

>>> compressed = write_idf(model, output_type="compressed")
>>> "\n" not in compressed.split("Zone")[1].split(";")[0]
True

Lossless round-trip:

```python
from idfkit import load_idf, write_idf
model = load_idf("building.idf", preserve_formatting=True)
write_idf(model, "building_copy.idf")  # byte-identical
```

Source code in src/idfkit/writers.py

def write_idf(
    doc: IDFDocument[bool],
    filepath: Path | str | None = None,
    encoding: str = "latin-1",
    output_type: OutputType = "standard",
    *,
    preserve_formatting: bool | None = None,
) -> str | None:
    """
    Write document to IDF format.

    Args:
        doc: The document to write.
        filepath: Output path (if ``None``, returns a string).
        encoding: Output encoding.
        output_type: Output formatting mode — ``"standard"`` (with
            comments), ``"nocomment"`` (no comments), or
            ``"compressed"`` (single-line objects).  Mirrors eppy's
            ``idf.outputtype``.  Ignored when *preserve_formatting* is
            explicitly ``True``.  When *preserve_formatting* is ``None``
            and *output_type* is not ``"standard"``, the explicit output
            type takes precedence and lossless mode is disabled.
        preserve_formatting: If ``True``, reproduce the original source
            text for unmodified objects and apply standard formatting only
            to objects that were mutated or added after parsing.  Requires
            the document to have been parsed with
            ``preserve_formatting=True``.  When ``None`` (the default),
            automatically uses lossless output if a CST is available and
            *output_type* is ``"standard"``.

    Returns:
        IDF string if *filepath* is ``None``, otherwise ``None``.

    Examples:
        Serialize the model to an IDF string for inspection:

        >>> from idfkit import new_document, write_idf
        >>> model = new_document()
        >>> model.add("Zone", "Perimeter_ZN_1")  # doctest: +ELLIPSIS
        Zone('Perimeter_ZN_1')
        >>> idf_str = write_idf(model)
        >>> "Zone," in idf_str
        True

        Write to disk for EnergyPlus simulation:

            ```python
            write_idf(model, "in.idf")
            ```

        Use compressed format for batch parametric runs:

        >>> compressed = write_idf(model, output_type="compressed")
        >>> "\\n" not in compressed.split("Zone")[1].split(";")[0]
        True

        Lossless round-trip:

            ```python
            from idfkit import load_idf, write_idf
            model = load_idf("building.idf", preserve_formatting=True)
            write_idf(model, "building_copy.idf")  # byte-identical
            ```
    """
    if preserve_formatting is not None:
        use_preserve = preserve_formatting
    elif output_type != "standard":
        use_preserve = False
    else:
        use_preserve = doc.cst is not None

    if use_preserve and doc.cst is not None:
        content = _write_idf_lossless(doc)
    else:
        writer = IDFWriter(doc, output_type=output_type)
        content = writer.to_string()

    if filepath:
        filepath = Path(filepath)
        with open(filepath, "w", encoding=encoding) as f:
            f.write(content)
        logger.info("Wrote IDF (%d objects) to %s", len(doc), filepath)
        return None

    logger.debug("Serialized IDF (%d objects) to string", len(doc))
    return content