From 990bf2e1307d3f8b3e9e57ee7ea02361d63b0d91 Mon Sep 17 00:00:00 2001 From: Julian Pawlowski Date: Tue, 20 May 2025 19:44:27 +0000 Subject: [PATCH] refactoring --- .github/copilot-instructions.md | 105 ++++++++++++++++---------------- 1 file changed, 54 insertions(+), 51 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 546a29c..cf5955e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,89 +4,92 @@ 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 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. -- Make use of **Home Assistant's built-in libraries** for common tasks (e.g., `asyncio`, `aiohttp`, `homeassistant.helpers`, `homeassistant.util`). -- Do not create redundant wrapper functions around Home Assistant's built-in utilities or standard Python libraries. Use Home Assistant utilities directly (e.g., use `dt_util.parse_datetime` instead of wrapping it). -- Avoid using **custom libraries** unless absolutely necessary. +- 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 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. +- 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 -To ensure readability and consistency, follow this recommended structure within each Python module: +Follow this standard order within Python modules: 1. **Imports** - - Standard library imports - - Third-party libraries (e.g., `homeassistant.*`) - - Local module imports (`from . import xyz`) - - Use `isort` to enforce this automatically + - Python standard library imports + - Third-party libraries (`homeassistant.*`) + - Local imports (`from . import xyz`) + - Use `isort` to enforce order 2. **Module-level constants and globals** - - e.g., `DOMAIN`, `_LOGGER`, `CONF_*` + - Example: `DOMAIN`, `_LOGGER`, `CONF_*`, `DEFAULT_*` 3. **Top-level functions** - - Use only if necessary and not part of a class + - Only define if they are 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 + - 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 below main classes or move to a separate module if large + - Place after main classes, or move to separate modules if complex -- Use `async def` for all I/O-bound functions and Home Assistant callbacks -- Split large modules into separate files for clarity +- Use `async def` for I/O or Home Assistant lifecycle methods +- Split large files into multiple modules if needed -> ✅ Tip for Copilot: Public before private. Group logically. Favor readability over cleverness. +> ✅ 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 -- 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: +- 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 chars + - `E402`, `E501` – Imports at top, lines ≤88 characters - `C901`, `PLR0912`, `PLR0915` – Keep functions small and simple - - `PLR0911`, `RET504` – Avoid redundant returns and `else` after `return` + - `PLR0911`, `RET504` – Avoid unnecessary `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 + - `SIM102` – Use `if x`, not `if x == True` -## Additional Notes +- 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 -- 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. +> ✅ Copilot tip: Generate clean, single-pass functions with clear returns. Don’t leave unused code. ## Tests -This project does **not currently include automated tests**. Simplicity and fast iteration are prioritized over test coverage at this stage. +This project does **not include automated tests**. -> ⚠️ If you generate tests, keep them minimal and **do not introduce testing frameworks or infrastructure** that are not already present in the project. +> ⚠️ If generating tests, keep them minimal and avoid introducing test frameworks not already present.