Axis Library — Design Review

[Kane610]

Overall Verdict

This is a mature, well-engineered library. The dominant characteristics are extreme consistency, strict layering, and a contract-first approach to both the device API and the library's own internal architecture. For a library targeting Home Assistant integration with dozens of physical device variants, the design holds up well.

---

1. API Versioning — Strong Strategy, One Gap

What's there is correct: every ApiHandler subclass declares an api_id into the ApiId enum and a default_api_version fallback. At runtime, the handler resolves the actual version from the device's API Discovery response, falling back gracefully to the declared default. This means the same code handles both current and legacy firmware transparently.

The ApiId enum also has a catch-all UNKNOWN that prevents hard failures on unknown APIs. StrEnum._missing_() is used consistently across enums to absorb unknown values gracefully — this is the right defensive pattern for an evolving external API surface.

The gap: version negotiation is one-directional. The device tells the library what it supports, and the library trusts that implicitly. There's no assertion that the client-side code is compatible with the declared version. For now this is fine — the device will reject bad requests — but as the API evolves across major versions, differing request/response shapes for the same api_id could cause silent parsing failures rather than clear compatibility errors. A minimum-version guard per handler would make compatibility failures explicit.

---

2. Modular Feature Detection — Works, But Implicit

Feature support is decoupled and modular: each handler independently reports whether it's supported via a .supported property that cross-references both API Discovery and param.cgi fallback. This dual-source check is the most important scalability feature in the library — it means older firmware that doesn't advertise via API Discovery still works.

The design is correct but implicit. Consumers must know to check device.vapix.light_control.supported before using light_control. There's no central capability registry or device.supports("light_control") query. For library consumers (Home Assistant), this means each integration must manually probe each handler. That's fine today, but as more APIs are added a registry pattern (a dict of ApiId → handler) would allow consumers to enumerate capabilities without knowing the full handler list.

The Vapix class composes ~20 handlers in its __init__ — this works but grows linearly. The handlers for parameters/ and applications/ are properly factored into sub-orchestrators (Params class, ApplicationsHandler), preventing Vapix from becoming a god class.

---

3. Interface/Model Separation — Excellent

This is the strongest design aspect. The separation is absolute and consistently enforced:

• models/ contains only data structures: frozen dataclasses, TypedDicts for API response shapes, StrEnums for fixed values, and decode() class methods. No network I/O, no device references, no side effects.
• interfaces/ contains only communication logic: HTTP request objects, result parsing delegation, lifecycle management. All inherit from ApiHandler[T].
• The dependency direction is strictly one-way: interfaces → models. Models never import from interfaces.

The ApiHandler[T] base class is a clean generic that unifies the public interface across all 12+ concrete handlers. Dict-like access (__getitem__, __iter__, keys(), values(), items()), subscription callbacks, error normalization, and the update() lifecycle are all inherited. A new handler is essentially just a model declaration + one or two request methods.

TypedDicts for response shapes is the right call — they document the wire format precisely without enforcing full parsing at every layer. The parsed frozen dataclasses are then the stable internal representation. This two-layer approach (TypedDict → frozen dataclass) is idiomatic for working with external APIs.

One minor inconsistency: MqttClientHandler[Any] carries Any as its item type, breaking the generic contract followed by every other handler. This is likely because MQTT client state has no meaningful persistent item to track, but it still represents a type-level exception.

---

4. Transport Abstraction — Clean Protocol Boundary

The StreamTransport / StreamSession structural protocols define a minimal, sufficient boundary. StreamManager is genuinely transport-agnostic — it holds a StreamTransport reference and calls data, session, start(), stop() on it without knowing whether it's RTSP or WebSocket underneath.

The Signal and State enums live in rtsp.py but are re-imported by websocket.py — a small layering violation. Both enums are protocol-level concepts that belong in a shared module, not in one of the two protocol implementations. This is cosmetic but worth noting in a design review.

The transport selection logic in StreamManager.use_websocket is correctly layered: websocket_force → websocket_enabled && discovery. The websocket_force/websocket_enabled flags in Configuration are a clean backward-compatibility mechanism.

---

5. Parameters and Applications Sub-Packages — Consistent, Right Level of Abstraction

Both sub-packages follow the same structural pattern as the top-level interfaces:

