Add Ruff formatting and linting

Adds [tool.ruff] config (line-length 100, py310 target, E/W/F/I/B/UP/SIM
rules), ruff to dev deps, a lint CI workflow, and a pre-commit config.
Initial format pass applied across src/ and tests/.

Fixes surfaced by ruff check:
- mqtt.py: move MqttClient annotation under TYPE_CHECKING (was F821
  undefined at runtime due to deferred import)
- mqtt.py, webhook.py: raise ImportError ... from err (B904)
- test_discovery.py: drop unused `as adv` binding (F841)
- test_ven.py: combine nested with-statements (SIM117)

Closes OA3C-1t4.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dcj

.github/workflows/lint.yml

@@ -0,0 +1,18 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - run: pip install "ruff>=0.15.0"
+      - run: ruff check src tests
+      - run: ruff format --check src tests

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

pyproject.toml

@@ -33,7 +33,7 @@ mqtt = ["ebus-mqtt-client>=0.1.0"]
 webhooks = ["flask>=3.0.0"]
 mdns = ["zeroconf>=0.131.0"]
 all = ["ebus-mqtt-client>=0.1.0", "flask>=3.0.0", "zeroconf>=0.131.0"]
-dev = ["pytest", "ebus-mqtt-client>=0.1.0", "flask>=3.0.0", "zeroconf>=0.131.0"]
+dev = ["pytest", "ruff>=0.15.0", "ebus-mqtt-client>=0.1.0", "flask>=3.0.0", "zeroconf>=0.131.0"]
 
 [project.urls]
 Homepage = "https://grid-coordination.energy"
@@ -51,3 +51,26 @@ exclude = [
     ".beads/",
     "examples/",
 ]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = [".beads", "examples"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501", # line-too-long (handled by formatter)
+    "B008", # do not perform function calls in argument defaults
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]  # allow assert False in tests

src/openadr3_client/__init__.py

@@ -1,19 +1,19 @@
 from openadr3_client.base import BaseClient
-from openadr3_client.ven import VenClient, extract_topics
 from openadr3_client.bl import BlClient
-from openadr3_client.notifications import (
-    MqttChannel,
-    NotificationChannel,
-    WebhookChannel,
-)
-from openadr3_client.mqtt import MQTTConnection, MQTTMessage, normalize_broker_uri
-from openadr3_client.webhook import WebhookReceiver, WebhookMessage, detect_lan_ip
 from openadr3_client.discovery import (
     DiscoveredVTN,
     DiscoveryMode,
     advertise_vtn,
     discover_vtns,
 )
+from openadr3_client.mqtt import MQTTConnection, MQTTMessage, normalize_broker_uri
+from openadr3_client.notifications import (
+    MqttChannel,
+    NotificationChannel,
+    WebhookChannel,
+)
+from openadr3_client.ven import VenClient, extract_topics
+from openadr3_client.webhook import WebhookMessage, WebhookReceiver, detect_lan_ip
 
 __all__ = [
     # Clients

src/openadr3_client/base.py

@@ -73,12 +73,15 @@ def start(self) -> BaseClient:
         if self._api:
             log.info(
                 "%s already started: url=%s",
-                type(self).__name__, self._resolved_url,
+                type(self).__name__,
+                self._resolved_url,
             )
             return self
 
         self._resolved_url = resolve_url(
-            self.discovery_mode, self.url, self.discovery_timeout,
+            self.discovery_mode,
+            self.url,
+            self.discovery_timeout,
         )
 
         if not self.token:
@@ -98,7 +101,9 @@ def start(self) -> BaseClient:
         )
         log.info(
             "%s started: type=%s url=%s",
-            type(self).__name__, self._client_type, self._resolved_url,
+            type(self).__name__,
+            self._client_type,
+            self._resolved_url,
         )
         return self
 
@@ -120,9 +125,7 @@ def __exit__(self, *args: Any) -> None:
     def api(self) -> OpenADRClient:
         """The underlying OpenADRClient. Raises if not started."""
         if not self._api:
-            raise RuntimeError(
-                f"{type(self).__name__} not started. Call start() first."
-            )
+            raise RuntimeError(f"{type(self).__name__} not started. Call start() first.")
         return self._api
 
     # -- __getattr__ delegation --
