mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-30 05:13:40 +00:00
147 lines
5.4 KiB
Markdown
147 lines
5.4 KiB
Markdown
# Copilot Instructions
|
||
|
||
This repository contains a **custom component for Home Assistant**, intended to be distributed via the **HACS (Home Assistant Community Store)**.
|
||
|
||
## Development Guidelines
|
||
|
||
- Follow the **official Home Assistant development guidelines** at [developers.home-assistant.io](https://developers.home-assistant.io).
|
||
- 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
|
||
- `manifest.json` – metadata and dependencies
|
||
- `config_flow.py` – if the integration supports UI configuration
|
||
- `sensor.py`, `switch.py`, etc. – for platforms
|
||
- `const.py` – constants (`DOMAIN`, `CONF_*`, etc.)
|
||
|
||
- Use Home Assistant's built-in helpers and utility modules:
|
||
|
||
- `homeassistant.helpers.entity`, `device_registry`, `config_validation`
|
||
- `homeassistant.util.dt` (`dt_util`) for time/date handling
|
||
|
||
- Do not wrap built-in functions (e.g., don’t wrap `dt_util.parse_datetime`)
|
||
- Avoid third-party or custom libraries unless absolutely necessary
|
||
- Never assume static local file paths — use config options and relative paths
|
||
|
||
## Coding Style
|
||
|
||
- Follow **PEP8**, enforced by **Black**, **isort**, and **Ruff**
|
||
- 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
|
||
|
||
Use the following order inside Python modules:
|
||
|
||
1. **Imports**
|
||
|
||
- Python standard library imports first
|
||
- Third-party imports (e.g., `homeassistant.*`)
|
||
- Local imports within this component (`from . import xyz`)
|
||
- Enforced automatically by `isort`
|
||
|
||
2. **Module-level constants and globals**
|
||
|
||
- Define constants and globals at module-level (e.g., `DOMAIN`, `_LOGGER`, `CONF_*`, `DEFAULT_*`)
|
||
|
||
3. **Top-level functions**
|
||
|
||
- Use only for stateless, reusable logic
|
||
- Prefix with `_` if internal only (e.g., `_parse_price()`)
|
||
- Do not place Home Assistant lifecycle logic here
|
||
|
||
4. **Main classes**
|
||
|
||
- Define main classes (Home Assistant Entity classes, DataUpdateCoordinators, and ConfigFlow handlers)
|
||
- Order inside class:
|
||
|
||
- Special methods (`__init__`, `__repr__`)
|
||
- Public methods (no `_`)
|
||
- Private methods (`_prefix`)
|
||
|
||
- All I/O or lifecycle methods must be `async def`
|
||
|
||
5. **Helper classes**
|
||
|
||
- If helper classes become complex, move them to separate modules (e.g., `helpers.py`, `models.py`)
|
||
|
||
> ✅ Copilot tip: Use top-level functions for pure helpers only. Prefer structured classes where Home Assistant expects them.
|
||
|
||
## Data Structures
|
||
|
||
Use `@dataclass` for plain data containers where appropriate:
|
||
|
||
```python
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class PriceSlot:
|
||
start: datetime
|
||
end: datetime
|
||
price: float
|
||
```
|
||
|
||
## Visual File Layout
|
||
|
||
Split component logic into multiple Python modules for improved clarity and maintainability:
|
||
|
||
```
|
||
/custom_components/your_component/
|
||
├── __init__.py
|
||
├── manifest.json
|
||
├── const.py
|
||
├── sensor.py
|
||
├── config_flow.py
|
||
├── models.py # dataclasses
|
||
├── helpers.py # pure utility functions
|
||
```
|
||
|
||
Use `#region` / `#endregion` optionally to improve readability in large files.
|
||
|
||
## Optional Files (Custom Integration via HACS)
|
||
|
||
Only create these files if explicitly required by your integration features. Not all files used in Core integrations apply to Custom Integrations:
|
||
|
||
- `services.yaml` – Define custom Home Assistant services
|
||
- `translations/*.json` (e.g., `en.json`, `de.json`) – Provide translations for UI elements
|
||
- 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.
|
||
|
||
## Linting and Code Quality
|
||
|
||
- Enforced by **Ruff**, which runs:
|
||
|
||
- Locally via VS Code devcontainer
|
||
- Remotely via GitHub Actions
|
||
|
||
Key Ruff linter rules that must be followed:
|
||
|
||
- `F401`, `F841` – No unused imports or variables
|
||
- `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:
|
||
|
||
- Use **Black** for formatting
|
||
- Use **isort** for import sorting
|
||
- See `.ruff.toml` for custom settings
|
||
- Prefer **one return statement per function** unless early returns improve clarity
|
||
|
||
## Tests
|
||
|
||
This integration does **not include automated tests** by default.
|
||
|
||
> ⚠️ If Copilot generates tests, keep them minimal and **do not introduce new test frameworks** not already present.
|