Docstring Standards for aiohomematic¶

"""
{Brief one-line description}.

Overview
--------
{2-3 paragraphs explaining purpose, responsibilities, and design philosophy}

Public API
----------
{List of key classes/functions exposed by this module}
- ClassName: Brief description
- function_name: Brief description

Quick start
-----------
{Short code example or usage pattern}

Notes
-----
{Optional additional information, warnings, or related modules}
"""

"""
Central unit and core orchestration for Homematic CCU and compatible backends.

Overview
--------
This package provides the central coordination layer for aiohomematic. The
CentralUnit class manages client lifecycles, device creation, event handling,
and background tasks. It serves as the primary entry point for interacting
with Homematic systems.

Public API
----------
- CentralUnit: Main coordination class for managing all operations
- CentralConfig: Configuration dataclass for central initialization

Quick start
-----------
Typical usage is to create a CentralConfig, instantiate CentralUnit,
and call start():

    config = CentralConfig(name="ccu", host="192.168.1.100", ...)
    central = config.create_central()
    await central.start()
"""

"""
{Brief one-line description}.

{1-2 paragraphs with key details}

Key features:
- Feature 1
- Feature 2
- Feature 3
"""

"""
Device coordinator for managing device lifecycle and operations.

This module provides centralized device management including device creation,
registration, removal, and device-related operations. The DeviceCoordinator
works in conjunction with DeviceRegistry to maintain the runtime device model.

Key features:
- Device creation from descriptions
- Device registration and lookup
- Device removal and cleanup
- Device update operations
"""

"""
{Brief description of module purpose}.

Public API of this module is defined by __all__.
"""

"""
Constants used by aiohomematic.

Public API of this module is defined by __all__.
"""

class DeviceProvider(Protocol):
    """Protocol for providing access to device registry."""

class CentralInfo(Protocol):
    """Protocol for central system information."""

class BaseDataPoint(ABC):
    """
    Base class for all data point implementations.

    Subclasses must implement value property and update methods.
    """

class BasePersistentFile(ABC):
    """
    Base class for persistent file storage.

    Provides caching and serialization for device/paramset descriptions.
    """

class Device:
    """Represents a Homematic device with channels and data points."""

class CentralUnit:
    """Central orchestration unit for managing Homematic backend connections."""

class SchedulerJob:
    """Scheduled background task with interval-based execution."""

@dataclass
class CentralConfig:
    """Configuration for central unit initialization."""

@dataclass
class DeviceDescription:
    """Device metadata from backend."""

def get_device_by_address(self, address: str) -> Device | None:
    """Return device by address."""

@property
def is_connected(self) -> bool:
    """Return connection status."""

def clear_cache(self) -> None:
    """Clear all cached data."""

def create_device(
    self,
    *,
    interface_id: str,
    device_address: str,
    device_type: str,
    force_create: bool = False,
) -> Device:
    """
    Create and register a new device instance.

    Args:
        interface_id: Interface identifier (e.g., "hmip-rf")
        device_address: Unique device address
        device_type: Device type identifier
        force_create: Force creation even if device exists

    Returns:
        Created or existing Device instance.

    Raises:
        DeviceCreationException: If device creation fails.
    """

def __init__(self) -> None:
    """Initialize the coordinator."""

def __init__(
    self,
    *,
    central_info: CentralInfo,
    device_provider: DeviceProvider,
    client_provider: ClientProvider,
) -> None:
    """
    Initialize the device coordinator.

    Args:
        central_info: System information provider
        device_provider: Device registry access
        client_provider: Client lookup functionality
    """

def channel_address(value: str, /) -> str:
    """Validate channel address format."""

def positive_int(value: int, /) -> int:
    """Validate value is positive integer."""

def inspector[**P, R](
    func: Callable[P, R] | None = None,
    /,
    *,
    log_level: int = logging.ERROR,
    re_raise: bool = True,
    scope: ServiceScope = ServiceScope.EXTERNAL,
) -> Callable[[Callable[P, R]], Callable[P, R]] | Callable[P, R]:
    """
    Decorator for exception handling and performance measurement.

    Works with both sync and async functions. Can be used with or without
    parameters:
        @inspector
        @inspector(log_level=logging.DEBUG)
        @inspector(re_raise=False, service=ServiceScope.INTERNAL)

    Args:
        func: Function to decorate (when used without parameters)
        log_level: Logging level for exceptions
        re_raise: Whether to re-raise caught exceptions
        service: The scope of this service method (see ServiceScope enum).
            EXTERNAL: Methods for external consumers (HA) - user-invokable commands
                like turn_on, turn_off. Appears in service_method_names.
            INTERNAL: Infrastructure methods like load_data_point_value.
                Does NOT appear in service_method_names.

    Returns:
        Decorated function or decorator function.
    """

@property
def device_address(self) -> str:
    """Return the device address."""

@property
def available(self) -> bool:
    """Return whether device is available."""

@config_property
def value(self) -> Any:
    """Return current data point value."""

"""Tests for device coordinator functionality."""

class TestDeviceCoordinator:
    """Test suite for DeviceCoordinator."""

async def test_device_creation(factory):
    """Test device creation with valid parameters."""

def test_address_validation():
    """Test address validation with various inputs."""

"""Module for data points implemented using the sensor category"""

"""
Generic sensor data points.

Public API of this module is defined by __all__.
"""

def get_device(self, addr):
    """Gets device"""

def fetch_value(self, param):
    """Returns the value of param"""

def get_device(self, address: str) -> Device | None:
    """Return device by address."""

def fetch_value(self, parameter: str) -> Any:
    """Return parameter value."""

def __init__(self, central, addr, channel_no):
    """Init custom entity."""

def __init__(
    self,
    *,
    central: CentralUnit,
    device_address: str,
    channel_no: int,
) -> None:
    """
    Initialize custom climate entity.

    Args:
        central: Central unit instance
        device_address: Device address
        channel_no: Channel number
    """

# Bad: Type already in signature
def get_address(self) -> str:
    """Return the address as a string."""

# Good: Don't repeat types
def get_address(self) -> str:
    """Return the device address."""

# Bad: Adds no value
def process_data(self, data: dict[str, Any]) -> None:
    """Process the data."""

# Good: Explain what processing means
def process_data(self, data: dict[str, Any]) -> None:
    """Update device state from backend data."""

# Bad: Inconsistent
def get_device(self, address: str) -> Device:
    """Gets device."""

def return_channels(self) -> list[Channel]:
    """Returns channels."""

def fetch_value(self, param: str) -> Any:
    """Fetches value."""

# Good: Consistent imperative mood
def get_device(self, address: str) -> Device:
    """Return device by address."""

def return_channels(self) -> list[Channel]:
    """Return all device channels."""

def fetch_value(self, parameter: str) -> Any:
    """Return parameter value."""

# Bad: No period
def clear_cache(self) -> None:
    """Clear the cache"""

# Good: Always end with period
def clear_cache(self) -> None:
    """Clear the cache."""

"""Brief summary here.

Extended description continues here.
"""

"""Module docstring.

Notes
-----
Final section here.

"""

"""Initialize the coordinator."""  # ✓ Correct