@@ -136,6 +139,4 @@ def __getattr__(self, name: str) -> Any:
                 return getattr(api, name)
             except AttributeError:
                 pass
-        raise AttributeError(
-            f"'{type(self).__name__}' object has no attribute '{name}'"
-        )
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")

src/openadr3_client/discovery.py

@@ -11,7 +11,7 @@
 
 import logging
 import threading
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from enum import Enum
 from typing import Any
 
@@ -71,8 +71,10 @@ def from_service_info(cls, info: Any) -> DiscoveredVTN:
         """Build from a ``zeroconf.ServiceInfo`` object."""
         props = _parse_txt_properties(info.properties or {})
         # Prefer .server (the .local hostname) over parsed addresses
-        host = info.server.rstrip(".") if info.server else (
-            info.parsed_addresses()[0] if info.parsed_addresses() else "localhost"
+        host = (
+            info.server.rstrip(".")
+            if info.server
+            else (info.parsed_addresses()[0] if info.parsed_addresses() else "localhost")
         )
         return cls(
             name=info.name,
@@ -91,6 +93,7 @@ def _import_zeroconf():
     """Lazy-import zeroconf with a helpful error message."""
     try:
         import zeroconf  # noqa: F811
+
         return zeroconf
     except ImportError:
         raise ImportError(
@@ -157,19 +160,15 @@ def resolve_url(
 
     if mode == DiscoveryMode.REQUIRE_LOCAL:
         if not discovered_url:
-            raise RuntimeError(
-                "discovery='require_local' but no VTN found via mDNS"
-            )
+            raise RuntimeError("discovery='require_local' but no VTN found via mDNS")
         return discovered_url
 
     if mode == DiscoveryMode.PREFER_LOCAL:
         if discovered_url:
             return discovered_url
         if configured_url:
             return configured_url
-        raise RuntimeError(
-            "discovery='prefer_local': no VTN found via mDNS and no url configured"
-        )
+        raise RuntimeError("discovery='prefer_local': no VTN found via mDNS and no url configured")
 
     # LOCAL_WITH_FALLBACK
     if discovered_url:
@@ -241,9 +240,7 @@ def advertise_vtn(
         server=f"{host}.",
         port=port,
         properties=properties,
-        addresses=[socket.inet_aton(
-            "127.0.0.1" if host in ("localhost", "127.0.0.1") else host
-        )],
+        addresses=[socket.inet_aton("127.0.0.1" if host in ("localhost", "127.0.0.1") else host)],
     )
 
     zc = Zeroconf()

src/openadr3_client/mqtt.py

@@ -9,15 +9,18 @@
 
 import json
 import logging
-import re
 import threading
 import time
-from dataclasses import dataclass, field
-from typing import Any, Callable
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
 from openadr3.entities import coerce_notification, is_notification
 
+if TYPE_CHECKING:
+    from ebus_mqtt_client import MqttClient
+
 log = logging.getLogger(__name__)
 
 
@@ -54,9 +57,7 @@ def _parse_payload(raw: bytes, topic: str) -> Any:
         return s
 
     if isinstance(parsed, dict) and is_notification(parsed):
-        return coerce_notification(
-            parsed, {"openadr/channel": "mqtt", "openadr/topic": topic}
-        )
+        return coerce_notification(parsed, {"openadr/channel": "mqtt", "openadr/topic": topic})
     return parsed
 
 
@@ -96,11 +97,11 @@ def connect(self) -> None:
         """Connect to the MQTT broker."""
         try:
             from ebus_mqtt_client import MqttClient
-        except ImportError:
+        except ImportError as err:
             raise ImportError(
                 "ebus-mqtt-client is required for MQTT support. "
                 "Install it with: pip install python-oa3-client[mqtt]"
-            )
+            ) from err
 
         host, port, use_tls = normalize_broker_uri(self.broker_url)
         self._client = MqttClient(

src/openadr3_client/notifications.py

@@ -7,10 +7,11 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Callable, Protocol, runtime_checkable
+from collections.abc import Callable
+from typing import Any, Protocol, runtime_checkable
 
 from openadr3_client.mqtt import MQTTConnection, MQTTMessage
-from openadr3_client.webhook import WebhookReceiver, WebhookMessage
+from openadr3_client.webhook import WebhookMessage, WebhookReceiver
 
 log = logging.getLogger(__name__)
 

src/openadr3_client/ven.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 import httpx
-
-from openadr3.api import success, body
+from openadr3.api import success
 
 from openadr3_client.base import BaseClient
 from openadr3_client.notifications import (
@@ -83,16 +83,16 @@ def register(self, ven_name: str) -> VenClient:
                 vid = existing["id"]
                 log.info("VEN found, reusing: name=%s id=%s", ven_name, vid)
             else:
-                resp = self.api.create_ven({
-                    "objectType": "VEN_VEN_REQUEST",
-                    "venName": ven_name,
-                })
+                resp = self.api.create_ven(
+                    {
+                        "objectType": "VEN_VEN_REQUEST",
+                        "venName": ven_name,
+                    }
+                )
                 resp.raise_for_status()
                 vid = resp.json().get("id")
                 if not vid:
-                    raise RuntimeError(
-                        f"VEN registration failed: {resp.status_code} {resp.text}"
-                    )
+                    raise RuntimeError(f"VEN registration failed: {resp.status_code} {resp.text}")
                 log.info("VEN registered: name=%s id=%s", ven_name, vid)
             self._ven_id = vid
             self._ven_name = ven_name
@@ -135,9 +135,7 @@ def vtn_supports_mqtt(self) -> bool:
             return False
         # VTN-RI returns a list of notifier dicts with "transport" field
         if isinstance(notifiers, list):
-            return any(
-                n.get("transport", "").upper() == "MQTT" for n in notifiers
-            )
+            return any(n.get("transport", "").upper() == "MQTT" for n in notifiers)
         # Or it might be a dict with transport info
         return "mqtt" in str(notifiers).lower()
 
@@ -213,16 +211,20 @@ def subscribe(
                     all_topics.extend(topics)
             elif isinstance(channel, WebhookChannel):
                 # Create a VTN subscription pointing to the webhook
-                self.api.create_subscription({
-                    "clientName": self._ven_name or "ven-client",
-                    "programID": program_id,
-                    "objectOperations": [{
-                        "objects": objects,
-                        "operations": operations,
-                        "callbackUrl": channel.callback_url,
-                        "bearerToken": channel._receiver.bearer_token,
-                    }],
-                })
+                self.api.create_subscription(
+                    {
+                        "clientName": self._ven_name or "ven-client",
+                        "programID": program_id,
+                        "objectOperations": [
+                            {
+                                "objects": objects,
+                                "operations": operations,
+                                "callbackUrl": channel.callback_url,
+                                "bearerToken": channel._receiver.bearer_token,
+                            }
+                        ],
+                    }
+                )
 
         return all_topics
 

src/openadr3_client/webhook.py

@@ -11,12 +11,12 @@
 
 import json
 import logging
+import socket
 import threading
 import time
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Callable
-
-import socket
+from typing import Any
 
 from openadr3.entities import coerce_notification, is_notification
 
@@ -66,9 +66,7 @@ def _parse_webhook_payload(raw: bytes, path: str) -> Any:
         return s
 
     if isinstance(parsed, dict) and is_notification(parsed):
-        return coerce_notification(
-            parsed, {"openadr/channel": "webhook", "openadr/path": path}
-        )
+        return coerce_notification(parsed, {"openadr/channel": "webhook", "openadr/path": path})
     return parsed
 
 
@@ -120,12 +118,12 @@ def callback_url(self) -> str:
     def start(self) -> None:
         """Start the webhook server in a background thread."""
         try:
-            from flask import Flask, request, abort
-        except ImportError:
+            from flask import Flask, abort, request
+        except ImportError as err:
             raise ImportError(
                 "Flask is required for webhook support. "
                 "Install it with: pip install python-oa3-client[webhooks]"
-            )
+            ) from err
 
         app = Flask(__name__)
         # Suppress Flask/werkzeug request logging
@@ -177,7 +175,9 @@ def health():
         self._server_thread.start()
         log.info(
             "Webhook server started: %s (bind=%s:%d)",
-            self.callback_url, self.host, self.port,
+            self.callback_url,
+            self.host,
+            self.port,
         )
 
     def stop(self) -> None: