Summary
Deferred follow-up from #95 (comprehensive repo evaluation, batch 6: architecture cleanup).
Several public/semi-public signatures in the MQTT layer still expose awscrt SDK types directly, e.g.:
awscrt.mqtt.QoS as a parameter/return type (mqtt/connection.py, mqtt/subscriptions.py, mqtt/client.py)
awscrt.mqtt.Connection as an internal connection handle type
awscrt.exceptions.AwsCrtError surfacing directly from library calls instead of being translated into the library's own exception hierarchy (MqttError and subclasses)
This leaks a third-party dependency's types into the library's own API surface, coupling callers (including the Home Assistant integration) to awscrt's versioning and making it harder to swap the underlying MQTT transport in the future.
Suggested approach
- Introduce a library-owned
QoS-equivalent enum (or reuse an existing nwp500 enum if one covers this) and translate to/from awscrt.mqtt.QoS at the connection-layer boundary.
- Ensure
AwsCrtError is always caught and re-raised/wrapped as an nwp500 exception (e.g. MqttError) at public API boundaries, per the project's exception-handling conventions (specific exception types, no leaking SDK exceptions).
- Audit all public method signatures in
nwp500/mqtt/ and nwp500/__init__.py-exported names for remaining awscrt type references.
Acceptance criteria
- No
awscrt types appear in the signatures of public/exported classes or methods.
- Existing behavior unchanged;
awscrt remains an internal implementation detail.
ruff/mypy clean, tests updated accordingly.
Summary
Deferred follow-up from #95 (comprehensive repo evaluation, batch 6: architecture cleanup).
Several public/semi-public signatures in the MQTT layer still expose
awscrtSDK types directly, e.g.:awscrt.mqtt.QoSas a parameter/return type (mqtt/connection.py,mqtt/subscriptions.py,mqtt/client.py)awscrt.mqtt.Connectionas an internal connection handle typeawscrt.exceptions.AwsCrtErrorsurfacing directly from library calls instead of being translated into the library's own exception hierarchy (MqttErrorand subclasses)This leaks a third-party dependency's types into the library's own API surface, coupling callers (including the Home Assistant integration) to
awscrt's versioning and making it harder to swap the underlying MQTT transport in the future.Suggested approach
QoS-equivalent enum (or reuse an existingnwp500enum if one covers this) and translate to/fromawscrt.mqtt.QoSat the connection-layer boundary.AwsCrtErroris always caught and re-raised/wrapped as annwp500exception (e.g.MqttError) at public API boundaries, per the project's exception-handling conventions (specific exception types, no leaking SDK exceptions).nwp500/mqtt/andnwp500/__init__.py-exported names for remainingawscrttype references.Acceptance criteria
awscrttypes appear in the signatures of public/exported classes or methods.awscrtremains an internal implementation detail.ruff/mypyclean, tests updated accordingly.