Add user_agent parameter for client self-identification in VTN logs

BaseClient accepts an optional user_agent kwarg, composes a layered
User-Agent string (python-oa3-client/<ver> openadr3/<ver> <custom>),
and passes it through to the upstream OpenADRClient. Bumps openadr3
dependency to >=0.3.0 for upstream user_agent support.

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

Author: dcj

README.md

@@ -65,6 +65,25 @@ bl_token = base64.b64encode(b"bl_client:1001").decode()
 ven_token = base64.b64encode(b"ven_client:999").decode()
 ```
 
+## User-Agent
+
+Clients send a composed User-Agent header for server-side log identification:
+
+```
+python-oa3-client/0.2.1 openadr3/0.3.0 (node=a1b2c3d4e5f6)
+```
+
+Add your own identifier with the `user_agent` parameter:
+
+```python
+ven = VenClient(
+    url=vtn_url,
+    token=token,
+    user_agent="my-thermostat/1.0 (contact@example.com)",
+)
+# UA: python-oa3-client/0.2.1 openadr3/0.3.0 (node=...) my-thermostat/1.0 (contact@example.com)
+```
+
 ## mDNS/DNS-SD Discovery
 
 Requires: `pip install python-oa3-client[mdns]`

pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-    "openadr3>=0.2.0",
+    "openadr3>=0.3.0",
 ]
 
 [project.optional-dependencies]

src/openadr3_client/base.py

@@ -4,8 +4,12 @@
 
 import logging
 import threading
+from importlib.metadata import version as _pkg_version
 from typing import Any
 
+from openadr3.api import (
+    DEFAULT_USER_AGENT as _UPSTREAM_UA,
+)
 from openadr3.api import (
     OpenADRClient,
     create_bl_client,
@@ -17,6 +21,8 @@
 
 log = logging.getLogger(__name__)
 
+DEFAULT_USER_AGENT = f"python-oa3-client/{_pkg_version('python-oa3-client')} {_UPSTREAM_UA}"
+
 
 class BaseClient:
     """Lifecycle-managed OpenADR 3 client with __getattr__ delegation.
@@ -38,6 +44,7 @@ def __init__(
         validate: bool = False,
         discovery: str | DiscoveryMode = "never",
         discovery_timeout: float = 3.0,
+        user_agent: str | None = None,
     ) -> None:
         if not token and not (client_id and client_secret):
             raise ValueError("Provide either token or both client_id and client_secret")
@@ -57,6 +64,7 @@ def __init__(
         self.spec_version = spec_version
         self.spec_path = spec_path
         self.validate = validate
+        self.user_agent = f"{DEFAULT_USER_AGENT} {user_agent}" if user_agent else DEFAULT_USER_AGENT
 
         self._resolved_url: str | None = None
         self._api: OpenADRClient | None = None
@@ -98,6 +106,7 @@ def start(self) -> BaseClient:
             token=self.token,
             spec_path=self.spec_path,
             validate=self.validate,
+            user_agent=self.user_agent,
         )
         log.info(
             "%s started: type=%s url=%s",

tests/test_base.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from openadr3_client.base import BaseClient
+from openadr3_client.base import DEFAULT_USER_AGENT, BaseClient
 
 
 class TestBaseClientLifecycle:
@@ -121,3 +121,33 @@ def test_raises_attribute_error_unknown(self, mock_create):
         c.start()
         with pytest.raises(AttributeError):
             c.totally_fake_method()
+
+
+class TestBaseClientUserAgent:
+    def test_default_user_agent(self):
+        c = BaseClient(url="http://test", token="tok")
+        assert c.user_agent == DEFAULT_USER_AGENT
+        assert "python-oa3-client/" in c.user_agent
+        assert "openadr3/" in c.user_agent
+
+    def test_custom_user_agent_appended(self):
+        c = BaseClient(url="http://test", token="tok", user_agent="my-app/1.0")
+        assert c.user_agent.startswith("python-oa3-client/")
+        assert c.user_agent.endswith("my-app/1.0")
+        assert "openadr3/" in c.user_agent
+
+    @patch("openadr3_client.base.create_ven_client")
+    def test_user_agent_passed_to_factory(self, mock_create):
+        mock_create.return_value = MagicMock()
+        c = BaseClient(url="http://test", token="tok", user_agent="my-app/2.0")
+        c.start()
+        call_kwargs = mock_create.call_args[1]
+        assert call_kwargs["user_agent"] == c.user_agent
+
+    @patch("openadr3_client.base.create_ven_client")
+    def test_default_user_agent_passed_to_factory(self, mock_create):
+        mock_create.return_value = MagicMock()
+        c = BaseClient(url="http://test", token="tok")
+        c.start()
+        call_kwargs = mock_create.call_args[1]
+        assert call_kwargs["user_agent"] == DEFAULT_USER_AGENT