• An orchestrator handler fetches data once (Params → param.cgi, ApplicationsHandler → installed apps list)
• Sub-handlers register interest in a slice of that data
• Models decode their slice into frozen dataclasses

The parameters/ sub-package uses a subscription/observer model (ParamHandler subscribes to Params updates) which is the right approach to avoid N separate HTTP calls for N parameter groups. The applications/ approach is even simpler: all apps come in one manifest, individual handlers just query it.

One structural difference worth flagging: param.cgi uses a flat key=value text format with recursive string parsing via params_to_dict(), deliberately distinct from the JSON decode() pattern used everywhere else. This is unavoidable (legacy firmware reality) but it means the parameters sub-system has its own mini-parsing layer not shared with the rest of the codebase. It's correctly isolated.

---

6. Efficiency

• orjson throughout for JSON parsing — correct choice for a high-frequency event library
• Frozen dataclasses as model items — zero field mutation overhead, safe sharing
• deque(maxlen=BUFFER_SIZE) in the WebSocket client — bounded memory for event buffering without explicit eviction management
• Single HTTP gateway (vapix.api_request) — all requests funnel through one place, making retry/auth/session management centralized
• Lazy initialization — handlers don't fetch data until update() is called; devices without permission for an API fail gracefully at call time, not at construction

The httpx dependency alongside aiohttp is potentially unnecessary duplication. httpx appears to be an alternative HTTPSession type in Configuration but if aiohttp covers all use cases, httpx adds dependency weight for little benefit.

---

7. Type Safety and Pythonic Style

• Strict mypy enforced at CI — the py.typed marker and packages = find: mean downstream consumers get type checking for free
• Self return type in decode() class methods — correct for inheritance-safe construction
• KW_ONLY sentinel in Configuration.__post_init__ — prevents positional argument mistakes for optional config fields
• StrEnum with _missing_() universally — absorbs unknown values at boundaries without raising
• @dataclass(frozen=True) for items, mutable dataclasses for request parameters — intent is clear from mutability declaration alone

The one area where Any bleeds in is deeply nested application config (fence guard triggers, perspective data, MQTT filters). These are genuinely unstructured blobs from the device API, so Any is the honest type, not a cop-out.

---

Summary

Dimension	Assessment
API versioning	Strong — dual-source fallback, ApiId enum, per-handler defaults. Minor gap: no client-side min-version guard
Feature modularity	Good — every handler self-reports support independently. Improvement opportunity: central capability registry
Interface/model separation	Excellent — absolute, enforced by structure, no circular deps
Transport abstraction	Clean Protocol boundary. Minor: Signal/State belong in a shared module
Sub-package consistency	High — parameters and applications follow the same orchestrator/sub-handler pattern
Efficiency	Good — orjson, frozen dataclasses, single HTTP gateway, bounded buffers
Type safety	Strong — strict mypy, TypedDicts for wire shapes, Self, StrEnum, minimal Any
Overall scalability	High — adding a new API means: one model file, one interface file, one handler registration in Vapix. No cross-cutting changes required

[Kane610]

Let me run both agents in parallel — one to deeply investigate the current request structure and versioning mechanics, and one to research how mature Python API client libraries solve this problem.

API Versioning & Request Structure — Design Analysis

What's Actually Wrong

Your instinct is correct. The ApiRequest structure itself is fine — the problem is in the plumbing between version discovery and request construction. Specifically:

The ApiHandler.api_version property exists, is correct, but is dead code.

Every handler method has to manually decide how to get a version string and pass it to its request objects. The result is three inconsistent patterns coexisting in the same codebase:

Pattern	Handlers	Version sent to device
Manual api_discovery[self.api_id] lookup	BasicDeviceInfo, ViewArea, StreamProfiles	✅ Discovered version
self.default_api_version	LightControl, MqttClient	⚠️ Hardcoded fallback
No argument, module constant used	IoPortManagement	❌ Hardcoded constant

The handler base class already computes the right answer — discovered version, falling back to the declared default — but nothing calls it. Three handlers reinvent it manually; three others skip it entirely.

---

Is This a Live Problem?

Partially, but it's accidentally contained today. Axis follows a backwards-compatibility policy, so a device advertising LightControl v2.0 mostly accepts a v1.1 request. The failure mode is:

