bandsaunter/bandsaunter/sensors.py

"""What each sensor is called, which is the only thing the sensor cannot say.

A weather sensor broadcasts an identity -- fourteen bits on a tower sensor,
eight on a 609 -- and that identity is a number drawn at random in a factory,
or redrawn at random the next time somebody changes the batteries.  It is
enough to tell one sensor from another and it is no use at all for telling
which is which: 1A2B is not a place.

So this keeps a small file saying that 1A2B is the back fence.  It is the
only part of the weather section that holds anything a person typed, which
makes it the only part worth being careful with:

* Names are written the moment they are given, not when the program exits.
  A listening session ends when the operator gets bored and presses
  control-C, and a file that only reached the disk on a clean shutdown would
  lose exactly the names that had just been thought of.

* Writing is done to a neighbouring file which is then renamed over the old
  one, so that a machine losing power halfway through leaves either the old
  names or the new ones and never half of each.

* Nothing is ever removed for being stale.  A sensor whose battery ran out
  two winters ago keeps its name, because the alternative is that putting a
  battery back in loses it.

The file is YAML with one entry per sensor, meant to be opened and edited by
hand -- it is a list of things in a garden, and typing them is often quicker
than tagging them one at a time off the air.
"""

from __future__ import annotations

import os
import time
from dataclasses import asdict, dataclass, field
from pathlib import Path

import yaml

__all__ = ["Sensor", "SensorBook", "names_path", "UNHEARD"]

# The family part of the key given to a sensor named before it has been
# heard.  Nobody knows yet which model it is -- that is in the message, and
# there has not been one -- so the name waits under this until there is.
UNHEARD = "?"


@dataclass
class Sensor:
    """One sensor: what it calls itself, and what its owner calls it."""

    key: str = ""                  # family and identity: "tower/1A2B"
    name: str = ""                 # what a person calls it
    note: str = ""                 # anything else worth remembering
    model: str = ""                # what it said it was, when last heard
    channel: str = ""              # the switch position, when last heard
    first_heard: float = 0.0
    last_heard: float = 0.0
    messages: int = 0

    @property
    def sensor(self) -> str:
        """The identity on its own, without the family in front of it."""
        return self.key.split("/", 1)[-1]

    @property
    def family(self) -> str:
        return self.key.split("/", 1)[0] if "/" in self.key else ""

    @property
    def named(self) -> bool:
        return bool(self.name.strip())

    def label(self) -> str:
        """What to put at the front of a line about this sensor.

        The name where there is one, because that is what the person watching
        is looking for; the identity where there is not, because that is all
        there is and pretending otherwise would make two nameless sensors
        look like one.
        """
        return self.name.strip() or self.sensor

    def describe(self) -> str:
        bits = [self.label()]
        if self.named:
            bits.append(f"({self.sensor})")
        if self.model:
            bits.append(self.model)
        if self.channel:
            bits.append(f"ch {self.channel}")
        return "  ".join(bits)


def names_path(directory=None) -> Path:
    from .config import DEFAULT_CONFIG_DIR

    return Path(directory or DEFAULT_CONFIG_DIR) / "sensors.yaml"


