refactoring

.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.
+-   Follow the **latest official practices** from Home Assistant and HACS.
--   This component must be compatible with the **latest Home Assistant release**.
+-   Ensure compatibility 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.
+-   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** where applicable.
+-   Use **async functions**, **non-blocking I/O**, and **config flows** when applicable.
--   Structure the component with the expected files: `__init__.py`, `manifest.json`, `config_flow.py` (if needed), and versioning compatible with HACS.
+-   Structure the component using standard files: `__init__.py`, `manifest.json`, `config_flow.py` (if needed), and proper versioning.
--   Make use of **Home Assistant's built-in libraries** for common tasks (e.g., `asyncio`, `aiohttp`, `homeassistant.helpers`, `homeassistant.util`).
+-   Use **Home Assistant built-in libraries and helpers** whenever possible:
--   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).
+    -   For dates: use `homeassistant.util.dt` (`dt_util`)
--   Avoid using **custom libraries** unless absolutely necessary.
+    -   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**.
+-   Follow **PEP8** and Home Assistant's coding conventions
--   Use **type hints** for all function signatures.
+-   Use **type hints** for all function and method signatures
--   Include **docstrings** for all public classes and methods.
+-   Add **docstrings** to all public classes and public methods
--   Prefer **f-strings** over `%` or `.format()` for string formatting.
+-   Use **f-strings** for formatting, not `%` or `.format()`
--   Avoid placeholder or mock data unless explicitly required.
+-   Use **relative paths** and **configurable options**, not hardcoded values
--   Never assume hardcoded paths or local setups — use **relative paths** and **configurable options**.
+-   Provide valid and clean YAML examples when needed (e.g., for `configuration.yaml`)
--   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:
+Follow this standard order within Python modules:
 
 1. **Imports**
 
-    - Standard library imports
+    - Python standard library imports
-    - Third-party libraries (e.g., `homeassistant.*`)
+    - Third-party libraries (`homeassistant.*`)
-    - Local module imports (`from . import xyz`)
+    - Local imports (`from . import xyz`)
-    - Use `isort` to enforce this automatically
+    - 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)
+    - Core classes first: entity classes, coordinators, config flows
-    - Within each class:
+    - Method order within each class:
-        - Public methods first, ordered by importance or typical usage
+        - Special methods (`__init__`, `__str__`) first
-        - Then private methods (prefix with `_`)
+        - Public methods (no `_` prefix), in logical order of usage
-        - Special methods (`__init__`, `__str__`, etc.) at the top of the class
+        - 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
+-   Use `async def` for I/O or Home Assistant lifecycle methods
--   Split large modules into separate files for clarity
+-   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:
+-   Use **Ruff**, which runs:
-    -   Locally in the **devcontainer** (VS Code or Cursor)
+
-    -   Remotely via **GitHub Actions**
+    -   Locally in the devcontainer (VS Code or Cursor)
--   Follow these key Ruff rules:
+    -   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`)
+    -   `SIM102` – Use `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
+-   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.
+> ✅ Copilot tip: Generate clean, single-pass functions with clear returns. Don’t leave unused code.
--   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.
 
 ## 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.