ebus-panel-sim 0.3.2__tar.gz → 0.3.3__tar.gz

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-08-07
+
+### Fixed
+
+- **`stop(graceful=False)` published `$state=lost` but left the root Device still holding `ready`.** The wire and the object disagreed, so anything re-announcing from that object republished `ready` straight over the `lost`. It now goes through the SDK's public `Device.set_state(DeviceState.LOST)` first, mirroring what `Device.stop()` already does for `disconnected`. The flushed publish that follows is deliberately the same retained value a second time: `set_state` uses the ordinary unflushed path, and on the owned path the connection closes immediately behind the call, so only a flushed publish is guaranteed to land. Costs one message at teardown. The observable retained outcome is unchanged (confirmed against a real broker: `p1=lost`); what changes is that it now survives a subsequent re-announce. Two tests pin it, both failing against 0.3.2. Found by [@cayossarian](https://github.com/cayossarian) while building on this code in [#17](https://github.com/electrification-bus/distribution-enclosure-simulator/pull/17).
+
 ## [0.3.2] - 2026-08-07
 
 Metadata-only. No source changes, so the published tree and the public API are identical to 0.3.1; this release exists to get the packaging metadata below onto PyPI, where it only takes effect on a publish.

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/CONTRIBUTING.md

@@ -39,6 +39,20 @@ Pull requests are welcome.
 - **Keep comments to a minimum.** The project style is self-explanatory code, with comments reserved for the non-obvious *why* (a spec quirk, a Homie nuance, a SPAN-variant deviation). Don't add comments that just restate the code.
 - One commit per logical change is fine; we don't require squash or any particular branch naming.
 
+## What "done" means
+
+This package is published to PyPI, and a PyPI upload can never be replaced. So an increment that lands behaviour and leaves its documentation for later is not a smaller version of the change: it is a release whose docs contradict its code, and the correction costs another release. Ship the whole thing.
+
+A change is done when, in the same PR:
+
+- **Prose it invalidates is fixed.** If a change makes a sentence in the README, `DESIGN.md`, `DEVELOPER.md`, or a docstring untrue, that sentence is part of the change. A new option whose README still describes the old single path is not finished.
+- **Types its signatures name are reachable.** A public parameter annotated with a type a caller cannot import from `ebus_panel_sim` forces them to depend on `ebus_sdk` directly, which is what the SDK seam exists to spare them.
+- **It carries its `CHANGELOG.md` entry**, under `[Unreleased]` or a version heading.
+- **New behaviour has a test that fails without it.** Say so in the PR, and say which. A test that passes against the previous commit is not evidence.
+- **Caller obligations are written down where the caller will look.** If correct use requires the caller to do something (wire a callback, set something before connecting, let an event loop turn), a `#` comment in our source does not reach them.
+
+Splitting a change is fine when the parts are genuinely independent, or when a decision is needed that only a maintainer can make. It is not fine as a way to defer the half that needs no decision. If you are unsure which you have, open the PR with the whole thing and let the review split it.
+
 ## Local development
 
 Python >= 3.11 (developed and CI-tested on 3.11 and 3.14), managed with [uv](https://docs.astral.sh/uv/). See [DEVELOPER.md](DEVELOPER.md) for the full guide.

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/DESIGN.md

@@ -17,7 +17,7 @@ The producer builds a `DeviceManifest` (identity plus physics keys per device) a
 
 The enclosure is a Homie root device (`energy.ebus.device.distribution-enclosure`); every circuit, lugs pair, and integrated DER (BESS, PV, EVSE, MID) is a separate child Homie device with `root` and `parent` back-references to the enclosure. Each device's properties are grouped into capability-typed nodes (`info`, `meter`, `switch`, `breaker`, `load-shed`, `pcs`, `connection`, `status`, `door`, `soc`, `shed`, `shed-forecast`, `grid`, `config`, `power-flows`), whose node `$type` is `energy.ebus.capability.<capability>`. A child device therefore publishes under its own topic root, for example `ebus/5/<circuit-id>/switch/relay` and `ebus/5/<bess-id>-mid/grid/islanding-state`.
 
-Placement is declarative. Each `wire/mapping/*.yaml` descriptor says whether its device class is the `root-device` or a `child-of-parent`; `graph_builder` walks the manifest, mappings, and profiles to build the SDK device graph, and the SDK's `Device` owns the `$state` cascade: `graph_builder` wraps each device's node/property build in a `state_transition()` that coalesces the description republish into a single `init` then `ready` cycle, while `Emitter.start()`/`stop()` drive connect and disconnect. A graceful `stop()` publishes only the root's `$state=disconnected` (by Homie's effective-state rule that covers every child); an ungraceful drop leaves the broker LWT to fire `$state=lost`; retained topics are cleared only when `stop(clear_retained=True)` is passed. The vendored `wire/profiles/*.json` are the schema (capabilities, properties, datatypes, units, `$format`, settability); `bag_builder` maps each profile-declared property to a snapshot accessor and fails loud at construction if any declared property has no source.
+Placement is declarative. Each `wire/mapping/*.yaml` descriptor says whether its device class is the `root-device` or a `child-of-parent`; `graph_builder` walks the manifest, mappings, and profiles to build the SDK device graph, and the SDK's `Device` owns the `$state` cascade: `graph_builder` wraps each device's node/property build in a `state_transition()` that coalesces the description republish into a single `init` then `ready` cycle, while `Emitter.start()`/`stop()` drive connect and disconnect. A graceful `stop()` publishes only the root's `$state=disconnected` (by Homie's effective-state rule that covers every child); `stop(graceful=False)` publishes the root's `$state=lost` itself, because the registered LWT cannot deliver it (a will fires only on an *unclean* disconnect, and every teardown path here closes cleanly, deliberately, so an orderly shutdown is not reported as a crash); retained topics are cleared only when `stop(clear_retained=True)` is passed, which is graceful-only, since a producer that died clears nothing. The vendored `wire/profiles/*.json` are the schema (capabilities, properties, datatypes, units, `$format`, settability); `bag_builder` maps each profile-declared property to a snapshot accessor and fails loud at construction if any declared property has no source.
 
 ## Native devices
 

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/DEVELOPER.md

