"""Session management: create and release session keys via the RemoteControl API. - ``get_session_key(client, username, password) -> str`` Raises ``LsAuthError`` when the login is refused. Note: LimeSurvey puts ``{"status": "Invalid user name or password!"}`` in the **result** (not in ``error``) on a failed login — this is handled here. - ``release_session_key(client, session_key)`` """ from __future__ import annotations from typing import Any from .errors import LsAuthError from .rpc import RpcClient def get_session_key(client: RpcClient, username: str, password: str) -> str: """Request a session key from the RemoteControl endpoint. Args: client: an ``RpcClient`` (fixed endpoint URL). username: RemoteControl user. password: password (or API token). Returns: The session key as a string. Raises: LsAuthError: when the login is refused (wrong credentials or blocked user). LsConnectionError: when the server is unreachable. """ result = client.call("get_session_key", [username, password]) if isinstance(result, str) and result: return result # LS error pattern: result = {"status": "Invalid user name or password!"} status = result.get("status") if isinstance(result, dict) else result raise LsAuthError( f"Login failed (get_session_key): {status!r}", method="get_session_key", rpc_message=str(status), raw=result, ) def release_session_key(client: RpcClient, session_key: str) -> Any: """Release a session key properly (returns the RPC result).""" return client.call("release_session_key", [session_key])