"""Custom exceptions of the library. Hierarchy: - ``LsError`` — base class for all pylimerpc errors - ``LsConnectionError(LsError)`` — network/server unreachable (DNS, timeout, HTTP error status, no valid JSON-RPC response); keeps ``url``, ``cause``, ``http_status`` and ``body`` - ``LsApiError(LsError)`` — the API returned a JSON-RPC error; keeps the original RPC error (``rpc_code``, ``rpc_message``, ``raw``) plus ``method``, ``http_status`` and ``body`` for diagnosis - ``LsAuthError(LsApiError)`` — login refused or session key invalid/expired This lets callers catch specifically: connection problem vs. API error vs. auth error. """ from __future__ import annotations from typing import Any class LsError(Exception): """Base class for all pylimerpc errors.""" class LsConnectionError(LsError): """The server was unreachable or did not return a valid JSON-RPC response. Attributes: url — the endpoint that was called cause — the underlying exception (e.g. ``urllib.error.URLError``) http_status — HTTP status if the server did respond (e.g. 500), else None body — (truncated) response body, for diagnosis """ def __init__( self, message: str, *, url: str | None = None, cause: BaseException | None = None, http_status: int | None = None, body: str | None = None, ) -> None: super().__init__(message) self.url = url self.cause = cause self.http_status = http_status self.body = body class LsApiError(LsError): """LimeSurvey returned a JSON-RPC error. Keeps the original RPC error plus diagnostic info: method — the RPC method that was called (e.g. ``list_surveys``) rpc_code — the status/code from the JSON-RPC error object rpc_message — the message from the JSON-RPC error object raw — the complete, original error object http_status — HTTP status of the response body — (truncated) response body """ def __init__( self, message: str, *, method: str | None = None, rpc_code: int | str | None = None, rpc_message: str | None = None, raw: Any = None, http_status: int | None = None, body: str | None = None, ) -> None: super().__init__(message) self.method = method self.rpc_code = rpc_code self.rpc_message = rpc_message self.raw = raw self.http_status = http_status self.body = body class LsAuthError(LsApiError): """Login failed or the session key is invalid / expired / refused."""