# 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.