aiohomematic: Instructions file for GitHub Copilot

GitHub Copilot Instructions for aiohomematic

This document provides guidance for GitHub Copilot when working with the aiohomematic codebase.

Project Overview

aiohomematic is an async Python library for controlling Homematic and HomematicIP devices. It powers the Home Assistant integration "Homematic(IP) Local".

• Python Version: 3.14+
• Type Safety: Fully typed with mypy strict mode
• Async Framework: AsyncIO-based

Mandatory Code Standards

Required Import

Every Python file MUST start with:

from __future__ import annotations

Type Annotations

All code MUST be fully typed. mypy runs in strict mode.

# Correct
def get_device(self, address: str) -> Device | None:
    """Return device by address."""
    return self._devices.get(address)

# Incorrect - missing type annotations
def get_device(self, address):
    return self._devices.get(address)

Keyword-Only Arguments

Use keyword-only arguments for functions with multiple parameters:

def create_client(
    *,
    host: str,
    username: str,
    password: str,
    port: int = 2001,
) -> Client:
    """Create a new client."""
    ...

Docstrings

• End all docstrings with a period (.)
• Use imperative mood for functions/methods ("Return the device", not "Returns")
• Use declarative statements for classes ("Represents a device")

def get_value(self, parameter: str) -> Any:
    """Return the current parameter value."""

class Device:
    """Representation of a Homematic device."""

Import Order

from __future__ import annotations

# 1. Standard library
import asyncio
from collections.abc import Callable
from typing import TYPE_CHECKING

# 2. Third-party
import aiohttp

# 3. First-party
from aiohomematic.const import Interface

# 4. TYPE_CHECKING imports
if TYPE_CHECKING:
    from aiohomematic.central import CentralUnit

Architecture Guidelines

Protocol-Based Dependency Injection

Components use protocol interfaces for loose coupling: