- Move UTC import from inline (inside _has_real_gaps_in_range) to
module-level in manager.py
- Hoist get_fetch_groups() out of while loop in _get_cached_intervals:
eliminates ~384 function calls per invocation
- Pre-compute criteria_by_day dict in build_periods before the for-loop:
eliminates ~381 redundant NamedTuple constructions per call; only
ref_price/avg_price vary by day (max 3 entries), flex/min_distance/
reverse_sort are constant throughout
Impact: Reduces unnecessary object creation during the hot paths called
every 15 minutes and during all relaxation phases.
PLW0108: Three lambdas were simple pass-throughs that added no value:
lambda data: aggregate_level_data(data) → aggregate_level_data
lambda: lifecycle_calculator.get_lifecycle_state() → lifecycle_calculator.get_lifecycle_state
Affected files:
sensor/calculators/rolling_hour.py (line 115)
sensor/helpers.py (line 139)
sensor/value_getters.py (line 220)
Impact: No behaviour change. Linter now passes with zero warnings.
Four non-MONETARY diagnostic sensors had state_class set, causing HA
Recorder to add them to long-term statistics tables unnecessarily:
- home_size (m²): SensorStateClass.MEASUREMENT
- main_fuse_size (A): SensorStateClass.MEASUREMENT
- number_of_residents: SensorStateClass.MEASUREMENT
- estimated_annual_consumption(kWh):SensorStateClass.TOTAL
All four are static user metadata retrieved from Tibber's user API
(cached for 24 h, rarely or never changes in practice). They carry no
time-series value: home_size and main_fuse_size don't change, and
estimated_annual_consumption is a rough Tibber estimate, not an actual
accumulating energy counter.
Setting state_class=None removes them from long-term statistics while
keeping normal state-change recording intact.
The three intentional non-None state_class values are unchanged:
- current_interval_price (MONETARY, TOTAL): Energy Dashboard
- current_interval_price_base (MONETARY, TOTAL): Energy Dashboard
- average_price_today (MONETARY, TOTAL): useful weekly/monthly trend
Impact: Reduced Recorder database growth; no user-visible sensor
behaviour change.
The timedelta import move (previous commit) was committed correctly, but a
subsequent automated formatting pass stripped the line that used it:
current_date = current_date + timedelta(days=1)
Without the increment the while loop never terminates, causing HA to hang
indefinitely during coordinator startup when period calculation is triggered.
Additionally, the timedelta module-level import was also reverted by the
same pass, so re-add it here.
Restore both the import and the loop increment so group_periods_by_day
correctly iterates one day at a time.
PLC0415 – suppress with noqa was already suppressing the warning, but the
import was still executed on every iteration of the while loop. Standard
library imports belong at module level both for correctness and performance.
Move 'from datetime import timedelta' to the top-level import block and
remove the now-unnecessary 'noqa: PLC0415' comment.
Impact: Negligible per-call overhead removed. More importantly, the code
no longer suppresses a linter warning that signals a real anti-pattern;
future static analysis runs will correctly flag any new inline imports.
RESOLUTION_CHANGE_ISO was a naive ISO string ("2025-10-01T00:00:00").
_split_at_resolution_boundary compared it against timezone-aware interval
strings via plain string ordering, which is unreliable when the strings
carry different UTC offsets (e.g. +02:00 vs +00:00). More critically,
the naive string was then split into ranges such as ("...", "2025-10-01T00:00:00")
which were parsed back to naive datetime objects in fetch_missing_ranges.
When routing.py then compared those naive objects against the tz-aware
boundary datetime, Python raised TypeError: can't compare offset-naive
and offset-aware datetimes.
Fix:
- Remove RESOLUTION_CHANGE_ISO; derive the boundary ISO string at
runtime from RESOLUTION_CHANGE_DATETIME.isoformat(), which produces
the UTC-normalised string "2025-10-01T00:00:00+00:00".
- Rewrite _split_at_resolution_boundary to parse each range's start/end
to datetime objects, normalise any defensively-naive values to UTC,
and compare against the RESOLUTION_CHANGE_DATETIME constant directly.
- Use the tz-aware boundary_iso string as the split point so downstream
fromisoformat() calls always return tz-aware datetime objects.
Impact: Ranges spanning 2025-10-01T00:00:00 UTC are now split correctly
regardless of the UTC offset carried by the original interval strings,
and no TypeError is raised when routing.py compares the boundary
endpoints to its own tz-aware boundary calculation.
On DST fall-back nights the clocks repeat an hour (e.g. 02:00 CET/CEST).
Tibber delivers quarter-hourly intervals for both the CEST (+02:00) and
CET (+01:00) copies of that hour. Both share the same 19-char naive local
key 'YYYY-MM-DDTHH:MM:SS', so _add_intervals treated the CET arrivals as
unwanted duplicates and sent them to _touch_intervals, which kept the CEST
data and silently discarded the CET price data. The fall-back hour's prices
were permanently lost from the pool.
Fix:
- Add module constant _DST_COLLISION_MAX_SAME_UTC_S (60 s) to distinguish
true duplicate arrivals (same UTC, ≤60 s apart) from DST collision pairs
(~3600 s apart).
- Add _handle_index_collision() helper that compares the UTC datetimes of
the existing and incoming interval. If they differ by more than the
threshold it stores the new interval in self._dst_extras keyed by the
normalised local timestamp and returns True.
- _add_intervals delegates every collision to _handle_index_collision and
only routes to touch when it returns False (true duplicate).
- _get_cached_intervals yields the saved extras after the main interval.
- After each GC run, stale entries are pruned from _dst_extras.
- to_dict / from_dict persist and restore _dst_extras across HA restarts.
Impact: The full fall-back hour (e.g. 02:00-02:45 CET) now appears in the
interval pool alongside the CEST copies, so sensors that query that hour
return correct prices instead of stale or missing data.
_get_sensor_interval_stats() computed expected_count via UTC time
arithmetic ((end - start).total_seconds() / 900 = 480 for 5 days), then
iterated through fixed-offset local timestamps adding timedelta(minutes=15).
On DST spring-forward days (e.g. last Sunday March in EU), clocks skip
from 02:00 to 03:00. The 4 local quarter-hour slots 02:00-02:45 never
exist, so the Tibber API never returns intervals for them. The iteration
still visits those 4 keys, finds them absent from the index, and reports
has_gaps=True (expected=480, actual=476). Since no API call can ever
fill those non-existent slots, the pool triggers an unnecessary gap-fill
fetch every 15 minutes for the entire spring-forward day.
Fix: keep the nominal expected_count for diagnostics, but determine
has_gaps via the new _has_real_gaps_in_range() helper that sorts
cached intervals by UTC time and checks consecutive UTC differences.
The 01:45+01:00 -> 03:00+02:00 transition is exactly 15 minutes in
UTC, so no gap is reported. Start/end boundary comparisons use naive
19-char local timestamps to stay consistent with the fixed-offset
arithmetic used by get_protected_range().
Impact: No spurious API fetches on DST spring-forward Sunday. Gap
detection for real missing data (API failures, first startup) remains
fully functional.
All three re-transform sites (_handle_options_update,
async_handle_config_override_update, _perform_midnight_data_rotation)
were building raw_data with only {'price_info': ...}, omitting
'currency' and 'home_id'.
data_transformation.py's transform_data() falls back to currency='EUR'
and home_id='' when those keys are missing. This caused all non-EUR
users (Norway/NOK, Sweden/SEK) to see wrong currency units in sensors
after every midnight turnover and after any options/override change,
until the next full API poll refilled coordinator.data with correct
values (up to 15 minutes of wrong units).
Fix: explicitly carry over coordinator.data's existing currency and
home_id into each raw_data dict. Also inline the redundant lambda
wrapper on calculate_periods_fn (PLW0108 ruff lint).
Impact: Norwegian and Swedish users no longer see EUR/ct units after
midnight or config changes. Sensor unit-of-measurement stays consistent
throughout the day regardless of re-transform triggers.
All entity descriptions had hardcoded English name= strings that were
never used at runtime: HA always prefers translations via translation_key
(entity.<platform>.<key>.name in translations/en.json), making the name=
fields dead code.
Removed 106 lines across all four platforms:
- sensor/definitions.py: 85 name= lines
- number/definitions.py: 12 name= lines
- binary_sensor/definitions.py: 6 name= lines
- switch/definitions.py: 3 name= lines
No functional change. The unique_id (entry_id + key) and translation_key
remain stable, ensuring entity IDs and friendly names are unaffected.
Impact: Cleaner definitions, no drift between name= strings and
translations. Aligns with HA standard: translations are the single
source of truth for entity names.
Add coverage for the state_class/statistics table optimization across
both user and developer documentation.
docs/user/docs/configuration.md:
- Add 'Price Sensor Statistics' section explaining that only 3 sensors
write to the HA statistics database (current_interval_price,
current_interval_price_base, average_price_today)
- Fix incorrect entity ID examples: remove non-existent _override suffix
from recorder exclude globs, Developer Tools example, and seasonal
automation example (actual IDs: number.*_best_price_flexibility etc.)
docs/developer/docs/recorder-optimization.md:
- Add 'Long-Term Statistics Optimization (state_class)' section covering
the statistics/statistics_short_term table dimension, which is distinct
from _unrecorded_attributes (state_attributes table)
- Documents the MONETARY device_class constraint (MEASUREMENT blocked by
hassfest, only TOTAL or None valid), the 3 sensors keeping TOTAL with
rationale, the 23 sensors set to None, and ~88% write reduction
- Includes comparison table: _unrecorded_attributes vs state_class
Impact: Users now understand the built-in statistics optimization and
have correct recorder exclude examples. Developers understand both
optimization layers and their interaction.
Previously all 26 MONETARY sensors had state_class=TOTAL, causing the
statistics and statistics_short_term tables to grow unbounded (never
auto-purged by HA).
Reduced to 3 sensors that genuinely benefit from long-term history:
- current_interval_price (main price sensor, trend over weeks/months)
- current_interval_price_base (required for Energy Dashboard)
- average_price_today (daily avg tracking over seasons)
Set state_class=None on 23 sensors where long-term history adds no
value: forecast/future sensors (next_avg_*h), daily snapshots
(lowest/highest_price_today), tomorrow sensors, rolling windows
(trailing/leading 24h), and next/previous interval sensors.
Note: state_class=None does not affect the States timeline (History
panel). Only the Statistics chart on entity detail pages is removed
for the affected sensors. Existing statistics data is retained.
Impact: ~88% reduction in statistics table writes. Prevents database
bloat reported by users with long-running installations.
User docs (period-calculation.md):
- New troubleshooting section "Fewer Periods Than Configured" (most
common confusing scenario, added before "No Periods Found")
- Extended "Understanding Sensor Attributes" section: all four diagnostic
attributes documented with concrete YAML examples and prose explanations
- Updated Table of Contents
Developer docs (period-calculation-theory.md):
- New section "Flat Day and Low-Price Adaptations" (between Flex Limits
and Relaxation Strategy) documenting all three mechanisms with
implementation details, scaling tables, and rationale for hardcoding
- Two new scenarios: 2b (flat day with adaptive min_periods) and 2c
(solar surplus / absolute low-price day) with expected logs and
sensor attribute examples
- Debugging checklist point 6: flat day / low-price checks with
exact log string patterns to grep for
- Diagnostic attribute reference table in the debugging section
Impact: Users can self-diagnose "fewer periods than configured" without
support. Contributors understand why the three thresholds are hardcoded
and cannot be user-configured.
Add calculation summary attributes to best_price_period and
peak_price_period binary sensors for diagnostic transparency.
New attributes (all excluded from recorder history):
- min_periods_configured: User's configured target per day (always shown)
- periods_found_total: Actual periods found across all days (always shown)
- flat_days_detected: Days where CV <= 10% reduced target to 1 (only when > 0)
- relaxation_incomplete: Some days couldn't reach the target (only when true)
These attributes explain observed behavior without requiring users to
read logs: seeing "flat_days_detected: 1" alongside
"min_periods_configured: 2, periods_found_total: 1" immediately
explains why the count is lower than configured on uniform-price days.
Implementation:
- _compute_day_effective_min() now returns (dict, int) tuple to propagate
the flat day count through to the metadata dict
- flat_days_detected added to metadata["relaxation"] in
calculate_periods_with_relaxation()
- build_final_attributes_simple() gains optional period_metadata parameter
- New add_calculation_summary_attributes() function handles the rendering
- Attributes are shown even when no period is currently active
Updated recorder-optimization.md: attribute counts + clarified that
timestamp is correctly excluded (entity native_value is recorded
separately by HA as the entity state itself).
Impact: Users can understand why they received fewer periods than
configured without enabling debug logging.
Three complementary fixes for pathological price days:
1. Adaptive min_periods for flat days (CV ≤ 10%):
On days with nearly uniform prices (e.g. solar surplus), enforcing
multiple distinct cheap periods is geometrically impossible.
_compute_day_effective_min() detects CV ≤ LOW_CV_FLAT_DAY_THRESHOLD
and reduces the effective target to 1 for that day (best price only;
peak price always runs full relaxation).
2. min_distance scaling on absolute low-price days:
When the daily average drops below 0.10 EUR (10 ct), percentage-based
min_distance becomes unreliable. The threshold is scaled linearly to
zero so the filter neither accepts the entire day nor blocks everything.
3. CV quality gate bypass for absolute low-price periods:
Periods with a mean below 0.10 EUR may show high relative CV even
though the absolute price differences are fractions of a cent.
Both _check_period_quality() and _check_merge_quality_gate() now
bypass the CV gate below this threshold.
Additionally: span-aware flex warnings now emit INFO/WARNING when
base_flex >= 25%/30% and at least one "normal" (non-V-shape) day
exists (FLEX_WARNING_VSHAPE_RATIO = 0.5). Previously the constants
were defined but never used.
Updated 3 test assertions in test_best_price_e2e.py: the flat-day
fixture (CV ~5.4%) correctly produces 1 period, not 2.
Impact: Best Price periods now appear reliably on V-shape solar days
and flat-price days. No more "0 periods" on days where the single
cheapest window is a valid and useful result.
homeassistant==2026.3.4 requires Python>=3.14.2. The lint workflow was
specifying Python 3.13, and uv venv was ignoring actions/setup-python and
picking up the system Python (3.14.0) instead.
Changes:
- lint.yml: python-version 3.13 → 3.14
- bootstrap: uv venv now uses $(which python) to respect
actions/setup-python and local pyenv/asdf setups
Impact: lint workflow no longer fails with Python version unsatisfiable
dependency error when installing homeassistant.
grep -q "refs/tags/$TAG" matched substrings, so v0.27.0b0
would block release of v0.27.0. Changed to "refs/tags/${TAG}$"
to require exact end-of-line match.
_get_cached_intervals() used fixed-offset datetimes from fromisoformat()
for iteration. When start and end boundaries span a DST transition (e.g.,
+01:00 CET → +02:00 CEST), the loop's end check compared UTC values,
stopping 1 hour early on spring-forward days.
This caused the last 4 quarter-hourly intervals of "tomorrow" to be
missing, making the binary sensor "Tomorrow data available" show Off
even when full data was present.
Changed iteration to use naive local timestamps, matching the index key
format (timezone stripped via [:19]). The end boundary comparison now
works correctly regardless of DST transitions.
Impact: Binary sensor "Tomorrow data available" now correctly shows On
on DST spring-forward days. Affects all European users on the last
Sunday of March each year.