1. An old device that only supports v1.0 receives v1.1 → device returns error 2003: "Requested API version is not supported" — arrives as a generic crash with no actionable diagnostic
2. A future device drops support for v1.1 after a firmware update → same silent failure
3. An API that actually changed its request/response structure between versions → silent misparsing or KeyError

The gap is a pit of failure, not yet fallen into.

---

The Right Fix — Two-Part, Low Cost

Part 1 — Thread self.api_version into all request construction (Option A)

Every handler method that constructs a request should replace:

• self.default_api_version → self.api_version
• self.vapix.api_discovery[self.api_id].version (manual lookup) → self.api_version
• GetPortsRequest() (no argument) → GetPortsRequest(api_version=self.api_version)

This is a purely mechanical change: no model classes change, no new abstractions, no response parsing changes. It makes the property that already exists actually do its job, and collapses three inconsistent patterns into one.

Part 2 — Fail-fast on version mismatch (Option D)

Add a lightweight assertion in the _api_request method of ApiHandler (or the concrete update() flow) that raises a clear, nameable error when the discovered version is outside a declared compatible range. Instead of the device eventually returning opaque error 2003, the library raises ApiVersionUnsupported("LightControl requires >= 1.0, device reports 3.0") before the HTTP call is even made. This is cheap insurance.

---

What NOT to Do

Skip versioned request registries and version-dispatched response decoders (Options B and C). VAPIX versioning has been additive — no known API in this library has divergent request bodies or response schemas across versions. Building that infrastructure now would be significant over-engineering for a risk that has not materialized. The right time to add version-branched response decoding is the moment a real schema divergence exists.

---

Summary

Issue	Severity	Fix
api_version property unused — dead code	Medium	Use it in all handler request construction
Three inconsistent patterns for passing version	Medium	Collapse to one via self.api_version
No fail-fast on version incompatibility	Low	Add version range guard in ApiHandler
No support for structurally different requests per version	Latent	Defer — no current need
No support for version-divergent response schemas	Latent	Defer — no current need

The core feeling you had is correct: the version information exists and is correctly resolved, but it has no reliable path into the actual request. The fix is connecting the wire, not redesigning the circuit.

[Kane610]

Findings Across All Investigation and Planning Agents

---

1. What the Code Actually Looks Like (Facts)

Vapix.__init__ creates 20 handler instances with zero conditional logic — every handler is always instantiated regardless of whether the device supports it. There are 3 conceptual groups mixed together in flat sequence:

Group	Handlers
API-discovery handlers	basic_device_info, io_port_management, light_control, mqtt, pir_sensor_configuration, stream_profiles, view_areas
Application handlers	applications, fence_guard, loitering_guard, motion_guard, object_analytics, vmd4
Legacy / CGI	port_cgi, ptz, params, api_discovery, users, user_groups, event_instances

These groups have no structural separation in the code — they are interleaved flat attributes on Vapix.

---

2. The Three Initialization Flows — What They Actually Do

initialize() chains three sequential phases:

initialize_api_discovery() → initialize_param_cgi(preload_data=False) → initialize_applications()

The ordering is load-order constrained — not arbitrary. initialize_param_cgi must run after initialize_api_discovery because its 9 conditional branches read the already-populated api_discovery state to decide which param.cgi fallback groups to load.

initialize_api_discovery() — has a hardcoded 7-tuple:

apis: tuple[ApiHandler[Any], ...] = (
    self.basic_device_info, self.io_port_management, self.light_control,
    self.mqtt, self.pir_sensor_configuration, self.stream_profiles, self.view_areas,
)
await asyncio.gather(*[api.update() for api in apis if api.supported])

initialize_applications() — has a hardcoded 5-tuple:

apps: tuple[ApiHandler[Any], ...] = (
    self.fence_guard, self.loitering_guard, self.motion_guard,
    self.object_analytics, self.vmd4,
)
await asyncio.gather(*[app.update() for app in apps if app.supported])

initialize_param_cgi() — has 9 conditional branches across two phases. The logic is NOT accidental complexity — it encodes firmware-evolution trade-offs:

Phase 1 (what to load from param.cgi):
  ├─ property_handler: ALWAYS (everything downstream depends on it)
  ├─ brand_handler: ONLY IF basic_device_info didn't load (fallback for device identity)
  ├─ io_port_handler: ONLY IF io_port_management didn't load
  ├─ stream_profile_handler: ONLY IF stream_profiles didn't load
  └─ image_handler: ONLY IF view_areas DID load (supplemental data, not a fallback)

