jpawlowski/hass.tibber_prices
1
0
Fork 0
mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-03-30 05:13:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

update copilot instructions

Browse source
This commit is contained in:
Julian Pawlowski 2025-11-03 21:49:15 +00:00
parent 2f7b48e177
commit fbda6281d1
1 changed files with 226 additions and 138 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

364
.github/copilot-instructions.md vendored
View file

@ -1,182 +1,270 @@
# Copilot Instructions # Copilot Instructions
This repository contains a **custom component for Home Assistant**, intended to be distributed via the **HACS (Home Assistant Community Store)**. This is a **Home Assistant custom component** for Tibber electricity price data, distributed via **HACS**. It fetches, caches, and enriches **quarter-hourly** electricity prices with statistical analysis, price levels, and ratings.
## Development Guidelines ## Architecture Overview
- Follow the **official Home Assistant development guidelines** at [developers.home-assistant.io](https://developers.home-assistant.io). **Core Data Flow:**
- Ensure compatibility with the **latest Home Assistant release**.
- Use **async functions**, **non-blocking I/O**, and **config flows** where applicable.
- Structure the component using these standard files:
- `__init__.py` – setup and teardown 1. `TibberPricesApiClient` (`api.py`) queries Tibber's GraphQL API with `resolution:QUARTER_HOURLY` for user data and prices (yesterday/today/tomorrow - 192 intervals total)
- `manifest.json` – metadata and dependencies 2. `TibberPricesDataUpdateCoordinator` (`coordinator.py`) orchestrates updates every 15 minutes, manages persistent storage via `Store`, and schedules quarter-hour entity refreshes
- `config_flow.py` – if the integration supports UI configuration 3. Price enrichment functions (`price_utils.py`, `average_utils.py`) calculate trailing/leading 24h averages, price differences, and rating levels for each 15-minute interval
- `sensor.py`, `switch.py`, etc. – for platforms 4. Entity platforms (`sensor.py`, `binary_sensor.py`) expose enriched data as Home Assistant entities
- `const.py` – constants (`DOMAIN`, `CONF_*`, etc.) 5. Custom services (`services.py`) provide API endpoints for integrations like ApexCharts
- Use Home Assistant's built-in helpers and utility modules: **Key Patterns:**
- `homeassistant.helpers.entity`, `device_registry`, `config_validation` - **Dual translation system**: Standard HA translations in `/translations/` (config flow, UI strings per HA schema), supplemental in `/custom_translations/` (entity descriptions not supported by HA schema). Both must stay in sync. Use `async_load_translations()` and `async_load_standard_translations()` from `const.py`. When to use which: `/translations/` is bound to official HA schema requirements; anything else goes in `/custom_translations/` (requires manual translation loading).
- `homeassistant.util.dt` (`dt_util`) for time/date handling - **Price data enrichment**: All quarter-hourly price intervals get augmented with `trailing_avg_24h`, `difference`, and `rating_level` fields via `enrich_price_info_with_differences()` in `price_utils.py`. Enriched structure example:
```python
{
"startsAt": "2025-11-03T14:00:00+01:00",
"total": 0.2534, # Original from API
"level": "NORMAL", # Original from API
"trailing_avg_24h": 0.2312, # Added: 24h trailing average
"difference": 9.6, # Added: % diff from trailing avg
"rating_level": "NORMAL" # Added: LOW/NORMAL/HIGH based on thresholds
}
```
- **Quarter-hour precision**: Entities update on 00/15/30/45-minute boundaries via `_schedule_quarter_hour_refresh()` in coordinator, not just on data fetch intervals. This ensures current price sensors update without waiting for the next API poll.
- **Currency handling**: Multi-currency support with major/minor units (e.g., EUR/ct, NOK/øre) via `get_currency_info()` and `format_price_unit_*()` in `const.py`.
- **Intelligent caching strategy**: Minimizes API calls while ensuring data freshness:
- User data cached for 24h (rarely changes)
- Price data validated against calendar day - cleared on midnight turnover to force fresh fetch
- Cache survives HA restarts via `Store` persistence
- API polling intensifies only when tomorrow's data expected (afternoons)
- Stale cache detection via `_is_cache_valid()` prevents using yesterday's data as today's
- Do not wrap built-in functions (e.g., don’t wrap `dt_util.parse_datetime`) **Component Structure:**
- Avoid third-party or custom libraries unless absolutely necessary
- Never assume static local file paths — use config options and relative paths
## Coding Style Policy ```
custom_components/tibber_prices/
├── __init__.py # Entry setup, platform registration
├── coordinator.py # DataUpdateCoordinator with caching/scheduling
├── api.py # GraphQL client with retry/error handling
├── price_utils.py # Price enrichment, level/rating calculations
├── average_utils.py # Trailing/leading average utilities
├── services.py # Custom services (get_price, ApexCharts, etc.)
├── sensor.py # Price/stats/diagnostic sensors
├── binary_sensor.py # Peak/best hour binary sensors
├── entity.py # Base TibberPricesEntity class
├── data.py # @dataclass TibberPricesData
├── const.py # Constants, translation loaders, currency helpers
├── config_flow.py # UI configuration flow
└── services.yaml # Service definitions
```
- Follow **PEP8**, enforced by **Black**, **isort**, and **Ruff** ## Development Workflow
- Use **type hints** on all function and method signatures
- Add **docstrings** for all public classes and methods
- Use **f-strings** for string formatting
- Do not use `print()` — use `_LOGGER` for logging
- YAML examples must be **valid**, **minimal**, and **Home Assistant compliant**
## Code Structure and Ordering Policy **Start dev environment:**
Use the following order inside Python modules: ```bash
./scripts/develop # Starts HA in debug mode with config/ dir, sets PYTHONPATH
```
1. **Imports** **Linting (auto-fix):**
- Python standard library imports first ```bash
- Third-party imports (e.g., `homeassistant.*`) ./scripts/lint # Runs ruff format + ruff check --fix
- Local imports within this component (`from . import xyz`) ```
- Enforced automatically by `isort`
2. **Module-level constants and globals** **Linting (check-only):**
- Define constants and globals at module-level (e.g., `DOMAIN`, `_LOGGER`, `CONF_*`, `DEFAULT_*`) ```bash
./scripts/lint-check # CI mode, no modifications
```
3. **Top-level functions** **Testing:**
- Use only for stateless, reusable logic ```bash
- Prefix with `_` if internal only (e.g., `_parse_price()`) pytest tests/ # Unit tests exist (test_*.py) but no framework enforced
- Do not place Home Assistant lifecycle logic here ```
- **Sort and group top-level functions for maximum readability:**
- Place public API/entry point functions (e.g., service handlers, async setup) at the top of the function section.
- Direct helpers (called by entry points) immediately after, in the order they are called.
- Pure/stateless utility functions that are not tightly coupled to entry points at the end.
- Where possible, order functions so that a function appears before any function that calls it (call hierarchy order).
- Group related functions by logical purpose or data handled, and use `#region`/`#endregion` folding comments for large files if needed.
4. **Main classes** **Key commands:**
- Define main classes (Home Assistant Entity classes, DataUpdateCoordinators, and ConfigFlow handlers) - Dev container includes `hass` CLI for manual HA operations
- Order inside class: - Use `uv run --active` prefix for running Python tools in the venv
- Special methods (`__init__`, `__repr__`) - `.ruff.toml` enforces max line length 120, complexity ≤25, Python 3.13 target
- Public methods (no `_`)
- Private methods (`_prefix`)
- All I/O or lifecycle methods must be `async def`
5. **Helper classes** ## Critical Project-Specific Patterns
- If helper classes become complex, move them to separate modules (e.g., `helpers.py`, `models.py`) **1. Translation Loading (Async-First)**
Always load translations at integration setup or before first use:
> ✅ Copilot tip:
>
> - Use top-level functions for pure helpers only.
> - Prefer structured classes where Home Assistant expects them.
> - Sort and group functions for maximum readability and maintainability, following call flow from entry points to helpers to utilities.
## Code Comments Policy
- Do **not** add comments in the code to explain automated changes, such as reordering, renaming, or compliance with coding standards or prompts.
- Comments in code should be reserved **only** for documenting the actual logic, purpose, or usage of code elements (e.g., classes, methods, functions, or complex logic blocks).
- If any explanations of automated actions are needed, provide them **outside the code file** (such as in your chat response, PR description, or commit message), not within the Python files themselves.
- Do **not** insert comments like `# moved function`, `# renamed`, `# for compliance`, or similar into code files.
## Backwards Compatibility Policy
- Do **not** implement or suggest backward compatibility features, workarounds, deprecated function support, or compatibility layers unless **explicitly requested** in the prompt or project documentation.
- All code should assume a clean, modern codebase and should target the latest stable Home Assistant version only, unless otherwise specified.
- If you believe backward compatibility might be required, **ask for clarification first** before adding any related code.
## Translations Policy
- All user-facing strings supported by Home Assistant's translation system **must** be defined in `/translations/en.json` and (if present) in other `/translations/*.json` language files.
- When adding or updating a translation key in `/translations/en.json`, **ensure that all other language files in `/translations/` are updated to match the same set of keys**. Non-English files may use placeholder values if no translation is available, but **must** not miss any keys present in `en.json`.
- Do **not** remove or rename translation keys without updating all language files accordingly.
- Never duplicate translation keys between `/translations/` and `/custom_translations/`.
- The `/custom_translations/` directory contains **supplemental translation files** for UI strings or other content not handled by the standard Home Assistant translation format.
- Only add strings to `/custom_translations/` if they are not supported by the standard Home Assistant translation system.
- Do **not** duplicate any string or translation key that could be handled in `/translations/`.
- When both exist, the standard Home Assistant translation in `/translations/` **always takes priority** over any supplemental entry in `/custom_translations/`.
- All translation files (both standard and custom) **must remain in sync** with the English base file (`en.json`) in their respective directory.
> ✅ Copilot tip: Whenever adding or changing user-facing strings, update both the main translation files in `/translations/` and the supplemental files in `/custom_translations/`, keeping them in sync and avoiding duplication.
## Data Structures
Use `@dataclass` for plain data containers where appropriate:
```python ```python
from dataclasses import dataclass # In __init__.py async_setup_entry:
await async_load_translations(hass, "en")
@dataclass await async_load_standard_translations(hass, "en")
class PriceSlot:
start: datetime
end: datetime
price: float
``` ```
## Visual File Layout Access cached translations synchronously later via `get_translation(path, language)`.
Split component logic into multiple Python modules for improved clarity and maintainability: **2. Price Data Enrichment**
Never use raw API price data directly. Always enrich first:
``` ```python
/custom_components/your_component/ from .price_utils import enrich_price_info_with_differences
├── __init__.py
├── manifest.json enriched = enrich_price_info_with_differences(
├── const.py price_info_data, # Raw API response
├── sensor.py thresholds, # User-configured rating thresholds
├── config_flow.py )
├── models.py # dataclasses
├── helpers.py # pure utility functions
``` ```
Use `#region` / `#endregion` optionally to improve readability in large files. This adds `trailing_avg_24h`, `difference`, `rating_level` to each interval.
## Optional Files (Custom Integration via HACS) **3. Time Handling**
Always use `dt_util.as_local()` when comparing API timestamps (UTC) to local time:
Only create these files if explicitly required by your integration features. Not all files used in Core integrations apply to Custom Integrations: ```python
from homeassistant.util import dt as dt_util
- `services.yaml` – Define custom Home Assistant services price_time = dt_util.parse_datetime(price_data["startsAt"])
- `translations/*.json` (e.g., `en.json`, `de.json`) – Provide translations for UI elements price_time = dt_util.as_local(price_time) # Convert to local TZ
- Additional platform files (e.g., `binary_sensor.py`, `switch.py`, `number.py`, `button.py`, `select.py`) – Support for additional entity types ```
- `websocket_api.py` – Define custom WebSocket API endpoints
- `diagnostics.py` – Provide diagnostic data to users and maintainers
- `repair.py` – Offer built-in repair hints or troubleshooting guidance
- `issue_registry.py` – Communicate integration-specific issues or important changes to users clearly
> ⚠️ **Copilot tip**: Avoid Core-only files (`device_action.py`, `device_trigger.py`, `device_condition.py`, `strings.json`) for Custom Integrations. These are typically not supported or rarely used. **4. Coordinator Data Structure**
Access coordinator data like:
## Linting and Code Quality Policy ```python
coordinator.data = {
"user_data": {...}, # Cached user info from viewer query
"priceInfo": {
"yesterday": [...], # List of enriched price dicts
"today": [...],
"tomorrow": [...],
"currency": "EUR",
},
}
```
- Enforced by **Ruff**, which runs: **5. Service Response Pattern**
Services use `SupportsResponse.ONLY` and must return dicts:
- Locally via VS Code devcontainer ```python
- Remotely via GitHub Actions @callback
def async_setup_services(hass: HomeAssistant) -> None:
hass.services.async_register(
DOMAIN, "get_price", _get_price,
schema=PRICE_SERVICE_SCHEMA,
supports_response=SupportsResponse.ONLY,
)
```
Key Ruff linter rules that must be followed: ## Code Quality Rules
- `F401`, `F841` – No unused imports or variables **Ruff config (`.ruff.toml`):**
- `E402`, `E501` – Imports at top, lines ≤88 chars
- `C901`, `PLR0912`, `PLR0915` – Functions must be small and simple
- `PLR0911`, `RET504` – No redundant `else` after `return`
- `B008` – No mutable default arguments
- `T201` – Do not use `print()`
- `SIM102` – Prefer `if x` over `if x == True`
Also: - Max line length: **120** chars (not 88 from default Black)
- Max complexity: **25** (McCabe)
- Target: Python 3.13
- No unused imports/variables (`F401`, `F841`)
- No mutable default args (`B008`)
- Use `_LOGGER` not `print()` (`T201`)
- Use **Black** for formatting **Import order (enforced by isort):**
- Use **isort** for import sorting
- See `.ruff.toml` for custom settings
- Prefer **one return statement per function** unless early returns improve clarity
## Tests 1. Python stdlib
2. Third-party (`homeassistant.*`, `aiohttp`, etc.)
3. Local (`.api`, `.const`, etc.)
This integration does **not include automated tests** by default. **Error handling best practices:**
> ⚠️ If Copilot generates tests, keep them minimal and **do not introduce new test frameworks** not already present. - Keep try blocks minimal - only wrap code that can throw exceptions
- Process data **after** the try/except block, not inside
- Catch specific exceptions, avoid bare `except Exception:` (allowed only in config flows and background tasks)
- Use `ConfigEntryNotReady` for temporary failures (device offline)
- Use `ConfigEntryAuthFailed` for auth issues
- Use `ServiceValidationError` for user input errors in services
**Logging guidelines:**
- Use lazy logging: `_LOGGER.debug("Message with %s", variable)`
- No periods at end of log messages
- No integration name in messages (added automatically)
- Debug level for non-user-facing messages
**Function organization:**
Public entry points → direct helpers (call order) → pure utilities. Prefix private helpers with `_`.
**No backwards compatibility code** unless explicitly requested. Target latest HA stable only.
**Translation sync:** When updating `/translations/en.json`, update ALL language files (`de.json`, etc.) with same keys (placeholder values OK).
## Common Tasks
**Add a new sensor:**
1. Define entity description in `sensor.py` (add to `SENSOR_TYPES`)
2. Add translation keys to `/translations/en.json` and `/custom_translations/en.json`
3. Sync all language files
4. Implement `@property` methods in `TibberPricesSensor` class
**Modify price calculations:**
Edit `price_utils.py` or `average_utils.py`. These are stateless pure functions operating on price lists.
**Add a new service:**
1. Define schema in `services.py` (top-level constants)
2. Add service definition to `services.yaml`
3. Implement handler function in `services.py`
4. Register in `async_setup_services()`
**Change update intervals:**
Edit `UPDATE_INTERVAL` in `coordinator.py` (default: 15 min) or `QUARTER_HOUR_BOUNDARIES` for entity refresh timing.
**Debug GraphQL queries:**
Check `api.py` → `QueryType` enum and `_build_query()` method. Queries are dynamically constructed based on operation type.
## Anti-Patterns to Avoid
**Never do these:**
```python
# ❌ Blocking operations in event loop
data = requests.get(url) # Use aiohttp with async_get_clientsession(hass)
time.sleep(5) # Use await asyncio.sleep(5)
# ❌ Processing data inside try block
try:
data = await api.get_data()
processed = data["value"] * 100 # Move outside try
self._attr_native_value = processed
except ApiError:
pass
# ❌ Hardcoded strings (not translatable)
self._attr_name = "Temperature Sensor" # Use translation_key instead
# ❌ Accessing hass.data directly in tests
coord = hass.data[DOMAIN][entry.entry_id] # Use proper fixtures
# ❌ User-configurable polling intervals
vol.Optional("scan_interval"): cv.positive_int # Not allowed, integration determines this
```
**Do these instead:**
```python
# ✅ Async operations
data = await session.get(url)
await asyncio.sleep(5)
# ✅ Process after exception handling
try:
data = await api.get_data()
except ApiError:
return
processed = data["value"] * 100 # Safe processing after try/except
# ✅ Translatable entities
_attr_has_entity_name = True
_attr_translation_key = "temperature_sensor"
# ✅ Proper test setup with fixtures
@pytest.fixture
async def init_integration(hass, mock_config_entry):
mock_config_entry.add_to_hass(hass)
await hass.config_entries.async_setup(mock_config_entry.entry_id)
return mock_config_entry
```