bricklogger 0.2.0__tar.gz → 0.2.2__tar.gz

{bricklogger-0.2.0 → bricklogger-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bricklogger
-Version: 0.2.0
+Version: 0.2.2
 Summary: Data bridge for building automation: collects data based on a Brick model and writes it to time-series databases
 Keywords: brick,bacnet,building-automation,timescaledb,data-logger
 Author: Michael Rosenlund
@@ -82,8 +82,8 @@ The script brings its own Python, so the machine needs only `curl`. With
 `sudo` it installs a service: the program under `/opt/bricklogger`, the
 configuration in `/etc/bricklogger`, the data in `/var/lib/bricklogger` and
 three systemd units, left stopped. Without `sudo` everything stays in your home
-directory. `--version 0.2.0` installs a given version; options come after
-`--` when the script is piped: `… | sudo sh -s -- --version 0.2.0`.
+directory. `--version 0.2.2` installs a given version; options come after
+`--` when the script is piped: `… | sudo sh -s -- --version 0.2.2`.
 
 **As a container** the same program is `ghcr.io/cx1-aps/bricklogger`, with a
 compose file for the daemon, the web interface and the MCP server; see
@@ -149,8 +149,8 @@ sudo systemctl restart bricklogger           # the daemon reads plugins at start
 ```
 
 A plugin is a Python package that provides a source or a destination type. A
-plugin that cannot load stops nothing: its instances show as failed and the
-rest keep running. Writing one is described under
+plugin that cannot load, or is configured but not installed, stops nothing:
+its instances show as failed and the rest keep running. Writing one is described under
 [plugins](https://cx1-aps.github.io/bricklogger/features/plugins/).
 
 ## Mail notifications
@@ -167,17 +167,16 @@ See [notifications](https://cx1-aps.github.io/bricklogger/features/notifications
 
 ## Upgrade
 
-Run the install script again; it leaves the plugins, the configuration and the
-data where they are. Then restart the daemon. A container pulls the new image
-instead:
-
 ```bash
-curl -fsSL https://github.com/CX1-ApS/bricklogger/releases/latest/download/install.sh | sudo sh
-sudo systemctl restart bricklogger
+bricklogger update status        # what there is to upgrade
+sudo bricklogger update all      # Bricklogger and the plugins together
 ```
 
-After an upgrade to a new minor version, `bricklogger plugins` shows whether
-every plugin still loads.
+`update` checks the configuration with the new version before it restarts
+anything, and puts the previous versions back if it does not hold; the
+configuration and the data stay where they are. `update core` upgrades
+Bricklogger alone, `update <type>` one plugin. Running the install script
+again works too. A container pulls the new image instead.
 
 **Upgrading from 0.1 with an iBOS source:** iBOS is no longer built in. The
 `ibos` instance shows as failed until the plugin is added with

{bricklogger-0.2.0 → bricklogger-0.2.2}/README.md

@@ -37,8 +37,8 @@ The script brings its own Python, so the machine needs only `curl`. With
 `sudo` it installs a service: the program under `/opt/bricklogger`, the
 configuration in `/etc/bricklogger`, the data in `/var/lib/bricklogger` and
 three systemd units, left stopped. Without `sudo` everything stays in your home
-directory. `--version 0.2.0` installs a given version; options come after
-`--` when the script is piped: `… | sudo sh -s -- --version 0.2.0`.
+directory. `--version 0.2.2` installs a given version; options come after
+`--` when the script is piped: `… | sudo sh -s -- --version 0.2.2`.
 
 **As a container** the same program is `ghcr.io/cx1-aps/bricklogger`, with a
 compose file for the daemon, the web interface and the MCP server; see
@@ -104,8 +104,8 @@ sudo systemctl restart bricklogger           # the daemon reads plugins at start
 ```
 
 A plugin is a Python package that provides a source or a destination type. A
-plugin that cannot load stops nothing: its instances show as failed and the
-rest keep running. Writing one is described under
+plugin that cannot load, or is configured but not installed, stops nothing:
+its instances show as failed and the rest keep running. Writing one is described under
 [plugins](https://cx1-aps.github.io/bricklogger/features/plugins/).
 
 ## Mail notifications
@@ -122,17 +122,16 @@ See [notifications](https://cx1-aps.github.io/bricklogger/features/notifications
 
 ## Upgrade
 
-Run the install script again; it leaves the plugins, the configuration and the
-data where they are. Then restart the daemon. A container pulls the new image
-instead:
-
 ```bash
-curl -fsSL https://github.com/CX1-ApS/bricklogger/releases/latest/download/install.sh | sudo sh
-sudo systemctl restart bricklogger
+bricklogger update status        # what there is to upgrade
+sudo bricklogger update all      # Bricklogger and the plugins together
 ```
 
-After an upgrade to a new minor version, `bricklogger plugins` shows whether
-every plugin still loads.
+`update` checks the configuration with the new version before it restarts
+anything, and puts the previous versions back if it does not hold; the
+configuration and the data stay where they are. `update core` upgrades
+Bricklogger alone, `update <type>` one plugin. Running the install script
+again works too. A container pulls the new image instead.
 
 **Upgrading from 0.1 with an iBOS source:** iBOS is no longer built in. The
 `ibos` instance shows as failed until the plugin is added with

{bricklogger-0.2.0 → bricklogger-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bricklogger"
-version = "0.2.0"
+version = "0.2.2"
 description = "Data bridge for building automation: collects data based on a Brick model and writes it to time-series databases"
 readme = "README.md"
 license = "MIT"

{bricklogger-0.2.0 → bricklogger-0.2.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "bricklogger"
-version = "0.2.0"
+version = "0.2.2"
 description = "Data bridge for building automation: collects data based on a Brick model and writes it to time-series databases"
 readme = "README.md"
 license = "MIT"

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/__init__.py

@@ -14,4 +14,4 @@ The package is laid out after the architecture in ``docs/architecture.md``:
   external plugins.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/cli/__init__.py

@@ -24,6 +24,7 @@ from bricklogger.cli.plugins import plugins_app
 from bricklogger.cli.query import query_command
 from bricklogger.cli.roles import destinations_app, sources_app
 from bricklogger.cli.serve import serve_command
+from bricklogger.cli.update import update_app
 from bricklogger.config import resolve_config_dir
 
 app = typer.Typer(
@@ -96,6 +97,7 @@ app.add_typer(destinations_app, name="destinations")
 app.add_typer(rules_app, name="rules")
 app.add_typer(notify_app, name="notify")
 app.add_typer(plugins_app, name="plugins")
+app.add_typer(update_app, name="update")
 app.add_typer(model_app, name="model")
 app.command("query")(query_command)
 app.command("serve")(serve_command)

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/cli/daemon_commands.py

@@ -28,6 +28,7 @@ from bricklogger.ops.status import PID_FILE as PID_FILE
 from bricklogger.ops.status import probe
 from bricklogger.ops.status import process_alive as process_alive
 from bricklogger.ops.status import read_pid as read_pid
+from bricklogger.ops.updates import available_line
 
 daemon_app = typer.Typer(
     no_args_is_help=True,
@@ -363,6 +364,9 @@ def _echo_summary(data: dict[str, Any]) -> None:
     ]
     for row in data.get("instances", []):
         lines.append(f"  {row['role']} {row['name']} ({row['type']}): {row['state']}")
+    newer = available_line(data.get("updates"))
+    if newer is not None:
+        lines.append(newer)
     for line in lines:
         typer.echo(line)
 

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/cli/plugins.py

@@ -129,8 +129,8 @@ def remove_command(
 ) -> None:
     """Uninstall the distribution that provides a plugin type.
 
-    Refuses while an instance of the type is configured, unless --force; the
-    daemon would reject such a configuration at its next start.
+    Refuses while an instance of the type is configured, unless --force; from
+    the daemon's next start such an instance would be failed.
     """
     context = cli_context(ctx)
     try:

bricklogger-0.2.2/src/bricklogger/cli/update.py

@@ -0,0 +1,205 @@
+"""``bricklogger update``: what there is to upgrade, and the upgrade itself.
+
+``update status`` installs nothing. ``update core``, ``update all`` and
+``update TYPE`` upgrade from PyPI with the environment's own uv, validate with
+the new version, put the previous versions back when that fails, write the
+units again and restart what runs as a unit. ``update`` alone shows this help,
+as every group does. See ``docs/features/cli.md``, "update".
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+from rich.table import Table
+from typer.core import TyperGroup
+from typer.main import get_command as typer_command
+
+from bricklogger.cli.context import cli_context
+from bricklogger.cli.output import fail, print_json, stderr, stdout
+from bricklogger.ops.errors import OperationError
+from bricklogger.ops.updates import CORE, Updated, UpdateRefused, status, update
+
+NoRestart = Annotated[
+    bool,
+    typer.Option(
+        "--no-restart",
+        help="Leave the daemon, the web interface and the MCP server alone.",
+    ),
+]
+
+
+class _UpdateGroup(TyperGroup):
+    """A group whose unknown subcommand is a plugin type to upgrade."""
+
+    # Typer carries its own copy of click, so the types are left open here.
+    def get_command(self, ctx: Any, cmd_name: str) -> Any:
+        command = super().get_command(ctx, cmd_name)
+        if command is not None or cmd_name.startswith("-"):
+            return command
+        return _type_command(cmd_name)
+
+
+update_app = typer.Typer(
+    cls=_UpdateGroup,
+    add_completion=False,
+    no_args_is_help=True,
+    help="Upgrade Bricklogger and its plugins from PyPI. `update status` shows what "
+    "there is; `update core` upgrades Bricklogger alone, as far as the plugins "
+    "allow; `update TYPE` upgrades the plugin that provides the type; `update all` "
+    "upgrades everything together. The new version validates the configuration "
+    "before anything is restarted, and the previous versions are put back when it "
+    "does not hold.",
+)
+
+
+@update_app.command("status")
+def status_command(
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Emit JSON instead of a table.")
+    ] = False,
+) -> None:
+    """For Bricklogger and every plugin: installed, newest, and newest that fits."""
+    try:
+        rows = status()
+    except OperationError as exc:
+        raise fail(exc.message) from exc
+    if json_output:
+        print_json([row.as_dict() for row in rows])
+        return
+    table = Table(box=None)
+    for column in ("Package", "Installed", "Newest", "Fits", "Note"):
+        table.add_column(column)
+    for row in rows:
+        table.add_row(
+            row.name,
+            row.installed,
+            row.newest or "?",
+            row.fits or "?",
+            _note(row.name, row.error, row.newest, row.fits, row.held_by),
+        )
+    stdout.print(table)
+
+
+def _note(
+    name: str,
+    error: str | None,
+    newest: str | None,
+    fits: str | None,
+    held_by: tuple[str, ...],
+) -> str:
+    if error is not None:
+        return f"not looked up: {error}"
+    if newest is not None and fits is not None and newest != fits and held_by:
+        return (
+            f"{newest} held back by {', '.join(held_by)}; "
+            "`update all` moves them together"
+        )
+    return ""
+
+
+@update_app.command("core")
+def core_command(ctx: typer.Context, no_restart: NoRestart = False) -> None:
+    """Upgrade Bricklogger alone, to the newest release the plugins allow."""
+    _update(ctx, "core", no_restart)
+
+
+@update_app.command("all")
+def all_command(ctx: typer.Context, no_restart: NoRestart = False) -> None:
+    """Upgrade Bricklogger and every plugin to the newest releases that fit together."""
+    _update(ctx, "all", no_restart)
+
+
+def _type_command(type_name: str) -> Any:
+    """``update TYPE``, made for the type that was typed."""
+    sub = typer.Typer(add_completion=False)
+
+    @sub.command(type_name)
+    def command(ctx: typer.Context, no_restart: NoRestart = False) -> None:
+        """Upgrade the plugin that provides this type, the rest held."""
+        _update(ctx, type_name, no_restart)
+
+    return typer_command(sub)
+
+
+def _update(ctx: typer.Context, target: str, no_restart: bool) -> None:
+    context = cli_context(ctx)
+    try:
+        result = update(target, config_dir=context.config_dir, restart=not no_restart)
+    except UpdateRefused as exc:
+        for error in exc.errors:
+            where = ".".join(
+                str(part)
+                for part in (
+                    f"{error.get('file')}.yaml",
+                    error.get("subject"),
+                    error.get("key"),
+                )
+                if part and part != "None.yaml"
+            )
+            stderr.print(f"  {where}: {error.get('message')}", highlight=False)
+        back = "; the previous versions are back in place" if exc.restored else ""
+        raise fail(f"{exc.message}{back}") from exc
+    except OperationError as exc:
+        raise fail(exc.message) from exc
+    _report(result, target, no_restart)
+
+
+def _report(result: Updated, target: str, no_restart: bool) -> None:
+    if not result.moved:
+        typer.echo("already up to date")
+        if target == "core":
+            _held_back()
+        return
+    typer.echo(
+        "updated "
+        + ", ".join(
+            _movement(name, old, new) for name, (old, new) in result.moved.items()
+        )
+    )
+    for warning in result.warnings:
+        subject = warning.get("subject") or warning.get("file")
+        typer.echo(f"warning: {subject}: {warning.get('message')}")
+    if result.units:
+        typer.echo(f"rewrote {', '.join(result.units)} from the new templates")
+    if result.restarted:
+        typer.echo(f"restarted {', '.join(result.restarted)}")
+    for unit in result.not_answering:
+        typer.echo(
+            f"{unit} was restarted but does not answer yet; check its log with "
+            f"journalctl -u {unit}"
+        )
+    for note in result.notes:
+        typer.echo(note)
+    if result.container:
+        typer.echo("Restart the containers to run it: docker compose restart")
+        if target == "all":
+            typer.echo("Bricklogger itself comes with a new image.")
+    elif no_restart:
+        typer.echo("nothing was restarted (--no-restart)")
+    if target == "core":
+        _held_back()
+
+
+def _movement(name: str, old: str | None, new: str | None) -> str:
+    if old is None:
+        return f"{name} {new} (new)"
+    if new is None:
+        return f"{name} {old} (removed)"
+    return f"{name} {old} → {new}"
+
+
+def _held_back() -> None:
+    """Name a newer Bricklogger the installed plugins exclude."""
+    try:
+        rows = status()
+    except OperationError:
+        return
+    core = next((row for row in rows if row.name == CORE), None)
+    if core is None or not core.held_by or core.newest is None:
+        return
+    typer.echo(
+        f"bricklogger {core.newest} is out, but {', '.join(core.held_by)} does not "
+        "allow it yet; `bricklogger update all` moves them together"
+    )

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/config/__init__.py

@@ -51,6 +51,7 @@ from bricklogger.config.schema import (
 from bricklogger.config.validation import (
     RESERVED_INSTANCE_NAMES,
     ValidationResult,
+    not_installed,
     validate_configuration,
 )
 
@@ -81,6 +82,7 @@ __all__ = [
     "examples_for",
     "instances_in",
     "load_configuration",
+    "not_installed",
     "parse_text",
     "read_env_file",
     "read_texts",

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/config/schema.py

@@ -185,6 +185,16 @@ class NotificationSettings(_Strict):
     )
 
 
+class UpdateSettings(_Strict):
+    """``updates`` in ``daemon.yaml``. See ``docs/features/cli.md``, "update"."""
+
+    check: bool = Field(
+        default=True,
+        description="Whether the daemon looks on PyPI once a day for newer "
+        "releases of Bricklogger and its plugins; off on a network with no way out",
+    )
+
+
 class DaemonSettings(_Strict):
     """``daemon.yaml``."""
 
@@ -216,6 +226,10 @@ class DaemonSettings(_Strict):
         default_factory=NotificationSettings,
         description="Mail to the administrator, off by default",
     )
+    updates: UpdateSettings = Field(
+        default_factory=UpdateSettings,
+        description="The daily look for newer releases",
+    )
 
     @property
     def log_file(self) -> Path:

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/config/validation.py

@@ -65,6 +65,51 @@ def _unloadable(file: str, name: str, error: str) -> ConfigIssue:
     )
 
 
+def not_installed(type_name: str) -> str:
+    """What is said of a configured type that no installed plugin provides,
+    by validation and by the daemon that shows its instance failed."""
+    return (
+        f"the type {type_name!r} is not installed; add its plugin with "
+        "`bricklogger plugins add`"
+    )
+
+
+def _not_installed(file: str, name: str, type_name: str) -> ConfigIssue:
+    """A warning, not an error: the instance will be failed while everything
+    else runs, as for a plugin that cannot load. See
+    ``docs/features/plugins.md``, "A type that is not installed"."""
+    return ConfigIssue(
+        file, f"the instance will be failed: {not_installed(type_name)}", name, "type"
+    )
+
+
+def _changed_instances(
+    config_dir: Path,
+    config: Configuration,
+    env: Mapping[str, str] | None,
+    texts: Mapping[str, str | None] | None,
+) -> set[tuple[str, str]]:
+    """``(file, name)`` for every instance a proposed change adds or changes,
+    compared with the files on disk; nothing when no change is proposed.
+    When the files on disk do not load, every instance counts as changed."""
+    if not texts:
+        return set()
+    current = load_configuration(config_dir, env).configuration
+    changed: set[tuple[str, str]] = set()
+    for file, new, old in (
+        ("sources", config.sources, current.sources if current else {}),
+        (
+            "destinations",
+            config.destinations,
+            current.destinations if current else {},
+        ),
+    ):
+        for name, instance in new.items():
+            if old.get(name) != instance:
+                changed.add((file, name))
+    return changed
+
+
 def _reserved(file: str, name: str) -> ConfigIssue:
     return ConfigIssue(
         file,
@@ -81,7 +126,9 @@ def validate_configuration(
 ) -> ValidationResult:
     """Validate the whole directory; the configuration comes back only when valid.
 
-    ``texts`` replaces files as they are on disk, for a proposed change.
+    ``texts`` replaces files as they are on disk, for a proposed change. A
+    configured type that is not installed is a warning, except in an
+    instance the proposed change adds or changes, where it is an error.
     """
     loaded = load_configuration(config_dir, env, texts)
     if loaded.configuration is None:
@@ -89,6 +136,7 @@ def validate_configuration(
     config = loaded.configuration
     errors: list[ConfigIssue] = []
     warnings: list[ConfigIssue] = []
+    changed = _changed_instances(config_dir, config, env, texts)
 
     daemon = config.daemon
     if not is_loopback(daemon.api.host) and not daemon.api.token:
@@ -126,6 +174,9 @@ def validate_configuration(
             if failure is not None:
                 warnings.append(_unloadable("sources", name, failure.error))
                 continue
+            if ("sources", name) not in changed:
+                warnings.append(_not_installed("sources", name, source.type))
+                continue
             errors.append(
                 ConfigIssue(
                     "sources",
@@ -150,6 +201,9 @@ def validate_configuration(
             if failure is not None:
                 warnings.append(_unloadable("destinations", name, failure.error))
                 continue
+            if ("destinations", name) not in changed:
+                warnings.append(_not_installed("destinations", name, destination.type))
+                continue
             errors.append(
                 ConfigIssue(
                     "destinations",

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/daemon/core.py

@@ -29,6 +29,7 @@ from bricklogger.config import (
     DestinationInstance,
     SourceInstance,
     ValidationResult,
+    not_installed,
     read_texts,
     validate_configuration,
     write_text,
@@ -51,6 +52,7 @@ from bricklogger.daemon.sink import DaemonSink
 from bricklogger.daemon.sparql import run_query
 from bricklogger.daemon.spool import SPOOL_DIR, Spool
 from bricklogger.daemon.state import STATE_FILE, RuntimeState
+from bricklogger.daemon.updates import Lookup, UpdateWatch
 from bricklogger.model import (
     INFERRED_GRAPH,
     MODEL_GRAPH,
@@ -197,6 +199,7 @@ class Daemon:
         config_dir: Path,
         registry: PluginRegistry | None = None,
         env: Mapping[str, str] | None = None,
+        update_lookup: Lookup | None = None,
     ) -> None:
         self.config_dir = config_dir
         if registry is None:
@@ -215,6 +218,8 @@ class Daemon:
         self.unloadable: dict[str, Unloadable] = {}
         self.spools: dict[str, Spool] = {}
         self.notifier: Notifier | None = None
+        self.updates: UpdateWatch | None = None
+        self._update_lookup = update_lookup
         self.plan: Plan | None = None
         self.active_version: int | None = None
         self.model_error: str | None = None
@@ -258,10 +263,14 @@ class Daemon:
         self.notifier = Notifier(self, config.daemon.notifications)
         self.notifier.record_event("started")
         self.notifier.start()
+        self.updates = UpdateWatch(config.daemon.updates.check, self._update_lookup)
+        self.updates.start()
         log.info("daemon started with config %s", self.config_dir)
 
     def stop(self) -> None:
         self.jobs.stop()
+        if self.updates is not None:
+            self.updates.stop()
         if self.notifier is not None:
             # Held rather than sent, so an upgrade gives one mail that says
             # the daemon stopped and started; see docs/features/notifications.md.
@@ -297,6 +306,8 @@ class Daemon:
             self._start_sources()
             if self.notifier is not None:
                 self.notifier.reconfigure(new.daemon.notifications)
+            if self.updates is not None:
+                self.updates.reconfigure(new.daemon.updates.check)
         log.info("configuration reloaded from %s", self.config_dir)
         return result
 
@@ -656,11 +667,7 @@ class Daemon:
         and the same warning a crashed instance raises."""
         assert self.state is not None
         failure = self.registry.failure_of(type_name)
-        error = (
-            failure.error
-            if failure is not None
-            else f"the plugin {type_name!r} is not installed"
-        )
+        error = failure.error if failure is not None else not_installed(type_name)
         self.unloadable[name] = Unloadable(role, type_name, error)
         self.state.set_instance(
             name, role=role, type_name=type_name, state="failed", error=error
@@ -780,10 +787,7 @@ class Daemon:
         else:
             entry = self.unloadable.get(instance)
             if entry is not None and entry.type_name == type_name:
-                raise InstanceNotRunning(
-                    f"{instance} cannot start: its plugin could not be loaded: "
-                    f"{entry.error}"
-                )
+                raise InstanceNotRunning(f"{instance} cannot start: {entry.error}")
             raise NotFound(f"unknown plugin type {type_name!r}")
         if runner is None or runner.type_name != type_name:
             raise NotFound(f"no instance {instance!r} of {type_name!r}")
@@ -982,6 +986,7 @@ class Daemon:
             ],
             "warnings": len(self.state.warnings()),
             "observations_received": self.state.counter("observations_received"),
+            "updates": self.updates.summary() if self.updates else None,
         }
 
     def status_sources(self) -> list[dict[str, Any]]:

{bricklogger-0.2.0 → bricklogger-0.2.2}/src/bricklogger/daemon/notify.py

@@ -38,6 +38,7 @@ from bricklogger.daemon.codes import (
 from bricklogger.daemon.rules import BRICK, REC
 from bricklogger.daemon.state import RuntimeState
 from bricklogger.model.working_graph import MODEL_GRAPH, WorkingGraph
+from bricklogger.ops.updates import available_line
 
 log = logging.getLogger("bricklogger.notify")
 
@@ -711,6 +712,9 @@ def _digest_sections(
         )
     else:
         sections.append(("Warnings", ["Nothing stands."], []))
+    newer = available_line(status.get("updates"))
+    if newer is not None:
+        sections.append(("Updates", [newer], []))
     return sections