idfkit 1.2.0__tar.gz → 1.3.0rc1__tar.gz

idfkit-1.3.0rc1/.github/workflows/check-identity.yml

@@ -0,0 +1,12 @@
+name: Identity
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  identity:
+    uses: idfkit/idfkit-brand/.github/workflows/check-touchpoint.yml@identity-2026.5
+    with:
+      identity_level: identity-2026.5

{idfkit-1.2.0 → idfkit-1.3.0rc1}/.github/workflows/conformance.yml

@@ -68,7 +68,7 @@ jobs:
 
       - name: Set up the environment
         # 3.11 is the floor the corpus runner needs: it reads case files with tomllib, which is
-        # standard library only from 3.11. The library itself is tested across 3.10 to 3.13 in
+        # standard library only from 3.11. The library itself is tested across 3.10 to 3.14 in
         # main.yml; this job is about the corpus, not about the supported interpreter range.
         uses: ./.github/actions/setup-python-env
         with:

{idfkit-1.2.0 → idfkit-1.3.0rc1}/.github/workflows/main.yml

@@ -35,7 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
     defaults:
       run:
@@ -62,6 +62,54 @@ jobs:
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
+  tests-free-threaded:
+    # The suite on free-threaded CPython with the GIL off. The core is pure Python and declares
+    # the Free Threading classifier on the strength of this job, and tests/test_thread_safety.py
+    # reproduces races only here: on a GIL build most of them cannot happen.
+    name: "tests (3.14t, GIL off)"
+    runs-on: ubuntu-latest
+    # A lock regression shows up as a deadlock. The race tests fail on their own deadline, but this
+    # caps whatever they miss well short of GitHub's six-hour default.
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: "3.14t"
+
+      # A `3.14t` request that resolved to a GIL build would pass every test below while proving
+      # nothing, so fail loudly first. The import check runs WITHOUT PYTHON_GIL=0: an interpreter
+      # re-enables the GIL when it imports an extension module that does not declare support, and
+      # that override would hide such a module. idfkit and all of its sub-packages must keep it
+      # off on their own.
+      - name: Check the interpreter is free-threaded and idfkit keeps the GIL off
+        run: |
+          uv run python - <<'EOF'
+          import importlib, pkgutil, sys, sysconfig
+          assert sysconfig.get_config_var("Py_GIL_DISABLED"), f"not a free-threaded build: {sys.version}"
+          import idfkit
+          # walk_packages yields each package before importing it, so the import below is the first and
+          # raises on any failure: no `onerror` is needed for a broken package to fail this step.
+          for mod in pkgutil.walk_packages(idfkit.__path__, "idfkit."):
+              if ".codegen" not in mod.name:
+                  importlib.import_module(mod.name)
+          assert not sys._is_gil_enabled(), "importing idfkit re-enabled the GIL"
+          print(sys.version, "- GIL off after importing every idfkit module")
+          EOF
+
+      # PYTHON_GIL=0 because the locked pandas (2.3) re-enables the GIL at import; pandas 3 does
+      # not. The override keeps the whole run, the pandas tests included, genuinely GIL-free.
+      - name: Run tests
+        env:
+          PYTHON_GIL: "0"
+        run: uv run python -m pytest -W error::DeprecationWarning
+
   example-sweep:
     # Read every EnergyPlus example file, for every version idfkit bundles a schema for.
     #

{idfkit-1.2.0 → idfkit-1.3.0rc1}/.github/workflows/rehearse-all.yml

@@ -14,6 +14,9 @@ name: Rehearse a candidate against every consumer
 # consumer's pull requests, it cannot block any consumer's unrelated work (FR-013).
 #
 # A dispatch that does not land fails this run. A rehearsal that reached nobody is not a rehearsal.
+# This run then waits for every rehearsal to conclude and fails if any one fails or times out, so a
+# candidate that breaks a consumer is red here as well. The job timeout covers the consumers' own
+# 45-minute rehearsal jobs.
 on:
   workflow_dispatch:
     inputs:
@@ -28,7 +31,7 @@ permissions:
 jobs:
   rehearse:
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 60
     steps:
       - name: Check out this repository for its governance pin
         uses: actions/checkout@v4

{idfkit-1.2.0 → idfkit-1.3.0rc1}/CHANGELOG.md

