[davidski]

Closes #1

Summary

Opt-in raise_errors=True makes the client raise typed exceptions instead of returning {"success": False, ...}. The default behaviour is unchanged.

EmoncmsError                  # any other non-200 or bad JSON
├── EmoncmsAuthError          # HTTP 401 (invalid API key)
└── EmoncmsConnectionError    # aiohttp ClientError or timeout

 async_request(path)
   GET url
-  ClientError / timeout  -> return {"success": False, "message": ...}
-  401                    -> return {"success": False, "message": "error 401 ..."}
+  ClientError / timeout  -> raise EmoncmsConnectionError   (if raise_errors)
+  401                    -> raise EmoncmsAuthError         (if raise_errors)
+  other non-200          -> raise EmoncmsError             (if raise_errors)
+  otherwise              -> same dict as today

 async_input_post(data)
+  uses request_timeout (previously had no timeout)
+  same exception mapping when raise_errors
   non-200 without raise_errors -> RuntimeError (unchanged)

async_get_uuid, async_list_feeds and async_get_feed_fields call async_request, so they raise too. When raising, the library logs at debug instead of error, leaving error reporting to the caller. This avoids duplicate log lines in Home Assistant (log-when-unavailable).

Home Assistant will use this to tell ConfigEntryAuthFailed (reauth) apart from ConfigEntryNotReady (retry), as required by the test-before-setup, test-before-configure and reauthentication-flow quality-scale rules.

Evidence

• Before (main): a bad key and a missing server look identical, and a bad key sends HA users to the "upgrade Emoncms" repair:

  bad key   -> None
  no server -> None
  

  After (raise_errors=True):

  bad key   -> EmoncmsAuthError error 401 unauthorized access
  no server -> EmoncmsConnectionError client error : Cannot connect to host ...
  

• New tests, all 8 passing:

  test_raise_auth_error      401 -> EmoncmsAuthError (async_list_feeds, async_get_uuid)
  test_raise_timeout         timeout -> EmoncmsConnectionError
  test_raise_client_error    refused -> EmoncmsConnectionError (request + input_post), no ERROR logs
  test_input_post            200 ok; 401 -> EmoncmsAuthError; 500 -> EmoncmsError;
                             default mode still RuntimeError
  

Merge Danger

Door: two-way

The flag is opt-in and defaults to False. Once released, the exception names become public API that the Home Assistant integration depends on.

Blast Radius: minimal

Existing callers keep the dict and None returns. The one change in default mode is that async_input_post now times out after request_timeout (20 s) instead of waiting indefinitely. The version is bumped to 0.1.4.