Phase 2 (post-load conditionals, after gather):
  ├─ EARLY EXIT if property_handler failed (all subsequent logic reads from it)
  ├─ light_control: special case — updated here if in params but not api_discovery
  ├─ port_cgi.load_ports(): if io_port_management absent but param-based ports present
  └─ ptz_handler: if property_handler["0"].ptz flag is set

The order of operations in Phase 2 is safety-critical — property_handler["0"].ptz and property_handler["0"].light_control must be populated before those reads can happen, which is why the early-exit guard exists.

---

3. What Already Exists That Can Be Leveraged

ApiHandler already has nearly everything needed for self-registration:

Existing	What It Does
api_id: ApiId | None	Declares which discovery API this handler covers
listed_in_api_discovery	Checks if api_id is in the discovery list
listed_in_parameters	Overridable; defaults False; e.g. LightHandler overrides it
supported	Composes both checks via OR
api_version	Correctly resolves discovered vs. fallback version — dead code, never called
update()	Error-safe (catches Unauthorized/Forbidden/PathNotFound)

ApplicationHandler (subclass of ApiHandler) uses app_name instead of api_id — a different but clean pattern. All app handlers share this base class.

There is no ApiId → handler class mapping anywhere. The 56-value ApiId enum and the 20 handler instances are not connected by any data structure — only by the imperative code in vapix.py.

---

4. Scaling Problems — Quantified

Adding a single new handler today requires touching 3 edit sites inside vapix.py:

Site	Location	Difficulty
Add import	Top ~30 import lines	Trivial
Instantiate self.new_handler = NewHandler(self)	__init__	Trivial
Add to hardcoded tuple in initialize_api_discovery or initialize_applications	Body of init method	Easy to forget

The initialize_param_cgi() site is different — it cannot be reduced to a tuple append; it requires a new conditional block that encodes the fallback relationship. That is appropriate complexity for the problem it solves.

---

5. Architecture Recommendations (All Agents Converge)

The planning agent evaluated three architectures. All agents independently converged on the same recommendation.

What NOT to do

Lazy-load opt-in handlers (Architecture B) is disqualifying for this codebase. Home Assistant calls vapix.initialize() at startup to discover all capabilities and register entities. Lazy loading inverts this — you must know what you want before asking, but you don't know what to ask until after discovery. Chicken-and-egg.

Group-wrapper classes (Architecture C) add coordination objects (ApiDiscoveryHandlerGroup, etc.) but the cross-group state dependencies (initialize_param_cgi needing api_discovery state) leak anyway. Meaningful abstraction only if the handler count approaches 40+.

What TO do — Architecture A (lightweight)

Keep typed attribute declarations on Vapix for strict mypy compatibility and IDE autocomplete. The only change is eliminating the hardcoded tuples by having handlers self-declare their group:

Step 1 — Add to ApiHandler:

class HandlerGroup(enum.Enum):
    API_DISCOVERY = "api_discovery"
    APPLICATION = "application"

class ApiHandler(...):
    handler_group: ClassVar[HandlerGroup | None] = None

Step 2 — Annotate each handler:

class LightHandler(ApiHandler[LightInformation]):
    handler_group = HandlerGroup.API_DISCOVERY
    # (already has api_id, default_api_version, listed_in_parameters override)

Step 3 — Replace the two hardcoded tuples:

# initialize_api_discovery — was: hardcoded 7-tuple
handlers = [
    v for v in vars(self).values()
    if isinstance(v, ApiHandler)
    and v.handler_group == HandlerGroup.API_DISCOVERY
]
await asyncio.gather(*[h.update() for h in handlers if h.supported])

# initialize_applications — was: hardcoded 5-tuple
# Already works cleanly via isinstance(v, ApplicationHandler)
apps = [v for v in vars(self).values() if isinstance(v, ApplicationHandler)]
await asyncio.gather(*[app.update() for app in apps if app.supported])

After this change, adding a new handler = 2 edit sites (import + typed attribute). The initialize_* methods are permanently frozen — no further edits ever needed.

Step 4 (separate): Fix dead api_version property
Thread self.api_version into request construction in every handler — identified in the previous session. Until then, BasicDeviceInfoHandler uses the manually-fetched discovery version, LightHandler passes self.default_api_version (ignores discovery), and IoPortManagement hardcodes a module constant.

