hass.tibber_prices/.github/copilot-instructions.md

Copilot Instructions

This repository contains a Home Assistant custom integration providing Tibber electricity price information and ratings, distributed via HACS.

Repository Overview

• Type: Home Assistant Custom Integration (~5,100 lines Python)
• Language: Python 3.13, async/await
• Framework: Home Assistant 2025.10.0+
• Main Components: Sensors, Binary Sensors, Services, Config Flow, Data Coordinator
• Testing: pytest with pytest-homeassistant-custom-component (7 test files)

Build, Lint, and Test Commands

Setup (ALWAYS Run First)

scripts/setup  # Installs dependencies

Note: homeassistant>=2025.10.0 may not be in PyPI. Use devcontainer for full environment.

Linting (ALWAYS Run Before Commit)

scripts/lint  # Runs: ruff format . && ruff check . --fix

• CI enforces via .github/workflows/lint.yml (runs ruff format --check and ruff check)
• CI will fail if linting errors exist
• Key rules: F401, F841, E402, E501, C901, PLR0912/15/11, RET504, B008, T201, SIM102
• Line length: 120 chars (see .ruff.toml)

Testing

pytest tests/  # Run all tests
pytest tests/test_price_utils.py  # Run specific test

Tests in tests/ directory cover price utilities, coordinator, midnight turnover, services.

CI Validation

Two workflows run on push/PR:

1. validate.yml: hassfest (HA manifest validation) + HACS validation
2. lint.yml: Ruff format + lint checks

Replicate CI locally: Run scripts/lint – if it passes, CI will pass.

Development Environment

Use VS Code devcontainer (.devcontainer/devcontainer.json):

• Python 3.13, auto-runs scripts/setup
• Home Assistant on port 8123
• Start: scripts/develop (runs hass --config ./config --debug)

Development Guidelines

• Follow developers.home-assistant.io
• Use async functions, non-blocking I/O, config flows
• Standard files: __init__.py, manifest.json, config_flow.py, sensor.py, const.py
• Use HA helpers: homeassistant.helpers.entity, device_registry, dt_util
• Don't wrap built-ins, avoid third-party libs, no static file paths

Coding Style

• PEP8 via Black, isort, Ruff
• Type hints + docstrings on all public methods
• F-strings for formatting
• Use _LOGGER, not print()

Module Structure Order

1. Imports (stdlib → third-party → local)
2. Module constants/globals
3. Top-level functions (public → helpers → utilities)
4. Main classes (Entity, Coordinator, ConfigFlow)
5. Helper classes (or move to separate modules)

Code Comments Policy

• No comments for automated changes (reordering, renaming, compliance)
• Comments only for logic/purpose/usage
• Explanations go in PR/commit messages, not code

Backwards Compatibility Policy

• Do not add compatibility layers unless explicitly requested
• Target latest stable HA version only

Translations Policy

• User-facing strings in translations/en.json and other translations/*.json
• All translation files must sync – update all languages when adding/changing keys
• custom_translations/ for supplemental strings not in standard HA format
• Never duplicate keys between translations/ and custom_translations/
• Standard translations take priority over custom

Project Layout

/
├── .github/workflows/          # CI: lint.yml, validate.yml
├── .devcontainer/              # VS Code dev container
├── custom_components/tibber_prices/  # Main code (5,100 lines)
│   ├── __init__.py (115)       # Entry point
│   ├── const.py (473)          # Constants
│   ├── api.py (850)            # Tibber API client
│   ├── coordinator.py (536)    # Data coordinator
│   ├── sensor.py (859)         # Sensor platform
│   ├── binary_sensor.py (693)  # Binary sensors
│   ├── config_flow.py (494)    # UI config
│   ├── services.py (639)       # Custom services
│   ├── price_utils.py (291)    # Price calculations
│   ├── services.yaml           # Service definitions
│   ├── translations/           # Standard HA translations (en, de)
│   └── custom_translations/    # Supplemental translations
├── config/configuration.yaml   # Dev HA config
├── scripts/
│   ├── setup                   # Install deps
│   ├── lint                    # Ruff format & check
│   └── develop                 # Start HA
├── tests/                      # pytest suite (7 files)
├── .ruff.toml                  # Linting config
├── pyproject.toml              # Black/isort config
├── requirements.txt            # Dependencies
└── hacs.json                   # HACS metadata

Configuration Files

• .ruff.toml: Python 3.13, line length 120, ALL rules with selective ignores
• pyproject.toml: Black/isort (line length 120)
• .editorconfig: 4-space indent, LF, UTF-8
• manifest.json: domain, version, requirements (aiofiles>=23.2.1), IoT class
• hacs.json: HA 2025.10.0+, HACS 2.0.1+

Architecture

• Data Flow: API → Coordinator → Sensors/Binary Sensors
• Storage: HA Storage API for caching
• Update: Polling (cloud_polling)
• Services: get_price, get_apexcharts_data, get_apexcharts_yaml, refresh_user_data

Common Tasks

• Add sensor: Edit sensor.py/binary_sensor.py + translation keys
• Modify API: Edit api.py (GraphQL queries)
• Price calculations: Edit price_utils.py
• Translations: Sync all files in translations/ and custom_translations/
• Add service: Edit services.py + services.yaml

Linting Rules (Ruff)

Key enforced rules:

• F401, F841: No unused imports/variables
• E402: Imports at top
• E501: Lines ≤120 chars
• C901, PLR0912, PLR0915: Simple functions
• PLR0911, RET504: No redundant else after return
• B008: No mutable defaults
• T201: No print()
• SIM102: Prefer if x over if x == True

Optional Files

Only create if needed: services.yaml, translations/*.json, binary_sensor.py, diagnostics.py. Avoid Core-only files: device_action.py, device_trigger.py, strings.json.

Important Notes

• Only dependency: aiofiles>=23.2.1
• No pip install HA: Use devcontainer
• Git ignore: __pycache__, .pytest*, .ruff_cache, config/* (except configuration.yaml)
• Trust these instructions: Only search if incomplete or incorrect