@@ -131,13 +131,12 @@ distribution-enclosure-simulator/
       bag_builder.py           # Snapshot -> PropertyBag translator
       property_bag.py          # Per-tick property values + diff cache
       publisher.py             # Per-tick diff/publish loop
-      lifecycle.py             # $state, $description, /set subscription, LWT
       set_router.py            # Setter registry and /set dispatch
-      wire_paths.py            # Homie topic-template helpers
-      _sdk_seam.py             # Internal seam over ebus_sdk.property
+      _sdk_seam.py             # Internal seam over ebus_sdk (property build, owned-client narrowing, will publish)
       profiles/                # Vendored Homie 5 device profiles (JSON), per device type
       mapping/                 # Vendored mapping descriptors (YAML), per device type
-  tests/                       # pytest suite (asyncio auto; in-process amqtt broker)
+      catalogs/                # Vendored spec capability catalogs (JSON); the wire type contract
+  tests/                       # pytest suite; paho is patched, so no broker and no socket
     conftest.py
     conventions/               # convention tests
     wire/                      # wire-layer tests

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebus-panel-sim
-Version: 0.3.2
+Version: 0.3.3
 Summary: Producer-side Homie publisher with embedded behaviour runtime for the eBus convention
 Project-URL: Homepage, https://ebus.energy
 Project-URL: Repository, https://github.com/electrification-bus/distribution-enclosure-simulator

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/src/ebus_panel_sim/__init__.py

@@ -69,7 +69,7 @@ from ebus_panel_sim.wire.set_router import SetterHandler, SetterRegistry
 # via `[tool.hatch.version]`, and publish.yml refuses to release when the git tag
 # disagrees. Bump it in this one place. Note this is the PACKAGE version and is
 # distinct from the producer-contract version the docstrings above refer to.
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
     "BESSConfig",

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/src/ebus_panel_sim/wire/_sdk_seam.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import Any
 
 import ebus_sdk
-from ebus_sdk import EBUS_HOMIE_MQTT_QOS, MqttClient, PropertyDatatype, Unit
+from ebus_sdk import EBUS_HOMIE_MQTT_QOS, DeviceState, MqttClient, PropertyDatatype, Unit
 
 
 def make_property(
@@ -74,12 +74,26 @@ def publish_will_now(root: ebus_sdk.Device) -> bool:
     delivered by the broker from its own state, whereas this goes out over a live
     connection that is about to close and has to actually land first.
 
+    ``set_state`` moves the root's own state to ``LOST`` first, mirroring what
+    ``Device.stop()`` does for ``DISCONNECTED``. Publishing a state the device
+    object does not itself hold leaves the two disagreeing, and anything that later
+    re-announces from that object (``refresh_tree()``, which the SDK asks a
+    bring-your-own-transport caller to wire onto their client's on-connect handler)
+    republishes ``ready`` straight over the ``lost`` we just sent.
+
+    That call also publishes ``$state``, so the flushed publish below is the same
+    retained value a second time. The duplicate is deliberate and costs one message
+    at teardown: ``set_state`` goes through the ordinary unflushed path, and on the
+    owned path the connection closes immediately behind this function, so only a
+    flushed publish is actually guaranteed to land.
+
     Returns True when the broker acknowledged it, False if there is no owned
     client or the publish did not flush in time.
     """
     client = owned_client(root.mqttc)
     if client is None:
         return False
+    root.set_state(DeviceState.LOST)
     will = root.will()
     return bool(
         client.publish_and_flush(

{ebus_panel_sim-0.3.2 → ebus_panel_sim-0.3.3}/tests/test_teardown.py

@@ -71,3 +71,25 @@ def test_ungraceful_stop_publishes_lost_retained(rec: PahoRecorder) -> None:
     lost = [(t, d, q, r) for (t, d, q, r) in rec.published if t == ROOT_STATE and d == "lost"]
     assert lost, "no $state=lost publish reached the transport"
     assert all(retain for (_t, _d, _q, retain) in lost)
+
+
+def test_ungraceful_stop_moves_the_device_state_not_just_the_wire(rec: PahoRecorder) -> None:
+    """Publishing `lost` while the Device object still holds `ready` leaves the two
+    disagreeing, and anything that re-announces from the object undoes the publish.
+    `Device.stop()` sets `_state` for `disconnected`; this must match."""
+    emitter = _started()
+    emitter.stop(graceful=False)
+    assert rec.retained[ROOT_STATE] == "lost"
+    assert emitter._root.state().value == "lost"
+
+
+def test_a_later_refresh_tree_re_announces_lost_not_ready(rec: PahoRecorder) -> None:
+    """`refresh_tree()` republishes from the Device's own state, and the SDK asks a
+    bring-your-own-transport caller to wire it onto their client's on-connect
+    handler. If the ungraceful stop left `_state` on `ready`, that hook would
+    resurrect `ready` over the `lost` and restore the very stale-tree bug 0.3.1
+    removed."""
+    emitter = _started()
+    emitter.stop(graceful=False)
+    emitter._root.refresh_tree()
+    assert rec.retained[ROOT_STATE] == "lost"