class SensorBook:
    """Every sensor ever heard, and whatever it has been called.

    Two jobs, deliberately in one place.  It remembers the names, and it
    remembers when each sensor was last heard and how often -- because the
    second is what makes the first usable: a list of eleven identities is
    unnameable, and a list of eleven identities with "last heard four
    seconds ago" beside one of them is a sensor somebody can walk out and
    look at.
    """

    def __init__(self, path=None, directory=None):
        self.path = Path(path) if path is not None else names_path(directory)
        self.sensors: dict[str, Sensor] = {}
        self.dirty = False
        self.load()

    # -- the file ---------------------------------------------------------
    def load(self) -> "SensorBook":
        """Read the names.  A file with a mistake in it costs no names.

        A broken file is not an error here for the same reason it is not one
        anywhere else in this program: it is hand-edited, the mistake is
        usually one line of it, and refusing to listen to the weather because
        of a stray colon would be the wrong trade.  What is unreadable is
        left alone rather than overwritten, so the mistake can be found.
        """
        self.sensors = {}
        try:
            body = yaml.safe_load(self.path.read_text(encoding="utf8")) or {}
        except (OSError, ValueError, yaml.YAMLError):
            return self
        entries = body.get("sensors") if isinstance(body, dict) else body
        if not isinstance(entries, list):
            return self
        known = set(Sensor().__dict__)
        for entry in entries:
            if not isinstance(entry, dict) or not entry.get("key"):
                continue
            sensor = Sensor()
            for field_name, value in entry.items():
                if field_name in known and value is not None:
                    try:
                        setattr(sensor, field_name,
                                type(getattr(sensor, field_name))(value))
                    except (TypeError, ValueError):
                        pass
            self.sensors[sensor.key] = sensor
        return self

    def save(self) -> Path:
        """Write the names, whole or not at all."""
        self.path.parent.mkdir(parents=True, exist_ok=True)
        body = {"sensors": [asdict(s) for s in self.ordered()]}
        beside = self.path.with_name(self.path.name + ".new")
        with open(beside, "w", encoding="utf8") as fh:
            fh.write("# What each weather sensor is called.  Edit the names "
                     "freely; the rest is\n# filled in from what was heard "
                     "and will be overwritten.\n")
            yaml.safe_dump(body, fh, sort_keys=False, allow_unicode=True,
                           default_flow_style=False)
        os.replace(beside, self.path)
        self.dirty = False
        return self.path

    # -- what is in it ----------------------------------------------------
    def __len__(self) -> int:
        return len(self.sensors)

    def __contains__(self, key: str) -> bool:
        return key in self.sensors

    def get(self, key: str) -> Sensor | None:
        return self.sensors.get(key)

    def name_for(self, key: str) -> str:
        sensor = self.sensors.get(key)
        return sensor.name if sensor is not None else ""

    def label_for(self, key: str) -> str:
        sensor = self.sensors.get(key)
        return sensor.label() if sensor is not None else key.split("/")[-1]

    def ordered(self) -> list[Sensor]:
        """Named ones first, then by how recently they were heard.

        The named ones are at the top because they are the ones being
        watched; the nameless ones are sorted by when they were last heard
        because that is the order in which somebody would want to name them.
        """
        return sorted(self.sensors.values(),
                      key=lambda s: (not s.named, -s.last_heard, s.key))

    def unnamed(self) -> list[Sensor]:
        return [s for s in self.ordered() if not s.named]

    def find(self, text: str) -> list[Sensor]:
        """Sensors matching what somebody typed: a key, a name, or an id.

        An exact match on the key or the identity wins outright, so that
        naming a sensor whose identity happens to read like a word does not
        turn into a list of everything else in the garden.
        """
        wanted = (text or "").strip().lower()
        if not wanted:
            return []
        exact = [s for s in self.ordered()
                 if wanted in (s.key.lower(), s.sensor.lower(),
                               s.name.strip().lower())]
        if exact:
            return exact
        return [s for s in self.ordered()
                if wanted in s.key.lower() or wanted in s.name.lower()
                or wanted in s.note.lower()]

    # -- changing it ------------------------------------------------------
    def heard(self, reading, when: float = 0.0) -> Sensor:
        """Note one reception.  Returns the sensor it belonged to.

        This does not save.  A sensor reports every sixteen seconds and there
        may be a dozen of them, and rewriting the file for each would be a
        few thousand writes an hour to record nothing a person typed.  The
        counts are saved when the listening stops, and the names -- which are
        the part that matters -- are saved the moment they are given.
        """
        key = getattr(reading, "key", "") or ""
        sensor = self.sensors.get(key) or self._claim(key)
        if sensor is None:
            sensor = self.sensors[key] = Sensor(key=key)
        at = when or getattr(reading, "at", 0.0) or time.time()
        sensor.first_heard = sensor.first_heard or at
        sensor.last_heard = max(sensor.last_heard, at)
        sensor.messages += 1
        sensor.model = getattr(reading, "model", "") or sensor.model
        sensor.channel = getattr(reading, "channel", "") or sensor.channel
        self.dirty = True
        return sensor

    def _claim(self, key: str) -> Sensor | None:
        """Hand a waiting name to the sensor it turns out to belong to.

        Somebody who knows there is a sensor on the shed can name it before
        it has ever been received, and that name is filed under the identity
        alone because nothing yet knows which model it is.  The first message
        from it says, and this is the moment the name moves across -- so the
        display says "shed" from the first reception rather than listing the
        shed and the sensor on it as two separate things.
        """
        identity = key.split("/", 1)[-1]
        waiting = self.sensors.pop(f"{UNHEARD}/{identity}", None)
        if waiting is None:
            return None
        waiting.key = key
        self.sensors[key] = waiting
        self.dirty = True
        return waiting

    def tag(self, key: str, name: str, note: str | None = None,
            save: bool = True) -> Sensor:
        """Give a sensor a name, and put it on the disk straight away."""
        sensor = self.sensors.get(key)
        if sensor is None:
            sensor = self.sensors[key] = Sensor(key=key)
        sensor.name = (name or "").strip()
        if note is not None:
            sensor.note = note.strip()
        self.dirty = True
        if save:
            self.save()
        return sensor

    def forget(self, key: str, save: bool = True) -> bool:
        """Remove a sensor entirely.  Returns whether there was one."""
        if key not in self.sensors:
            return False
        del self.sensors[key]
        self.dirty = True
        if save:
            self.save()
        return True

    def flush(self) -> Path | None:
        """Save if anything has changed since the last write."""
        return self.save() if self.dirty else None