Type-Safe Development¶

idfkit ships auto-generated type stubs for all 858 EnergyPlus object types. Your IDE gets autocomplete, inline documentation, and error detection out of the box — no plugins or configuration needed.

IDE Autocomplete and Inline Docs¶

Every object type has a typed attribute accessor on IDFDocument and typed fields on individual objects. Your IDE will show field names, types (including Literal for enumerated choices), docstrings with units, defaults, and valid ranges.

from idfkit import load_idf

model = load_idf("building.idf")

# Typed accessor — returns IDFCollection[Zone]
zones = model.zones

# O(1) lookup by name — returns Zone (typed IDFObject subclass)
zone = zones["Office"]

# Field access with IDE autocomplete and type info
print(zone.x_origin)  # float | None
print(zone.multiplier)  # int | None

# Subscript access also works
all_zones = model["Zone"]

For example, hovering over zone.ceiling_height in your IDE will show:

(property) ceiling_height: float | Literal["", "Autocalculate"] | None

Strict Field Access¶

By default, accessing a misspelled field name returns None. Enable strict mode to catch typos at runtime with an AttributeError:

from idfkit import new_document

# Enable strict field access on a new document
doc = new_document(strict=True)

zone = doc.add("Zone", "Office")
zone.x_origin = 0.0  # OK — valid field

# zone.x_orgin = 0.0  # AttributeError! Typo caught immediately

# Also available when loading files
# model = load_idf("building.idf", strict_fields=True)
# model = load_epjson("building.epJSON", strict_fields=True)

Function	Parameter
`new_document()`	`strict=True`
`load_idf()`	`strict_fields=True`
`load_epjson()`	`strict_fields=True`

Tip

Strict mode is recommended during development. Disable it when loading third-party IDF files that may contain non-standard fields.

Dynamic Key Access¶

When the object type is a string literal, doc["Zone"] returns a fully typed collection. When the key comes from a variable, use get_collection() to get a safely typed IDFCollection[IDFObject]:

# Literal key — fully typed, IDE knows the return type
zones = model["Zone"]

# Dynamic key — use get_collection() for variable object types
obj_type = "Zone"
collection = model.get_collection(obj_type)  # IDFCollection[IDFObject]

Use doc["Zone"] when you know the type at write time. Use doc.get_collection(obj_type) in generic functions that accept any object type.

Why get_collection()?

Under the hood, doc["Zone"] is typed via a TypedDict with all 858 EnergyPlus object types as literal keys. This gives your type checker exact return types for each key — but TypedDict subscript access requires string literals, so a plain str variable won't type-check. An @overload-based approach was considered but rejected because 858 overloads cause significant performance degradation in pyright. get_collection() is the lightweight escape hatch: it accepts any str and returns the base IDFCollection[IDFObject] type.

Version Availability¶

Type stubs include "Since: X.Y.Z" annotations in docstrings for object types and fields that were introduced after EnergyPlus 8.9.0. This helps you avoid using features that don't exist in your target version:

from idfkit import new_document

doc = new_document(version=(25, 2, 0))

# SpaceHVAC:ZoneReturnMixer was added in EnergyPlus 24.2.0
# IDE docstring shows: "Since: 24.2.0"
mixer = doc.add("SpaceHVAC:ZoneReturnMixer", "Return Mixer 1")
mixer.zone_name = "Office"

Hovering over SpaceHVACZoneReturnMixer in your IDE shows the docstring including "Since: 24.2.0", making it clear which minimum EnergyPlus version is required.