synthetic_home.inventory

  1"""Data model for the lower level inventory of a home, usable for fixtures and evaluations."""
  2
  3import pathlib
  4from dataclasses import dataclass, field
  5import logging
  6import slugify
  7from typing import Any
  8
  9import yaml
 10from mashumaro.mixins.yaml import DataClassYAMLMixin, EncodedData
 11from mashumaro.config import BaseConfig
 12from mashumaro.codecs.yaml import yaml_decode
 13
 14from . import common
 15from .exceptions import SyntheticHomeError
 16
 17__all__ = [
 18    "Inventory",
 19    "load_inventory",
 20    "Area",
 21    "Device",
 22    "Entity",
 23]
 24
 25_LOGGER = logging.getLogger(__name__)
 26
 27DEFAULT_SEPARATOR = "_"
 28
 29
 30def _custom_encoder(data: dict[str, Any]) -> EncodedData:
 31    return yaml.safe_dump(data, sort_keys=False, explicit_start=True)  # type: ignore[no-any-return]
 32
 33
 34@dataclass
 35class Area(DataClassYAMLMixin):
 36    """Represents an area in a home."""
 37
 38    name: str
 39    """The human readable name of the area e.g. 'Living Room'."""
 40
 41    id: str | None = None
 42    """The identifier of the area eg. 'living_room', unique within a Home."""
 43
 44    floor: str | None = None
 45    """The human readable name of the floor."""
 46
 47    def __post_init__(self) -> None:
 48        """Validate the area."""
 49        if self.id is None:
 50            self.id = slugify.slugify(self.name, separator=DEFAULT_SEPARATOR)
 51
 52    class Config(BaseConfig):
 53        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
 54        sort_keys = False
 55
 56
 57@dataclass
 58class Device(DataClassYAMLMixin):
 59    """Represents a devie within a home."""
 60
 61    name: str
 62    """The human readable name of the device e.g. 'Left Blind'."""
 63
 64    id: str | None = None
 65    """The identifier of the area eg. 'living_room_left_blind', unique within a Home."""
 66
 67    area: str | None = None
 68    """The area id of the home. e.g. 'living_room'"""
 69
 70    info: common.DeviceInfo | None = None
 71    """Detailed model information about the device."""
 72
 73    class Config(BaseConfig):
 74        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
 75        sort_keys = False
 76
 77    def __post_init__(self) -> None:
 78        """Validate the device."""
 79        if self.id is None:
 80            self.id = slugify.slugify(self.name, separator=DEFAULT_SEPARATOR)
 81
 82
 83@dataclass
 84class Entity(DataClassYAMLMixin):
 85    """Represents an entity within a home."""
 86
 87    name: str | None = None
 88    """The human readable name of the entity e.g. 'Outside rain sensor'. or omitted to use device naming."""
 89
 90    id: str | None = None
 91    """The identifier of the entity e.g. 'sensor.rain_sensor_intensity', unique within a Home."""
 92
 93    area: str | None = None
 94    """The area id within the home e.g. 'living_room'."""
 95
 96    device: str | None = None
 97    """The device id within the home e.g. 'living_room_left_blind'."""
 98
 99    state: str | None = None
100    """The current state value for the entity."""
101
102    attributes: common.NamedAttributes | None = None
103    """The current state attributes for the entity."""
104
105    def __post_init__(self) -> None:
106        """Validate the device."""
107        if self.id is None:
108            raise SyntheticHomeError("Entity {self.name} had no value for 'id'")
109
110    class Config(BaseConfig):
111        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
112        sort_keys = False
113
114
115@dataclass
116class Inventory(DataClassYAMLMixin):
117    """A fixture defines the entire definition of the home."""
118
119    language: str | None = None
120    """The default system language."""
121
122    areas: list[Area] = field(default_factory=list)
123    """The list of areas within the home."""
124
125    devices: list[Device] = field(default_factory=list)
126    """The list of devices within a home, which may be associated with areas."""
127
128    entities: list[Entity] = field(default_factory=list)
129    """The list of entities within a home, which may be associated with areas and devices."""
130
131    def yaml(self) -> str:
132        """Render the inventory as yaml."""
133        return str(self.to_yaml(omit_none=True, encoder=_custom_encoder))
134
135    @property
136    def floors(self) -> set[str]:
137        """Return the set of floors across all areas."""
138        return {area.floor for area in self.areas if area.floor is not None}
139
140    def device_dict(self) -> dict[str, Device]:
141        """Dictionary of devices by device id."""
142        return {device.id: device for device in self.devices if device.id is not None}
143
144    def area_dict(self) -> dict[str, Area]:
145        """Dictionary of areas by area id."""
146        return {area.id: area for area in self.areas if area.id is not None}
147
148    class Config(BaseConfig):
149        code_generation_options = ["TO_DICT_ADD_OMIT_NONE_FLAG"]
150        sort_keys = False
151
152
153def read_config_content(config_file: pathlib.Path) -> str:
154    """Create configuration file content, exposed for patching."""
155    with config_file.open("r") as f:
156        return f.read()
157
158
159def decode_inventory(content: str) -> Inventory:
160    """Load synthetic home configuration from disk."""
161    return yaml_decode(content, Inventory)
162
163
164def load_inventory(config_file: pathlib.Path) -> Inventory:
165    """Load synthetic home configuration from disk."""
166    try:
167        content = read_config_content(config_file)
168    except FileNotFoundError:
169        raise SyntheticHomeError(f"Configuration file '{config_file}' does not exist")
170    try:
171        return decode_inventory(content)
172    except ValueError as err:
173        raise SyntheticHomeError(f"Could not parse config file '{config_file}': {err}")