---

6. initialize_param_cgi — What Should Happen to It

Leave the conditional logic procedural — it is correct-by-design, not a code smell.

The complexity is real: it reflects the fact that Axis firmware has been evolving from param.cgi-based APIs toward REST/JSON APIs (api_discovery) over multiple generations, and devices must degrade gracefully. Each conditional branch exists because some firmware version boundary exists at Axis. This logic cannot be replaced with metadata without making the metadata more complex than the code it replaces.

What CAN be improved: add a comment block on each conditional branch explaining the firmware contract it encodes, e.g.:

# basic_device_info was introduced in firmware 9.80; older devices fall back to
# params.brand_handler which covers the same product identity data via param.cgi
if not self.basic_device_info.supported or not self.basic_device_info.initialized:
    tasks.append(self.params.brand_handler.update())

This makes the logic reviewable and maintainable without restructuring it.

---

7. What preload_data=True vs preload_data=False Actually Means

The preload_data parameter is a performance optimization switch that exists because the method serves two callers with different needs:

Caller	Mode	Why
initialize()	preload_data=False	api_discovery already ran, only load param groups not covered by REST APIs
External callers (e.g. HA re-poll)	preload_data=True	Load everything at once in a single request, cheaper

The naming preload_data is slightly misleading — it actually means "load all param groups regardless of fallback logic." A clearer name would be full_load: bool = True with a docstring noting the distinction. Not a blocking issue, but a readability gap.

---

8. Summary — Priority-Ordered Action Items

#	Action	Risk	Complexity	Value
1	Add HandlerGroup to ApiHandler, annotate 7 api-discovery handlers, replace hardcoded tuples	Very low	Small	Eliminates manual tuple maintenance forever
2	Replace initialize_applications hardcoded tuple with isinstance(v, ApplicationHandler) scan	Very low	Trivial	Same win, app handlers already share base class
3	Add firmware-rationale comments to each branch in initialize_param_cgi	Zero	Trivial	Turns opaque logic into documented intent
4	Thread self.api_version into all _update() request construction (from prior session)	Low	Medium	Closes the dead-code gap; correct behavior on version-boundary devices
5	Rename preload_data → select_load or targeted_load with docstring clarification	Zero	Trivial	Readability improvement only

Items 1–3 are a clean bounded refactor. Item 4 is a separate bug-fix track (separate PR). Item 5 is optional cleanup.

Similar code found with 1 license type

[Kane610]

Short answer: yes, but not fully automatic reflection-based discovery.

Best practice here is a hybrid:

1. Keep explicit, typed handler attributes for public API stability and mypy clarity.
2. Make initialization dynamic via handler metadata and group filtering.
3. Keep parameter fallback orchestration explicit because it encodes real firmware compatibility rules.

Why this is the right balance:

1. Fully dynamic registration (scan/import all subclasses and auto-attach everything) declutters one place but hurts type safety, discoverability, and predictable startup behavior.
2. Fully manual registration (current style) scales poorly as handlers grow and forces edits in multiple places.
3. Hybrid gives most decluttering with low risk: adding a handler should not require touching initialization pipelines.

What to improve first (highest value):

1. Add handler group metadata on base handler.
2. Replace hardcoded initialization tuples with group-driven iteration.
3. Keep explicit attributes on vapix.py for stable external API and strict typing.
4. Keep fallback logic in initialize_param_cgi explicit, but document each branch rationale.
5. Introduce optional capability profiles (all, minimal, applications-only) for opt-in loading where needed, while keeping default as load-all for Home Assistant use.

Recommended target architecture:

1. Registration model: declarative metadata per handler class.
2. Runtime model: dynamic init/update selection by group and support checks.
3. Public API model: explicit named attributes remain.
4. Compatibility model: fallback chains stay imperative and ordered.
5. Performance model: optional profile-based initialization, not lazy-by-default.

Answer to your core question:

1. Should all interfaces be dynamically registered to declutter design? Partially yes.
2. Should everything be auto-discovered and attached dynamically? No, not in this project.
3. Best improvement path: dynamic initialization orchestration + explicit typed surface.

If you want, next step can be a concrete implementation plan in 3 PR-sized phases against vapix.py and api_handler.py.