From 39f426cd9760b83c9af62c1ed4f6dc0333094117 Mon Sep 17 00:00:00 2001 From: Julian Pawlowski Date: Tue, 20 May 2025 18:53:22 +0000 Subject: [PATCH] update --- .github/copilot-instructions.md | 93 +++++++++++++++++++++++---------- 1 file changed, 66 insertions(+), 27 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b572ed7..a7b3297 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,42 +4,81 @@ This repository contains a **custom component for Home Assistant**, intended to ## Development Guidelines -- Follow the **latest development practices** from both Home Assistant and HACS. -- This component is actively maintained and must be compatible with the **latest Home Assistant release**. -- When working with dates or time references, always use the **current real-world date** and assume it is fetched from the internet — never use outdated or static values from training data. -- Use **async functions**, **non-blocking I/O**, and **config flows** where applicable. -- Ensure the component is structured with proper files: `__init__.py`, `manifest.json`, `config_flow.py` (if needed), and versioning compatible with HACS. +- Follow the **latest development practices** from both Home Assistant and HACS. +- This component must be compatible with the **latest Home Assistant release**. +- When working with dates or time references, always use the **current real-world date** and assume it is fetched from the internet — never use outdated or static values from training data. +- Use **async functions**, **non-blocking I/O**, and **config flows** where applicable. +- Structure the component with the expected files: `__init__.py`, `manifest.json`, `config_flow.py` (if needed), and versioning compatible with HACS. ## Coding Style -- Follow **PEP8** and Home Assistant's coding conventions. -- Use **type hints** and include **docstrings** for all public classes and methods. -- Prefer **f-strings** for string formatting over `%` or `.format()`. +- Follow **PEP8** and the official **Home Assistant coding conventions**. +- Use **type hints** for all function signatures. +- Include **docstrings** for all public classes and methods. +- Prefer **f-strings** over `%` or `.format()` for string formatting. +- Avoid placeholder or mock data unless explicitly required. +- Never assume hardcoded paths or local setups — use **relative paths** and **configurable options**. +- YAML examples must be valid and formatted correctly for use in Home Assistant. + +## Code Structure and Ordering + +To ensure readability and consistency, follow this recommended structure within each Python module: + +1. **Imports** + + - Standard library imports + - Third-party libraries (e.g., `homeassistant.*`) + - Local module imports (`from . import xyz`) + - Use `isort` to enforce this automatically + +2. **Module-level constants and globals** + + - e.g., `DOMAIN`, `_LOGGER`, `CONF_*` + +3. **Top-level functions** + + - Use only if necessary and not part of a class + +4. **Main classes** + + - Core classes come first (e.g., entity platforms, config flows, coordinators) + - Within each class: + - Public methods first, ordered by importance or typical usage + - Then private methods (prefix with `_`) + - Special methods (`__init__`, `__str__`, etc.) at the top of the class + +5. **Helper classes** + - Place below main classes or move to a separate module if large + +- Use `async def` for all I/O-bound functions and Home Assistant callbacks +- Split large modules into separate files for clarity + +> ✅ Tip for Copilot: Public before private. Group logically. Favor readability over cleverness. ## Linting and Code Quality -- Code must be clean and compliant with **Ruff**, which runs: - - **Locally** in the **devcontainer** (VS Code or Cursor) - - **Remotely** via **GitHub Actions** -- Follow these key Ruff rules: - - `F401`, `F841` – No unused imports or variables - - `E402`, `E501` – Imports at top, lines ≤88 chars - - `C901`, `PLR0912`, `PLR0915` – Keep functions small and simple - - `PLR0911`, `RET504` – Avoid redundant returns and `else` after `return` - - `B008` – No mutable default arguments - - `T201` – Use `_LOGGER`, not `print()` - - `SIM102` – Use direct conditions (`if x`, not `if x == True`) -- Prefer a **single return statement** at the end of a function for clarity - (prepare the return value first, then return it once) -- Avoid returning early unless it clearly improves readability -- Use **Black** for formatting and **isort** for import sorting -- See `.ruff.toml` for detailed settings +- Code must be clean and compliant with **Ruff**, which runs: + - Locally in the **devcontainer** (VS Code or Cursor) + - Remotely via **GitHub Actions** +- Follow these key Ruff rules: + - `F401`, `F841` – No unused imports or variables + - `E402`, `E501` – Imports at top, lines ≤88 chars + - `C901`, `PLR0912`, `PLR0915` – Keep functions small and simple + - `PLR0911`, `RET504` – Avoid redundant returns and `else` after `return` + - `B008` – No mutable default arguments + - `T201` – Use `_LOGGER`, not `print()` + - `SIM102` – Use direct conditions (`if x`, not `if x == True`) +- Prefer a **single return statement** at the end of a function + (prepare the return value first, then return it once) +- Avoid returning early unless it clearly improves readability +- Use **Black** for code formatting and **isort** for import sorting +- See `.ruff.toml` for detailed settings ## Additional Notes -- Avoid generating placeholder or mock data unless explicitly required. -- Don’t assume hardcoded paths or specific local setups – use **relative paths** and **configurable options**. -- YAML examples should be valid and properly formatted for use in Home Assistant configs. +- Avoid generating placeholder or mock data unless explicitly required. +- Don’t assume hardcoded paths or specific local setups – use **relative paths** and **configurable options**. +- YAML examples should be valid and properly formatted for use in Home Assistant configs. > ✅ Tip for Copilot: Generate clean, modular, and lint-compliant code from the start to minimize review and CI errors.