mirror of
https://github.com/jpawlowski/hass.tibber_prices.git
synced 2026-03-30 05:13:40 +00:00
95 lines
3.8 KiB
Markdown
95 lines
3.8 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 **latest official practices** from Home Assistant and HACS.
|
||
- Ensure compatibility with the **latest Home Assistant release**.
|
||
- Always use the **current real-world date** when working with times or schedules — do not use hardcoded or outdated values.
|
||
- Use **async functions**, **non-blocking I/O**, and **config flows** when applicable.
|
||
- Structure the component using standard files: `__init__.py`, `manifest.json`, `config_flow.py` (if needed), and proper versioning.
|
||
- Use **Home Assistant built-in libraries and helpers** whenever possible:
|
||
- For dates: use `homeassistant.util.dt` (`dt_util`)
|
||
- For configs: use `homeassistant.helpers.config_validation`
|
||
- For state handling: use `homeassistant.helpers.entity`
|
||
- **Avoid wrapping built-in utilities** (e.g., do not wrap `dt_util.parse_datetime`)
|
||
- **Avoid using custom libraries** unless absolutely necessary and justified
|
||
|
||
## Coding Style
|
||
|
||
- Follow **PEP8** and Home Assistant's coding conventions
|
||
- Use **type hints** for all function and method signatures
|
||
- Add **docstrings** to all public classes and public methods
|
||
- Use **f-strings** for formatting, not `%` or `.format()`
|
||
- Use **relative paths** and **configurable options**, not hardcoded values
|
||
- Provide valid and clean YAML examples when needed (e.g., for `configuration.yaml`)
|
||
|
||
## Code Structure and Ordering
|
||
|
||
Follow this standard order within Python modules:
|
||
|
||
1. **Imports**
|
||
|
||
- Python standard library imports
|
||
- Third-party libraries (`homeassistant.*`)
|
||
- Local imports (`from . import xyz`)
|
||
- Use `isort` to enforce order
|
||
|
||
2. **Module-level constants and globals**
|
||
|
||
- Example: `DOMAIN`, `_LOGGER`, `CONF_*`, `DEFAULT_*`
|
||
|
||
3. **Top-level functions**
|
||
|
||
- Only define if they are not part of a class
|
||
|
||
4. **Main classes**
|
||
|
||
- Core classes first: entity classes, coordinators, config flows
|
||
- Method order within each class:
|
||
- Special methods (`__init__`, `__str__`) first
|
||
- Public methods (no `_` prefix), in logical order of usage
|
||
- Private methods (prefix `_`), grouped below public ones
|
||
|
||
5. **Helper classes**
|
||
- Place after main classes, or move to separate modules if complex
|
||
|
||
- Use `async def` for I/O or Home Assistant lifecycle methods
|
||
- Split large files into multiple modules if needed
|
||
|
||
> ✅ Copilot tip: Use public methods first, private methods after. Avoid mixing. Keep file structure consistent.
|
||
|
||
### Optional: Code Folding Regions
|
||
|
||
You may use `#region` and `#endregion` comments to group related logic. Only apply in large files and where folding improves clarity.
|
||
|
||
## Linting and Code Quality
|
||
|
||
- Use **Ruff**, which runs:
|
||
|
||
- Locally in the devcontainer (VS Code or Cursor)
|
||
- Remotely via GitHub Actions
|
||
|
||
- Required Ruff rules:
|
||
|
||
- `F401`, `F841` – No unused imports or variables
|
||
- `E402`, `E501` – Imports at top, lines ≤88 characters
|
||
- `C901`, `PLR0912`, `PLR0915` – Keep functions small and simple
|
||
- `PLR0911`, `RET504` – Avoid unnecessary `else` after `return`
|
||
- `B008` – No mutable default arguments
|
||
- `T201` – Use `_LOGGER`, not `print()`
|
||
- `SIM102` – Use `if x`, not `if x == True`
|
||
|
||
- Prefer a **single return statement** at the end of functions
|
||
- Avoid early returns unless they improve clarity
|
||
- Use **Black** for formatting and **isort** for sorting imports
|
||
- Refer to `.ruff.toml` for configuration details
|
||
|
||
> ✅ Copilot tip: Generate clean, single-pass functions with clear returns. Don’t leave unused code.
|
||
|
||
## Tests
|
||
|
||
This project does **not include automated tests**.
|
||
|
||
> ⚠️ If generating tests, keep them minimal and avoid introducing test frameworks not already present.
|