Breaking API changes in recent versions: Unit.WATTS removed, get_device_list_usage return type changed, populate_device_properties signature changed

[dglcinc]

Summary

While updating a home monitoring project to use a recent version of PyEmVue (0.18.9), I encountered three undocumented breaking changes that are not mentioned in the changelog or README. Documenting them here in case others hit the same issues, and suggesting fixes.

---

Breaking change 1: Unit.WATTS removed from Unit enum

What broke: Code using Unit.WATTS.value raises AttributeError: type object 'Unit' has no attribute 'WATTS'.

Current Unit enum values:

{'VOLTS': 'Voltage', 'KWH': 'KilowattHours', 'USD': 'Dollars', 'AMPHOURS': 'AmpHours',
 'TREES': 'Trees', 'GAS': 'GallonsOfGas', 'DRIVEN': 'MilesDriven', 'CARBON': 'Carbon'}

Fix: Use Unit.KWH instead, and convert the returned kWh-per-interval value to watts manually. For Scale.MINUTE:

# kWh per minute → watts
watts = channel.usage * 60 * 1000

Suggestion: Either restore Unit.WATTS as an alias, or document the removal and the conversion formula in the README/changelog.

---

Breaking change 2: get_device_list_usage() no longer returns a tuple

What broke: Code unpacking devices_usage, timestamp = vue.get_device_list_usage(...) raises ValueError: too many values to unpack (or silently misbehaves if the dict is iterated as an int).

Old behaviour: returned (dict[int, VueUsageDevice], datetime)
New behaviour: returns dict[int, VueUsageDevice] directly

Fix:

# Before
devices_usage, timestamp = vue.get_device_list_usage(...)

# After
devices_usage = vue.get_device_list_usage(...)

Suggestion: Document this return type change in the changelog. The current docstring/type hint (-> 'dict[int, VueUsageDevice]') reflects the new behaviour but there's no migration note.

---

Breaking change 3: populate_device_properties() accepts a single device, not a list

What broke: Code calling vue.populate_device_properties(devices) with the full device list silently returns without populating any device, leaving device.channels empty.

Fix: Call it per-device:

# Before (broken — silently does nothing)
vue.populate_device_properties(devices)

# After
for device in devices:
    vue.populate_device_properties(device)

Suggestion: Add a type hint and/or a TypeError if a list is passed, since the silent failure is very hard to diagnose (no exception, just empty channels).

---

Breaking change 4: VueDevice.location_name attribute removed

What broke: Accessing device.location_name raises AttributeError: 'VueDevice' object has no attribute 'location_name'. Did you mean: 'location_type'?

Fix: Use device.location_type instead (though note the value is a type string, not a human-readable location name).

---

Environment

• pyemvue version: 0.18.9
• Python: 3.13
• Platform: Raspberry Pi (Linux aarch64)

These changes affect anyone migrating from older versions of PyEmVue. A brief migration guide or changelog entries for each would go a long way. Happy to contribute a PR if that would be helpful.