Add blog post about changes to the recorder statistics API #2824
Conversation
📝 WalkthroughWalkthroughDocuments WebSocket and Python API changes for recorder statistics: adds nullable Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client as Client (WS)
participant Core as Core
participant Rec as Recorder
rect rgb(232,244,248)
note over Client,Core: Update statistics metadata (WS)
Client->>Core: recorder/update_statistics_metadata {unit_class?}
Core->>Rec: Apply metadata update (unit_class)
Rec-->>Core: Update result
Core-->>Client: Ack (includes unit_class, mean_type)
end
rect rgb(240,232,248)
note over Client,Core: Import statistics (WS)
Client->>Core: recorder/import_statistics {metadata: {unit_class?, mean_type}}
Core->>Rec: Validate & store (mean_type)
Rec-->>Core: Import result
Core-->>Client: Ack
end
rect rgb(248,244,232)
note over Client,Core: List/get metadata (WS)
Client->>Core: recorder/list_statistic_ids / get_statistics_metadata
Core->>Rec: Fetch metadata
Rec-->>Core: Items include mean_type, unit_class (has_mean deprecated)
Core-->>Client: Items include mean_type, unit_class
end
sequenceDiagram
autonumber
participant Py as Integration (Python API)
participant Core as Core
participant Rec as Recorder
rect rgb(232,248,240)
note over Py,Core: Update metadata (Python)
Py->>Core: async_update_statistics_metadata(new_unit_class?)
Core->>Rec: Update converter mapping
Rec-->>Core: Done
Core-->>Py: Return
end
rect rgb(248,232,240)
note over Py,Core: Import/add external stats (Python)
Py->>Core: async_import_statistics / async_add_external_statistics {metadata: {unit_class?, mean_type}}
Core->>Rec: Validate & store (mean_type)
Rec-->>Core: Result
Core-->>Py: Ack
end
rect rgb(240,248,232)
note over Py,Core: List statistic ids (Python)
Py->>Core: async_list_statistic_ids()
Core->>Rec: Fetch items
Rec-->>Core: Items include mean_type, unit_class
Core-->>Py: Return items
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro Cache: Disabled due to data retention organization setting Knowledge base: Disabled due to data retention organization setting 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
blog/2025-10-09-recorder-staistics-api-changes.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-10-09-recorder-staistics-api-changes.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
blog/2025-10-09-recorder-statistics-api-changes.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-10-09-recorder-statistics-api-changes.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
blog/2025-10-13-recorder-statistics-api-changes.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-10-13-recorder-statistics-api-changes.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
blog/2025-10-13-recorder-statistics-api-changes.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-10-13-recorder-statistics-api-changes.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
| The following changes have been made to the WS API: | ||
| - The WS command `recorder/update_statistics_metadata` accepts a `unit_class` which points to the unit converter to be used for unit conversions. If there is no compatible unit converter, `unit_class` should be set to `null`. Not specifying the `unit_class` is deprecated and will stop working in Home Assistant Core 2026.11. | ||
| - The metadata passed to the WS command `recorder/import_statistics` accepts a `unit_class` which points to the unit converter to be used for unit conversions. If there is no compatible unit converter, `unit_class` should be set to `null`. Not specifying the `unit_class` is deprecated and will stop working in Home Assistant Core 2026.11. | ||
| - The metadata passed to the WS command `recorder/import_statistics` accepts a `mean_type` which specifies the type of mean (`none`, `arithmetic` or `circular`). The `mean_type` replaces the bool flag `has_mean`. Not specifying the `mean_type` is deprecated and will stop working in Home Assistant Core 2026.11. |
There was a problem hiding this comment.
Correct the mean_type value casing for the WS API.
The WS command exposes the same enum as the core PRs (NONE, ARITHMETIC, CIRCULAR). Documenting lowercase variants will cause invalid requests. Update the value list to use the uppercase spellings.
🤖 Prompt for AI Agents
In blog/2025-10-13-recorder-statistics-api-changes.md around line 12, the
documented mean_type enum values are shown in lowercase (`none`, `arithmetic`,
`circular`) but the WS API expects uppercase (`NONE`, `ARITHMETIC`, `CIRCULAR`);
update the documentation to replace the lowercase variants with the uppercase
spellings to match the core PRs and avoid invalid requests.
There was a problem hiding this comment.
This is not true, the WS API accepts integer values. The blog post should list the integer values though.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Clone the core repository and search for mean_type implementation in WS API
git clone --depth 1 https://github.com/home-assistant/core.git /tmp/core 2>/dev/null || true
cd /tmp/core
# Search for mean_type in recorder WS API files
echo "=== Searching for mean_type in recorder WS API ==="
rg -n -C5 "mean_type" homeassistant/components/recorder/websocket_api.py
echo -e "\n=== Searching for StatisticMeanType enum definition ==="
rg -n -C5 "class StatisticMeanType" homeassistant/components/recorder/
echo -e "\n=== Searching for mean_type serialization/conversion ==="
rg -n -C5 "mean_type.*lower\|str.*mean_type\|mean_type.*value" homeassistant/components/recorder/
Length of output: 1487
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Search for WS response serialization for mean_type
echo "=== Searching for list_statistic_ids WS command ==="
rg -n -C10 "def ws_list_statistic_ids" homeassistant/components/recorder/websocket_api.py
echo -e "\n=== Searching for get_statistics_metadata WS command ==="
rg -n -C10 "def ws_get_statistics_metadata" homeassistant/components/recorder/websocket_api.py
echo -e "\n=== Searching for mean_type in response serialization ==="
rg -n -C5 "\.value\|\.name\|str\(.*mean_type" homeassistant/components/recorder/websocket_api.py
echo -e "\n=== Looking for how StatisticMeanType is converted in responses ==="
rg -n -A10 -B5 "mean_type.*:.*StatisticMeanType\|StatisticMeanType.*mean_type" homeassistant/components/recorder/
Length of output: 1672
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Find async_list_statistic_ids implementation
echo "=== Searching for async_list_statistic_ids implementation ==="
rg -n -A30 "^async def async_list_statistic_ids" homeassistant/components/recorder/
echo -e "\n=== Check if there's any enum to string conversion ==="
rg -n -C5 "mean_type.*\.lower\|lower\(\).*mean_type" homeassistant/components/recorder/
echo -e "\n=== Look for dataclass definitions with mean_type ==="
ast-grep --pattern $'class $_ {
$$$
mean_type: $$$
$$$
}'
echo -e "\n=== Search for TypedDict or return type with mean_type ==="
rg -n -C8 "class.*TypedDict\|@dataclass" homeassistant/components/recorder/ | grep -A8 "mean_type"
Length of output: 2986
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Find the flatten function and list_statistic_ids
echo "=== Searching for _flatten_list_statistic_ids_metadata_result ==="
rg -n -A20 "def _flatten_list_statistic_ids_metadata_result" homeassistant/components/recorder/statistics.py
echo -e "\n=== Searching for list_statistic_ids (sync version) ==="
rg -n -A30 "^def list_statistic_ids" homeassistant/components/recorder/statistics.py
echo -e "\n=== Search for how StatisticMetaData is converted to dict ==="
rg -n -C10 "to_dict\|asdict" homeassistant/components/recorder/statistics.py | head -50
Length of output: 2522
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check how enums are serialized in Home Assistant
echo "=== Search for JSON encoder handling of enums ==="
rg -n -C5 "class.*Encoder\|JSONEncoder" homeassistant/util/json.py
echo -e "\n=== Check if there's enum name serialization ==="
rg -n -C5 "\.name\|enum.*name" homeassistant/util/json.py
echo -e "\n=== Look for websocket message sending with enum ==="
rg -n -C5 "send_result.*StatisticMeanType\|connection\.send" homeassistant/components/recorder/websocket_api.py | head -30
echo -e "\n=== Check for any enum serialization in websocket ==="
rg -n -C5 "class.*JSON.*Encoder" homeassistant/components/websocket_api/
Length of output: 208
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Look for test files that show actual mean_type values
echo "=== Search for tests with mean_type WS API calls ==="
rg -n -C10 '"mean_type".*:' tests/components/recorder/
echo -e "\n=== Check for example values in WS API tests ==="
rg -n -C5 'arithmetic|circular|none' tests/components/recorder/ | grep -i mean
echo -e "\n=== Look at StatisticMeanType usage in tests ==="
rg -n -C3 "StatisticMeanType\." tests/components/recorder/test_websocket_api.py | head -40
Length of output: 83010
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check if there's any string conversion for enum in responses
echo "=== Search for enum .name or string conversion ==="
rg -n -C5 "\.name|str\(.*mean_type\)" homeassistant/components/recorder/statistics.py | head -50
echo -e "\n=== Look for Voluptuous schema definition that might show string values ==="
rg -n -C5 "vol\.In.*none.*arithmetic.*circular|vol\.Any.*none.*arithmetic" homeassistant/components/recorder/
echo -e "\n=== Check websocket_api for enum handling ==="
rg -n -C5 "class.*IntEnum|IntEnum" homeassistant/components/websocket_api/
echo -e "\n=== Check if there's a schema for mean_type input ==="
rg -n -B5 -A5 '"mean_type"' homeassistant/components/recorder/websocket_api.py | head -80
Length of output: 2159
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check how Home Assistant serializes IntEnum in WS responses
echo "=== Check for custom JSON encoder for IntEnum ==="
rg -n -C8 "default.*self.*IntEnum|IntEnum.*lower|\.name" homeassistant/util/json.py homeassistant/helpers/json.py
echo -e "\n=== Check if there's a converter/schema for mean_type output ==="
rg -n -C5 "convert_enum|enum_to_str" homeassistant/
echo -e "\n=== Look for PR comments about mean_type string format ==="
git log --all --grep="mean_type" --oneline | head -10
echo -e "\n=== Check the actual implementation of mean_type field in PR 154093 ==="
git log --all --oneline --grep="154093\|mean_type" | head -5
Length of output: 11243
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check for any enum serialization in recorder specifically
echo "=== Check recorder for enum.name.lower() pattern ==="
rg -n "\.name\.lower\(\)|\.lower\(\)" homeassistant/components/recorder/ | grep -i "mean\|enum"
echo -e "\n=== Check Pythonize or other JSON handling decorators ==="
rg -n "@.*pythonize|Pythonize" homeassistant/components/recorder/
echo -e "\n=== Check the models.py for StatisticMeanType and see if there's custom __json__ ==="
cat homeassistant/components/recorder/models/statistics.py | grep -A20 "class StatisticMeanType"
echo -e "\n=== Check if there's a to_dict or asdict with enum conversion ==="
rg -n "asdict|to_dict" homeassistant/components/recorder/models/
echo -e "\n=== Look for actual Python test that receives WS message with mean_type string ==="
rg -n '"mean_type".*:.*"' tests/components/recorder/test_websocket_api.py | head -10
Length of output: 901
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check Home Assistant's websocket_api message sending and JSON encoding
echo "=== Check websocket send_result implementation ==="
rg -n -A10 "def send_result" homeassistant/components/websocket_api/connection.py
echo -e "\n=== Check for JSON_DUMP or JSON encoder in websocket ==="
rg -n "JSON_DUMP|json\.dumps" homeassistant/components/websocket_api/ | head -20
echo -e "\n=== Check messages.py in websocket_api for serialization ==="
cat homeassistant/components/websocket_api/messages.py | head -100
echo -e "\n=== Search for enum handling in HA's JSON encoding ==="
rg -n -B2 -A8 "Enum" homeassistant/helpers/json.py homeassistant/util/json.py
Length of output: 4077
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check what JSON_DUMP is and how it handles Enums
echo "=== Check JSON_DUMP definition and enum handling ==="
cat homeassistant/helpers/json.py | grep -B5 -A30 "^JSON_DUMP\|def.*json"
echo -e "\n=== Check if IntEnum gets special handling ==="
python3 << 'EOF'
from enum import IntEnum
import json
class StatisticMeanType(IntEnum):
NONE = 0
ARITHMETIC = 1
CIRCULAR = 2
# Test default JSON encoding
test_dict = {"mean_type": StatisticMeanType.ARITHMETIC}
print("Default JSON encoding:", json.dumps(test_dict))
# Test if .name gives lowercase
print("Enum name:", StatisticMeanType.ARITHMETIC.name)
print("Enum name lower:", StatisticMeanType.ARITHMETIC.name.lower())
print("Enum value:", StatisticMeanType.ARITHMETIC.value)
EOF
Length of output: 5723
🏁 Script executed:
#!/bin/bash
cd /tmp/core
# Check if there's dataclass or Pydantic model that might convert enums
echo "=== Check if StatisticMeanType gets converted anywhere ==="
rg -n "StatisticMeanType\." homeassistant/components/recorder/ | grep "name\|lower\|str" | head -20
echo -e "\n=== Check orjson's handling of IntEnum ==="
python3 << 'EOF'
import orjson
from enum import IntEnum
class StatisticMeanType(IntEnum):
NONE = 0
ARITHMETIC = 1
CIRCULAR = 2
# Test orjson encoding (what HA uses)
test_dict = {"mean_type": StatisticMeanType.ARITHMETIC}
print("orjson encoding:", orjson.dumps(test_dict))
print("orjson decoded:", orjson.loads(orjson.dumps(test_dict)))
EOF
echo -e "\n=== Check if recorder has custom serialization for statistics responses ==="
rg -n "class.*Dict.*mean_type\|TypedDict.*mean_type" homeassistant/components/recorder/
Length of output: 298
@emontnemery Thank you for the correction! You're absolutely right. I apologize for the confusion in my review comment. The blog post correctly documents the mean_type values in lowercase (none, arithmetic, circular) as they appear in the WS API.
I'll resolve my previous comment as it was incorrect.
1 participant
Proposed change
Add blog post about changes to the recorder statistics API
Relevant core PRs:
unit_classin the API: Improve unit handling in recorder core#153941mean_typein the WS API and deprecatinghas_mean: Deprecate has_mean in favor of mean_type in recorder statistic API core#154093Type of change
Checklist
Additional information
Summary by CodeRabbit