update

.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.
+-   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**.
+-   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.
+-   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.
+-   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.
+-   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.
+-   Follow **PEP8** and the official **Home Assistant coding conventions**.
-- Use **type hints** and include **docstrings** for all public classes and methods.
+-   Use **type hints** for all function signatures.
-- Prefer **f-strings** for string formatting over `%` or `.format()`.
+-   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:
+-   Code must be clean and compliant with **Ruff**, which runs:
-  - **Locally** in the **devcontainer** (VS Code or Cursor)
+    -   Locally in the **devcontainer** (VS Code or Cursor)
-  - **Remotely** via **GitHub Actions**
+    -   Remotely via **GitHub Actions**
-- Follow these key Ruff rules:
+-   Follow these key Ruff rules:
-  - `F401`, `F841` – No unused imports or variables
+    -   `F401`, `F841` – No unused imports or variables
-  - `E402`, `E501` – Imports at top, lines ≤88 chars
+    -   `E402`, `E501` – Imports at top, lines ≤88 chars
-  - `C901`, `PLR0912`, `PLR0915` – Keep functions small and simple
+    -   `C901`, `PLR0912`, `PLR0915` – Keep functions small and simple
-  - `PLR0911`, `RET504` – Avoid redundant returns and `else` after `return`
+    -   `PLR0911`, `RET504` – Avoid redundant returns and `else` after `return`
-  - `B008` – No mutable default arguments
+    -   `B008` – No mutable default arguments
-  - `T201` – Use `_LOGGER`, not `print()`
+    -   `T201` – Use `_LOGGER`, not `print()`
-  - `SIM102` – Use direct conditions (`if x`, not `if x == True`)
+    -   `SIM102` – Use direct conditions (`if x`, not `if x == True`)
-- Prefer a **single return statement** at the end of a function for clarity
+-   Prefer a **single return statement** at the end of a function
-  (prepare the return value first, then return it once)
+    (prepare the return value first, then return it once)
-- Avoid returning early unless it clearly improves readability
+-   Avoid returning early unless it clearly improves readability
-- Use **Black** for formatting and **isort** for import sorting
+-   Use **Black** for code formatting and **isort** for import sorting
-- See `.ruff.toml` for detailed settings
+-   See `.ruff.toml` for detailed settings
 
 ## Additional Notes
 
-- Avoid generating placeholder or mock data unless explicitly required.
+-   Avoid generating placeholder or mock data unless explicitly required.
-- Don’t assume hardcoded paths or specific local setups – use **relative paths** and **configurable options**.
+-   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.
+-   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.