[client] Document the proxy-vs-mixin rule (weather stays, streaming deferred) #175

Closed
opened 2026-10-27 11:31:49 +00:00 by mat · 0 comments
Owner

Decided during the #151 architecture audit.

Current state: weather is the only namespaced proxy (client.weather.forecast, _weather.py), every other domain is a flat mixin (client.get_*). The split looks arbitrary but follows an implicit rule worth writing down:

A domain gets a namespaced proxy if and only if its transport differs from the authenticated REST path — different base URL/host, protocol, or auth model. Method count is never a trigger.

Applying the rule:

  • Weather qualifies: unauthenticated + URL outside /api (_weather.py:7, vs _core.py:56), while reusing the client's _request transport via absolute-URL support (_core.py:94). Keep as proxy.
  • Streaming (wss://frontage.energy.comwatt.com/ws, _streaming.py:12) is the only other transport-divergent domain, but it is authenticated, session-coupled, and exposes a single flat method (stream_measurements) documented in the README. Do not convert now; revisit only if a second streaming method lands (conversion would need a deprecation path).

Done when:

  • README gains a short composition/architecture note stating the rule.
  • #151's first bullet ("mixin vs proxy split is inconsistent") is answered — cross-reference there.
Decided during the #151 architecture audit. **Current state:** weather is the only namespaced proxy (`client.weather.forecast`, `_weather.py`), every other domain is a flat mixin (`client.get_*`). The split looks arbitrary but follows an implicit rule worth writing down: > **A domain gets a namespaced proxy if and only if its transport differs from the authenticated REST path** — different base URL/host, protocol, or auth model. Method count is never a trigger. **Applying the rule:** - **Weather** qualifies: unauthenticated + URL outside `/api` (`_weather.py:7`, vs `_core.py:56`), while reusing the client's `_request` transport via absolute-URL support (`_core.py:94`). Keep as proxy. - **Streaming** (`wss://frontage.energy.comwatt.com/ws`, `_streaming.py:12`) is the only other transport-divergent domain, but it is authenticated, session-coupled, and exposes a single flat method (`stream_measurements`) documented in the README. Do **not** convert now; revisit only if a second streaming method lands (conversion would need a deprecation path). **Done when:** - [ ] README gains a short composition/architecture note stating the rule. - [ ] #151's first bullet ("mixin vs proxy split is inconsistent") is answered — cross-reference there.
mat closed this issue 2026-10-27 14:31:36 +00:00
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
mat/python-comwatt-client#175
No description provided.