@@ -7,6 +7,242 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0-rc.1] - 2026-11-14
+
+### Added
+
+- The README opens with the idfkit identity header at `identity-2026.5`: the mark, the
+  repository's one sentence, the family links and the badge row. The `Identity` workflow
+  (`.github/workflows/check-identity.yml`) holds the header to that tag on every pull request.
+- A field whose epJSON key ends in `_` could be given without the underscore, in `add()`,
+  attribute access, `update()` and the eppy helpers: `cond_flag_is_the_basement_conditioned="FALSE"`
+  set `GroundHeatTransfer:Basement:Interior.cond_flag_is_the_basement_conditioned_`, and the value
+  was stored and written under the schema's key. The underscore comes from IDD names that end in
+  punctuation or a space, and EnergyPlus has started dropping it: `WindowShadingControl`'s
+  `construction_with_shading_name_` in 9.0.1 and 9.1.0 is `construction_with_shading_name` from
+  9.2.0, and the one spelling worked on both. `name` was never such a spelling. `add()` refused a
+  call that gave both spellings of one field, even with one of them blank. The typed `update()`
+  stubs name only the schema's key. ([60c47cc](https://github.com/idfkit/idfkit/commit/60c47cc),
+  [9b208de](https://github.com/idfkit/idfkit/commit/9b208de))
+- Python 3.14 became a supported version: CI runs the test suite and type check on it, and the package declares the 3.14 classifier ([#253](https://github.com/idfkit/idfkit/pull/253)).
+- Free-threaded CPython 3.14 (`python3.14t`, GIL disabled) became a tested build: a CI job runs the test suite on it with the GIL off and fails if importing any idfkit module re-enables the GIL, and the package declares the `Free Threading :: 2 - Beta` classifier. The threading contract is now stated in the bundled agent references (`threading.md`): the schema manager and module-level caches are safe from any number of threads, separate documents are independent, and one document may be read from many threads but must not be mutated by several at once. Of the optional extras, only `pandas` before 3.0 re-enables the GIL on import. `benchmarks/bench_free_threading.py` measures thread scaling: on 4 CPUs, four threads parse IDF files 2.6 times faster than one thread on the regular build, and other workloads gain 1.0 to 1.6 times ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `idfkit.weather.designday.sanitize_ddy_bytes()`, the in-memory form of `sanitize_ddy_file()`, which blanks placeholder values in DDY content before it is written anywhere ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- **A document became typeable for the EnergyPlus release it was written for, not only the
+  latest one.** `idfkit.versioned` gained one type per supported release,
+  `IDFDocumentV<major>_<minor>` from `IDFDocumentV8_9` to `IDFDocumentV26_2` (which is
+  `IDFDocument`), and `as_version(doc, IDFDocumentV9_4)`, which returns the document under that
+  type after checking its release at run time. Given a tuple of those types, as `isinstance`
+  takes one, `as_version` accepts a document of any of them and types it as their union (mypy reduces
+  the union to what those releases share), which
+  narrows a model of unknown release into a range such as the releases that have `Space`. Such a document is indexed, completed and checked
+  with that release's object types, field value types and choices, accessors and `update()`
+  keywords: on a 9.4 model `doc["Space"]` is a type error and `People` has
+  `zone_or_zonelist_name`. Documents stay typed for the latest release unless their version is
+  stated this way. The stubs encode each object type's declaration once per contiguous range of
+  releases that share it, and `python -m idfkit.codegen.generate_stubs` now checks what it wrote
+  against every bundled schema before finishing, so adopting a release needs no hand edit of
+  the stubs, and a regeneration that would misdescribe a release fails ([#194](https://github.com/idfkit/idfkit/issues/194), [#251](https://github.com/idfkit/idfkit/pull/251)).
+- `AnyIDFDocument` (in `idfkit.versioned` and `idfkit.document`) was added. It accepts a
+  document of any supported release and, through it, offers what every release has: the object
+  types present in all of them. A field whose value type changed between releases reads as any
+  release's value and, through assignment and `update()`, accepts only a value every release
+  accepts: `heater_fuel_type` can be set to `"NaturalGas"` but not to `"DistrictHeatingWater"`,
+  which 9.3 to 23.1 reject. idfkit's own
+  functions were retyped to take it, so `save_idf`, `simulate`, the geometry and zoning helpers
+  and the rest accept a document typed for any release; `expand_objects` and the ground
+  heat-transfer preprocessors return the type they were given. An object type or accessor that
+  some release lacks is reported against the type that lacks it, for example
+  `"Space" is not a defined key in "IDFDocumentV9_4[bool]"`, and through `AnyIDFDocument` as
+  `"Space" is not a defined key in "IDFDocumentAllVersions[bool]"`. Naming one release's type costs
+  pyright about what naming `IDFDocument` does, 2 to 3 seconds for a file; a file naming every
+  release's type takes about 7 seconds
+  ([#194](https://github.com/idfkit/idfkit/issues/194), [#251](https://github.com/idfkit/idfkit/pull/251)).
+- Every object type of the latest release gained an `Any<Class>` type, importable from `idfkit.document` inside
+  `if TYPE_CHECKING:`, for annotating code that takes an object of any supported release:
+  `def floor_area(zone: AnyZone)` accepts a latest-release zone, a 9.4 zone and a zone reached
+  through `AnyIDFDocument`, where `Zone` accepts only the first. Through it, fields follow the
+  `AnyIDFDocument` rules, extensible groups included, so `AnyBuildingSurfaceDetailed.vertices` is
+  typed. For a type no release changed, `Any<Class>` is the latest class itself (`AnyZoneList` is
+  `ZoneList`). For a type that arrived after 8.9, it covers the releases that have it:
+  `AnySpace` accepts a `Space` of any release from 9.6, and its docstring says so. A type that
+  a release before the latest removed, such as `DistrictHeating`, has none: its classes are
+  named for the releases that have it (`DistrictHeating_v8_9_to_v23_1`). `Any<Class>` covers the
+  releases idfkit supports, so adopting a release that drops or renames a field removes that
+  field from it
+  ([#194](https://github.com/idfkit/idfkit/issues/194), [#251](https://github.com/idfkit/idfkit/pull/251)).
+
+### Changed
+
+- **Breaking:** for type checking only, an undeclared field name on a typed object is now a type
+  error. `material.thermal_resistance = 1.0` on a `Material` taken from `doc["Material"]`, or
+  `print(material.bogus)`, used to type-check clean because the catch-all `__getattr__` and
+  `__setattr__` of `IDFObject` accepted any name. pyright reports the name whether it is read or
+  assigned; mypy reports an assignment, and types a read as `object`, so it reports any use that
+  needs a more specific type.
+  The same holds for the groups of an extensible type, such as `surface.vertices[0]`. Typed objects
+  declare snake_case names only, so an eppy-style capitalised spelling such as
+  `material.Thickness = 0.2` is now reported too, although it still works at run time: use
+  `material.thickness`. The typed classes describe EnergyPlus 26.2, so a field name that only exists
+  in an earlier version, such as `Lights.watts_per_zone_floor_area` up to 23.2, is reported as well;
+  on such a model, reach it with item access (`lights["watts_per_zone_floor_area"]`) or `getattr`.
+  Objects from the eppy API (`doc.idfobjects[...]`, `newidfobject()`, `getobject()`) and other plain
+  `IDFObject`s, such as those from `doc.add()` or `doc.get_collection()`, stay permissive. Declared
+  fields, `name`, the spellings of trailing-underscore fields with and without the underscore, and
+  wrong-type errors behave as before. Run-time behaviour is unchanged. ([#272](https://github.com/idfkit/idfkit/pull/272))
+
+- **Breaking:** `IDFDocument.add()` raised `InvalidFieldError` when given a non-empty name for a
+  type without a Name field, such as `Output:Meter`, `Output:Variable`, `Output:SQLite`,
+  `Timestep` or `SimulationControl` (165 of the 880 types in the 26.2 schema), whether or not
+  `validate` is set. The name used to be stored and then dropped by both writers, so
+  `add("Output:SQLite", "SimpleAndTabular")` wrote `Output:SQLite,` and EnergyPlus produced no
+  `.sql` file. The message names the field to pass instead (`key_name="Electricity:Facility"`
+  for `Output:Meter`, `option_type=...` for `Output:SQLite`); the value is never moved there for
+  you. The same rule applies to `obj.name = ...` and to `newidfobject`, `addidfobject` and
+  `copyidfobject(..., new_name=...)`. Loading existing IDF and epJSON files is unaffected.
+  ([11ac720](https://github.com/idfkit/idfkit/commit/11ac720))
+- **Breaking:** `IDFDocument.add()` refused a key that is not a field of the object type even
+  with `validate=False`, raising `InvalidFieldError` that names every such key, whatever its
+  value. `validate=False` used to skip schema validation entirely, so the key was stored, then
+  silently dropped by `write_idf()` and written as an unknown property by `write_epjson()`. It
+  still skips value, required-field and range checks. The object's name belongs in the `name`
+  argument, not in `fields`; display spellings such as `"X Origin"` are refused with the field
+  to use instead; and `FenestrationSurface:Detailed` takes its fixed `vertex_N_x_coordinate`
+  fields, not a `vertices` list. ([1fe5171](https://github.com/idfkit/idfkit/commit/1fe5171),
+  [b415635](https://github.com/idfkit/idfkit/commit/b415635))
+- **Breaking:** `IDFDocument.add()` checked the extensible groups it was given in either
+  validate mode, as `IDFObject.update()` already did, and raised `TypeError` for a group key the
+  group does not name (`reports=[{"report_nme": ...}]`) or a wrapper value that is not a list of
+  groups (a string, a list of strings or tuples, or another object's live `vertices` view).
+  Validation never looked inside the groups, so these were stored, and `write_idf()` dropped the
+  values or crashed. ([b415635](https://github.com/idfkit/idfkit/commit/b415635))
+- `IDFCollection` became covariant in its object type, so `IDFCollection[Zone]` is accepted
+  where `IDFCollection[IDFObject]` is expected. `IDFCollection.remove` now takes any `IDFObject`,
+  and `get(name, default)` returns the object type or the default's type. The usual cost of
+  covariance came with it: a function that takes `IDFCollection[IDFObject]` can `add()` an object of
+  another type to the collection it is given, such as a `Material` to `doc["Zone"]`, without a type
+  error, and `add()` does not check it at run time
+  ([#194](https://github.com/idfkit/idfkit/issues/194), [#251](https://github.com/idfkit/idfkit/pull/251)).
+
+### Removed
+
+- **Breaking:** `SchemaManager.get_schema` is no longer wrapped in `functools.lru_cache`, so `get_schema.cache_clear()`, `get_schema.cache_info()` and `get_schema.cache_parameters()` are gone. The manager's own cache already held every loaded version; call `SchemaManager.clear_cache()` to drop it ([#254](https://github.com/idfkit/idfkit/pull/254)).
+
+### Fixed
+
+- The bundled agent references described the changes above wrongly or not at all. The HVAC loops
+  reference still called `validate_document` and `get_referencing` the safety net for node wiring,
+  though neither sees node names, and offered renaming a coil as a fix for a mismatched node name.
+  The references now say that typed objects accept only 26.2 snake_case field names, that an empty
+  group-only object such as `Output:Table:SummaryReports` is written to IDF as `Type,;`, and that
+  `prep_outputs` also requests the `AllSummary` tabular report.
+  ([2399407](https://github.com/idfkit/idfkit/commit/2399407))
+- `EpJSONSchema.get_field_names()` dropped the first field of every type, including types without
+  a Name field, whose first field is an ordinary one: `get_field_names("Output:Meter")` was
+  `['reporting_frequency']`. It now drops the first field only for a named type. As a result
+  `describe_object_type()` (and `IDFDocument.describe()`) lists `key_name` for `Output:Meter`,
+  and the generated `OutputMeter` class and its `update()` keywords include it; the same holds
+  for every other nameless type. Validation no longer counts a name stored on a nameless object
+  as a declared name. ([11ac720](https://github.com/idfkit/idfkit/commit/11ac720))
+- Fixed fields whose names look like a flat spelling of the type's own extensible group were
+  treated as that group's fields. This affected `MaterialProperty:GlazingSpectralData`
+  (`wavelength_1` … `back_reflectance_4`), `Site:SpectrumData` (`wavelength`, `spectrum`,
+  `wavelength_1`, `spectrum_2`), `ZoneHVAC:HybridUnitaryHVAC` (`mode_0_*`) and, in EnergyPlus 8.9
+  to 9.1, `Table:MultiVariableLookup` (`field_1_…` and `field_2_…`). `add()` moved these values
+  into the extensible groups with a deprecation warning, or raised `ValueError` ("cannot mix") when
+  the groups were passed too. `load_epjson()` moved them silently, after any groups already in the
+  file. Either way `write_idf` wrote the fixed fields blank and the values out of place. On
+  `Site:SpectrumData`, `wavelength_1` overwrote `wavelength`. Attribute assignment stored the
+  value in a group (for `mode_0_*`, the last mode), attribute reads of an unset field returned a
+  group's value, and `update()` refused the field as a legacy flat name. These fields are now
+  kept as fixed fields.
+  ([cee2d7c](https://github.com/idfkit/idfkit/commit/cee2d7c))
+- A field whose epJSON name ends in `_` was out of reach by attribute: assigning it or passing it
+  to `update()` raised `InvalidFieldError`, and so did reading it unset in a strict document,
+  because the trailing underscore was stripped into a name the type does not have. In a document
+  opened with `strict=False`, the assignment was stored under that name instead, and `write_idf()`
+  dropped it. 24 such fields exist across the bundled schemas, among them
+  `GroundHeatTransfer:Basement:Interior.cond_flag_is_the_basement_conditioned_`,
+  `GroundHeatTransfer:Basement:ManualGrid.nx_number_of_cells_in_the_x_direction_20_` and
+  `SizingPeriod:DesignDay.ashrae_clear_sky_optical_depth_for_beam_irradiance_taub_`; `add()`
+  already accepted them. `update()` also refused `Output:Table:ReportPeriod.name_` as the
+  object's name. The eppy-style dotted `IDFDocument.update()`, `get_referenced_object()`,
+  `getrange()`, `checkrange()` and `getreferingobjs(fields=...)` missed them the same way.
+  ([a520960](https://github.com/idfkit/idfkit/commit/a520960),
+  [9b208de](https://github.com/idfkit/idfkit/commit/9b208de))
+- A flat extensible name with group number 0, such as `vertex_0_x_coordinate` or
+  `mode_0_minimum_outdoor_air_temperature`, was read as the last group: assignment overwrote the
+  last group's value, or raised `IndexError` when there were no groups, and `add()` inserted it
+  as a new first group. Group numbers now start at 1, so such a name is an unknown field.
+  ([da8a613](https://github.com/idfkit/idfkit/commit/da8a613))
+- `write_idf` and `save_idf` wrote an object with nothing in it without its terminating `;`, so it
+  swallowed the object after it, and EnergyPlus read that object's type name and values as fields
+  of the empty one. This happened to a nameless type with no fixed fields
+  (`Output:Table:SummaryReports`, `Output:Diagnostics`, `OutdoorAir:NodeList`,
+  `EnergyManagementSystem:GlobalVariable` and the six `GroundHeatTransfer` face types) when it held
+  no groups. It affected the standard and `nocomment` output types, `doc.copy()`, and objects
+  added to a document loaded with `preserve_formatting=True`. Such an object is now written with
+  one blank field, `Output:Diagnostics,;`, which keeps the next object intact. IDF has no spelling
+  that EnergyPlus reads as one of these objects with nothing in it: `Output:Diagnostics;` swallows
+  the next object too, and EnergyPlus reads `Output:Diagnostics,;` as one blank group. That gives a
+  warning for `Output:Diagnostics` and a Severe error for `Output:Table:SummaryReports`, and
+  EnergyPlus refuses the input for `OutdoorAir:NodeList` and
+  `EnergyManagementSystem:GlobalVariable`. Remove such an object, or write the model as epJSON, to
+  keep it empty. ([3e3e772](https://github.com/idfkit/idfkit/commit/3e3e772),
+  [0dcfdd3](https://github.com/idfkit/idfkit/commit/0dcfdd3))
+- Strict IDF parsing no longer rejects blank fields past the last field of a type without
+  repeated groups, such as `Timestep,4,,;` or `GroundHeatTransfer:Slab:XFACE,;`; EnergyPlus accepts
+  them too. A non-blank extra value is still an error, and the error counts only the values up to
+  the last non-blank one. ([3e3e772](https://github.com/idfkit/idfkit/commit/3e3e772),
+  [0dcfdd3](https://github.com/idfkit/idfkit/commit/0dcfdd3))
+- `write_idf` dropped the name and every field of an object whose type was spelled in a different
+  case from the schema, such as one added with `addidfobject(IDFObject(obj_type="TIMESTEP", ...))`,
+  and of an object of a type the schema does not know. Both are now written with their values.
+  ([0dcfdd3](https://github.com/idfkit/idfkit/commit/0dcfdd3))
+- **Breaking:** Validation reported unknown fields (`W003`) on extensible object types too, and
+  on unknown fields with a blank value. Extensible types used to be exempt, so
+  `doc.add("Output:Table:SummaryReports", "", report_1="AllSummary")` passed the default
+  `validate=True` and stored a key that `write_idf()` silently dropped and `write_epjson()`
+  emitted as an unknown property. Such a call now raises `ValidationFailedError`, as an unknown
+  field on a non-extensible type already did; the wrapper list (`reports=[...]`) and the
+  deprecated flat spellings (`report_name`, `report_name_2`) are still accepted.
+  `validate_document()` reports the same keys on objects loaded from epJSON.
+  ([459258f](https://github.com/idfkit/idfkit/commit/459258f), [b415635](https://github.com/idfkit/idfkit/commit/b415635))
+- `prep_outputs()` requested the `AllSummary` tabular report, which it never had. It passed
+  `report_1`, a spelling `Output:Table:SummaryReports` does not have, so `write_idf()` wrote the object with
+  no fields and no terminator, and EnergyPlus read the next object into it and stopped with a
+  fatal error. ([381c12f](https://github.com/idfkit/idfkit/commit/381c12f),
+  [1fe5171](https://github.com/idfkit/idfkit/commit/1fe5171))
+- `OutputVariableIndex.add_all_to_model` stored each meter name in the `key_name` field of the
+  `Output:Meter` objects it adds. It used to pass the name as the object name, which
+  `Output:Meter` does not have, so both writers dropped it: `write_idf` emitted
+  `Output:Meter,,Timestep;` and EnergyPlus stopped with `Missing required property 'key_name'`.
+  The added meters now have an empty name, like meters loaded from a file, so
+  `doc["Output:Meter"]["<meter>"]` no longer finds them, and calling `add_all_to_model` twice
+  adds each meter twice instead of raising `DuplicateObjectError`
+  ([d214b51](https://github.com/idfkit/idfkit/commit/d214b51)).
+- `IDFCollection.remove` (and so `IDFDocument.removeidfobject`) removed the first object equal
+  to the one passed instead of that object. Two objects of a type with no Name field are equal
+  when their fields match, so removing one `Output:Meter` could remove another and leave the
+  one passed in the document ([c6514d0](https://github.com/idfkit/idfkit/commit/c6514d0)).
+- The `hvac-loops` and `reference-tracking` agent references no longer state that
+  `validate_document` reports node-name typos. It reports a dangling object-name reference as
+  `E009`, not `E004`, and does not check node names at all. They also no longer list setpoint
+  managers among the objects `get_referencing` returns for a coil, and the node walk under
+  "Common mistakes" now finds a node in any field, including branch components and outdoor-air
+  mixer streams, so it no longer fails on correct models such as `5ZoneAirCooled`.
+- Threads asking for the same schema version at the same moment each loaded and built their own copy, so a cold start with 16 threads read the schema file 16 times and handed out 16 different `EpJSONSchema` instances. All but one were then pickled by content instead of by version. The manager now loads each version once and gives every thread the same instance, and on a free-threaded build the first calls to `get_schema_manager()` no longer create several managers ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `ScheduleFileCache.get_values` could raise `KeyError` when another thread cleared or invalidated the cache between its store and its read, and `ScheduleFileCache.invalidate` could raise `RuntimeError: dictionary changed size during iteration` when another thread added an entry while it ran. A read still in flight when another thread called `invalidate` or `clear` also cached what it had read before the call, which silently undid the invalidation; such a read is now returned but not cached ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `SchemaManager.clear_cache` did not stop a load already in flight from caching its schema afterwards, so the clear was undone and a request made after it could be handed the pre-clear instance. Such a load now returns its schema to its caller without caching it. A logging handler or other code that asks for the version being loaded no longer deadlocks on the new load lock ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `copy.deepcopy` of a `ScheduleFileCache` or `SchemaManager` that other threads were using could raise `RuntimeError: dictionary changed size during iteration`, and `copy.copy` of a cache returned an alias that shared its entries but not its invalidations. Both now copy a consistent snapshot into an independent object, and instances pickled by idfkit 1.2.0 still load and work ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `ScheduleFileCache.invalidate` discarded every read in flight, of any file, so a steady stream of invalidations of one file stopped the cache caching the others. It now discards only reads of the file it invalidates. A child forked while another thread was inside `invalidate` or `clear` no longer inherits a half-invalidated cache ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- The weather cache is now safe to share between threads and processes. `WeatherDownloader.download` wrote the archive, the extracted files and the cleaned DDY in place, so callers downloading the same station at once could read a truncated file or raise "Downloaded file is not a valid ZIP archive", and a truncated file could stay in the cache for good; `StationIndex.refresh()` likewise rewrote `stations.json.gz` and its KML sources in place, so a concurrent `StationIndex.load()` raised `EOFError` or moved the half-written index aside. Every weather cache file, the IP-location cache and downloaded schemas are now written under a temporary name and renamed into place, with the permissions an in-place write would have given them. Extracted files carry their archive's modification time and size, so a file left truncated by an older version, or extracted from an archive that has since been replaced, is extracted again, and a corrupt archive is downloaded again on the next call. Threads of one process download a station once. Files inside folders of an archive, such as macOS `__MACOSX` resource forks, are no longer extracted beside the weather files ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- A child process forked while another thread was waiting out the geocoding rate limit hung on its first `geocode()` or `detect_location()` call ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `simulate` computed the cache key from the caller's model before copying it, so an edit made on another thread in between could store one model's results under another model's key. `async_simulate` read the caller's model on a worker thread after copying it, which raised on a free-threaded build when another coroutine edited the model meanwhile. Both now work only from their copy ([#254](https://github.com/idfkit/idfkit/pull/254)).
+- `expand_objects`, `IDFDocument.expand` and the ground heat-transfer preprocessors returned a
+  strict document for a model opened with `strict=False` whenever a preprocessor ran; only a model
+  with nothing to expand came back as it was. The result now keeps the model's strictness, as
+  `IDFDocument.copy` does ([#194](https://github.com/idfkit/idfkit/issues/194), [#251](https://github.com/idfkit/idfkit/pull/251)).
+
 ## [1.2.0] - 2026-10-28
 
 This release moves to `conformance-2026.21`. Through `conformance-2026.19`, the level the TypeScript library also declares, the corpus adds five cases for the multi-field `update` shared with the TypeScript library, an `update` operation and a `post-operation-epjson` assertion (`conformance-2026.17`), and removes the divergence entries for those cases in both languages: the ten Python entries that `IDFObject.update` closes (`conformance-2026.18`) and the six TypeScript ones (`conformance-2026.19`). `conformance-2026.20` then removes the two Python round-trip entries that #183 closes. An idfkit release without `IDFObject.update` fails the five update cases at this level, and one that still stores a blank fixed field as `""` fails those two. `conformance-2026.21` removes the three Python entries that #187 closes, so a release that still drops an unterminated final object fails `malformed-truncated-object` and `preserve-unterminated-final`.
@@ -977,7 +1213,8 @@ Initial public release.
 - Performance benchmarks comparing idfkit against eppy and opyplus. ([#5](https://github.com/idfkit/idfkit/pull/5))
 - MkDocs Material documentation site with a full API reference, an eppy migration guide, and a getting-started Jupyter notebook. ([#2](https://github.com/idfkit/idfkit/pull/2))
 
-[Unreleased]: https://github.com/idfkit/idfkit/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/idfkit/idfkit/compare/v1.3.0-rc.1...HEAD
+[1.3.0-rc.1]: https://github.com/idfkit/idfkit/compare/v1.2.0...v1.3.0-rc.1
 [1.2.0]: https://github.com/idfkit/idfkit/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/idfkit/idfkit/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/idfkit/idfkit/compare/v1.0.0...v1.1.0

{idfkit-1.2.0 → idfkit-1.3.0rc1}/CLAUDE.md

@@ -14,12 +14,14 @@ Key capabilities: IDF/epJSON parsing and writing, schema-driven validation, 3D g
 
 The core package — including simulation, schedules, thermal, and geometry — has **zero third-party dependencies** (stdlib only). Optional extras (defined in `pyproject.toml`):
 
-- `weather` — openpyxl (for station index refresh; bundled index works without it)
-- `pandas` / `dataframes` — pandas (for DataFrame result conversion)
+- `sim` — empty; simulation needs no extras
+- `pandas` — pandas (for DataFrame result conversion); `dataframes` is an alias
 - `plot` — matplotlib | `plotly` — plotly (plotting backends)
 - `progress` — tqdm (simulation progress bars)
-- `s3` / `async-s3` / `cloud` — boto3 / aiobotocore (cloud storage)
-- `all` — everything above
+- `s3` — boto3 (`cloud` is an alias) | `async-s3` — aiobotocore (cloud storage)
+- `all` — pandas, matplotlib, plotly, boto3, aiobotocore and tqdm
+
+There is no `weather` extra: weather search, download and station-index refresh are stdlib only.
 
 ## Common Commands
 

{idfkit-1.2.0 → idfkit-1.3.0rc1}/Makefile

@@ -12,7 +12,7 @@ install: ## Install the virtual environment and install the pre-commit hooks
 check-stubs: ## Verify generated type stubs are up-to-date
 	@echo "🚀 Checking type stub consistency"
 	@uv run python -m idfkit.codegen.generate_stubs
-	@git diff --exit-code src/idfkit/_generated_types.pyi src/idfkit/document.pyi || \
+	@git diff --exit-code src/idfkit/_generated_types.pyi src/idfkit/document.pyi src/idfkit/versioned.pyi src/idfkit/versioned.py || \
 		(echo "❌ Generated stubs are out of date. Run: uv run python -m idfkit.codegen.generate_stubs" && exit 1)
 
 .PHONY: check-conformance-level
@@ -99,7 +99,7 @@ test: ## Test the code with pytest
 	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
 
 .PHONY: weather-index
-weather-index: ## Rebuild the bundled weather station index (requires network + openpyxl)
+weather-index: ## Rebuild the bundled weather station index (requires network; standard library only)
 	@echo "🚀 Building weather station index"
 	@uv run python scripts/build_weather_index.py
 

{idfkit-1.2.0 → idfkit-1.3.0rc1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: idfkit
-Version: 1.2.0
+Version: 1.3.0rc1
 Summary: A fast, modern EnergyPlus IDF/epJSON parser with O(1) lookups and reference tracking
-Project-URL: Homepage, https://py.idfkit.com/
+Project-URL: Homepage, https://developers.idfkit.com/
 Project-URL: Repository, https://github.com/idfkit/idfkit
-Project-URL: Documentation, https://py.idfkit.com/
+Project-URL: Documentation, https://developers.idfkit.com/
 Author-email: Samuel Letellier-Duchesne <developers@idfkit.com>
 License-File: LICENSE
 Keywords: building simulation,energy modeling,energyplus,epjson,idf,parser
@@ -18,6 +18,8 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -48,12 +50,21 @@ Requires-Dist: boto3>=1.26; extra == 's3'
 Provides-Extra: sim
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/idfkit/idfkit-brand/identity-2026.5/marks/mark-on-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/idfkit/idfkit-brand/identity-2026.5/marks/mark-on-light.svg">
+    <img alt="idfkit" width="72" src="https://raw.githubusercontent.com/idfkit/idfkit-brand/identity-2026.5/marks/tile.png">
+  </picture>
+</p>
+
 # idfkit
 
-[![Release](https://img.shields.io/github/v/release/idfkit/idfkit)](https://github.com/idfkit/idfkit/releases)
-[![Build status](https://img.shields.io/github/actions/workflow/status/idfkit/idfkit/main.yml?branch=main)](https://github.com/idfkit/idfkit/actions/workflows/main.yml?query=branch%3Amain)
-[![codecov](https://codecov.io/gh/idfkit/idfkit/branch/main/graph/badge.svg)](https://codecov.io/gh/idfkit/idfkit)
-[![License](https://img.shields.io/github/license/idfkit/idfkit)](https://github.com/idfkit/idfkit/blob/main/LICENSE)
+An EnergyPlus IDF and epJSON toolkit for Python, with no third-party dependencies.
+
+[idfkit](https://idfkit.com) · [Developers](https://developers.idfkit.com) · [EnergyPlus docs](https://docs.idfkit.com) · [Envelop](https://app.idfkit.com) · [MCP](https://mcp.idfkit.com) · [Shoebox](https://shoebox.idfkit.com) · [GitHub](https://github.com/idfkit)
+
+[![Release](https://img.shields.io/github/v/release/idfkit/idfkit)](https://github.com/idfkit/idfkit/releases) [![Build status](https://img.shields.io/github/actions/workflow/status/idfkit/idfkit/main.yml?branch=main)](https://github.com/idfkit/idfkit/actions/workflows/main.yml?query=branch%3Amain) [![codecov](https://codecov.io/gh/idfkit/idfkit/branch/main/graph/badge.svg)](https://codecov.io/gh/idfkit/idfkit) [![License](https://img.shields.io/github/license/idfkit/idfkit)](https://github.com/idfkit/idfkit/blob/main/LICENSE) [![Capability parity](https://img.shields.io/badge/capability-parity-informational)](https://developers.idfkit.com/explanation/parity/)
 
 **A fast, modern EnergyPlus IDF/epJSON toolkit for Python.**
 
@@ -64,9 +75,9 @@ Description-Content-Type: text/markdown
 >
 > Code that still calls `write_*` with a path fails without naming the cause:
 > `write_epjson(doc, path)` raises `TypeError: can't multiply sequence by
-> non-int of type 'PosixPath'`, and `write_idf(doc, path)` writes nothing,
-> leaving an empty file that surfaces later as
-> `Could not detect EnergyPlus version in file`.
+> non-int of type 'PosixPath'`, and `write_idf(doc, path)` takes the path as
+> its `output_type` argument, returns the IDF text, and writes no file, so the
+> failure surfaces only when the file is next read.
 >
 > Search for `write_idf(` and `write_epjson(` called with two positional
 > arguments, or run a type checker, which rejects both. Full notes are in the
@@ -115,8 +126,8 @@ formats.
 
 ## Performance
 
-idfkit is designed from the ground up for speed. On a **1,700-object IDF**,
-looking up a single object by name is **over 3000x faster** than eppy and opyplus
+idfkit is designed from the ground up for speed. On a **1,700-object IDF**
+(Darwin arm64, median of 5 runs), looking up a single object by name is **over 2,000x** faster than eppy, **over 3,500x** faster than opyplus, and **over 130x** faster than energyplus-idd-idf-utilities
 thanks to O(1) dict-based indexing:
 
 <picture>
@@ -127,6 +138,7 @@ thanks to O(1) dict-based indexing:
 
 See [full benchmark results](https://developers.idfkit.com/benchmarks/)
 for all six operations (load, get by type, get by name, add, modify, write) across four tools.
+energyplus-idd-idf-utilities is measured on four of them (load, get by type, get by name, write).
 
 ## Installation
 
@@ -146,13 +158,16 @@ uv add idfkit
 
 | Extra | Install command | What it adds |
 |-------|----------------|--------------|
-| `weather` | `pip install idfkit[weather]` | Refresh weather station indexes from source (openpyxl) |
-| `dataframes` | `pip install idfkit[dataframes]` | DataFrame result conversion (pandas) |
+| `sim` | `pip install idfkit[sim]` | Nothing; simulation requires no extra packages |
+| `pandas` | `pip install idfkit[pandas]` | DataFrame result conversion (pandas) |
+| `dataframes` | `pip install idfkit[dataframes]` | Alias of `pandas` |
 | `s3` | `pip install idfkit[s3]` | S3 cloud storage backend (boto3) |
+| `async-s3` | `pip install idfkit[async-s3]` | Asynchronous S3 storage backend (aiobotocore) |
+| `cloud` | `pip install idfkit[cloud]` | Alias of `s3` |
 | `plot` | `pip install idfkit[plot]` | Matplotlib plotting |
 | `plotly` | `pip install idfkit[plotly]` | Plotly interactive charts |
 | `progress` | `pip install idfkit[progress]` | tqdm progress bars for simulations |
-| `all` | `pip install idfkit[all]` | Everything above |
+| `all` | `pip install idfkit[all]` | pandas, matplotlib, plotly, boto3, aiobotocore, and tqdm |
 
 ## Quick Example
 
@@ -177,9 +192,11 @@ for obj in doc.get_referencing("Office"):
 save_idf(doc, "out.idf")
 ```
 
-> **Note:** `load_idf()` defaults to strict parsing (`strict=True`) and raises
-> `IDFParseError` on malformed objects. Use `strict=False` only as a tolerant
-> migration/compatibility fallback for legacy or noisy files.
+> **Note:** `load_idf()` defaults to strict parsing (`strict_parsing=True`) and
+> raises `IDFParseError` on malformed objects. Use `strict_parsing=False` only as a
+> tolerant migration/compatibility fallback for legacy or noisy files. The separate
+> `strict` argument (default `True`) makes reading or setting an unknown field name
+> on an object raise `InvalidFieldError` instead of returning `None`.
 
 ### Creating a model from scratch
 
@@ -239,10 +256,12 @@ The two share a vocabulary and are held to a
 that proves they read and write the same files the same way.
 
 They are not equivalent, and this page will not imply that they are. All
-thirteen first-tier capabilities exist in both: parsing, the object model,
+fourteen first-tier capabilities exist in both: parsing, the object model,
 references, writers, schema access, validation, introspection, documentation
 addresses, generated object types, parse diagnostics, the weather station index,
-weather file retrieval, and geocoding. Almost everything else on this page is
+weather file retrieval, geocoding, and the conformance declaration. Three of them
+are recorded as partial on one side: generated object types in Python, and the
+weather station index and weather file retrieval in JavaScript. Almost everything else on this page is
 Python-only today, including running EnergyPlus locally, reading simulation
 results, geometry authoring, zoning, schedules, thermal properties, and
 migration. Some of that is a port not yet done; some of it, such as driving a
@@ -296,7 +315,6 @@ baked into that exact version.
 make install    # Install dependencies and pre-commit hooks
 make check      # Run linting, formatting, and type checks
 make test       # Run tests with coverage
-make docs       # Serve documentation locally
 ```
 
 ## Contributing