"""Query surveys via the RemoteControl API. - ``list_surveys(client, session_key, owner_id=None, group_id=None)`` — list of survey dicts (``owner_id`` is sent as the 2nd RPC param ``iUserID``; ``group_id`` filters client-side on ``group_id``/``gsid`` when present) - ``get_survey_properties(client, session_key, sid, properties=None)`` — properties dict of a single survey - ``get_survey_by_sid(client, session_key, sid, owner_id=None, group_id=None)`` — one survey dict from ``list_surveys`` by sid, or ``None`` - ``get_survey_info(client, session_key, sid)`` — compact ``SurveyInfo`` (sid/title/active), or ``None`` when the survey does not exist - ``filter_active(surveys)`` — only active surveys (``active == "Y"``) """ from __future__ import annotations from dataclasses import dataclass from typing import Any, Iterable from .errors import LsApiError from .rpc import RpcClient from .utils import is_active_flag, raise_for_status, to_int _GROUP_KEYS = ("group_id", "gsid", "group") def _survey_group_id(survey: dict[str, Any]) -> Any: for key in _GROUP_KEYS: if key in survey: return survey[key] return None def list_surveys( client: RpcClient, session_key: str, owner_id: int | str | None = None, group_id: int | str | None = None, ) -> list[dict[str, Any]]: """List all surveys the session key has access to. Args: client: an ``RpcClient``. session_key: a valid session key. owner_id: optional, sent as the 2nd RPC parameter (``iUserID``). group_id: optional, client-side filter on a group field in the result. Returns: List of survey dicts (``sid``, ``surveyls_title``, ``active``, ...). Raises: LsAuthError: invalid session key; LsApiError: other API errors. """ params: list[Any] = [session_key] if owner_id is not None: as_int = to_int(owner_id) params.append(as_int if as_int is not None else owner_id) result = client.call("list_surveys", params) raise_for_status(result, "list_surveys") if not isinstance(result, list): raise LsApiError( f"list_surveys did not return a list: {result!r}", method="list_surveys", raw=result, ) surveys = [s for s in result if isinstance(s, dict)] if group_id is not None: surveys = [s for s in surveys if str(_survey_group_id(s)) == str(group_id)] return surveys def get_survey_properties( client: RpcClient, session_key: str, sid: int | str, properties: Iterable[str] | None = None, ) -> dict[str, Any]: """Get the properties of a single survey. Args: client: an ``RpcClient``. session_key: a valid session key. sid: survey ID (numeric strings are converted to int). properties: optional list of property names; None = all. Returns: Dict with survey properties (contains e.g. ``sid``, ``surveyls_title``, ``active``). """ sid_int = to_int(sid) params: list[Any] = [session_key, sid_int if sid_int is not None else sid] if properties: params.append(list(properties)) result = client.call("get_survey_properties", params) raise_for_status(result, "get_survey_properties") if not isinstance(result, dict): raise LsApiError( f"get_survey_properties did not return a dict: {result!r}", method="get_survey_properties", raw=result, ) return result def filter_active(surveys: Iterable[dict[str, Any]]) -> list[dict[str, Any]]: """Filter a survey list to active surveys only (``active == "Y"``).""" return [s for s in surveys if is_active_flag(s.get("active"))] @dataclass(frozen=True) class SurveyInfo: """Compact info about a survey, built from a ``list_surveys`` entry. Fields: ``sid``, ``title`` (``surveyls_title``) and ``active``. """ sid: int title: str active: bool def get_survey_by_sid( client: RpcClient, session_key: str, sid: int | str, owner_id: int | str | None = None, group_id: int | str | None = None, ) -> dict[str, Any] | None: """Find one survey by sid in the ``list_surveys`` result. Args: client: an ``RpcClient``. session_key: a valid session key. sid: survey ID to look for (matched as ``str(sid)`` against each entry). owner_id: optional, passed through to ``list_surveys``. group_id: optional, passed through to ``list_surveys``. Returns: The survey dict, or ``None`` when no survey with this sid exists — "does not exist" is NOT an exception. Raises: LsAuthError / LsApiError: propagated from ``list_surveys`` (e.g. a ``{"status": ...}`` result is raised via ``raise_for_status``). """ surveys = list_surveys(client, session_key, owner_id=owner_id, group_id=group_id) for survey in surveys: if str(survey.get("sid")) == str(sid): return survey return None def get_survey_info(client: RpcClient, session_key: str, sid: int | str) -> SurveyInfo | None: """Compact info (sid / title / active) of a survey. Built from ``get_survey_by_sid``; handy for apps that want "does not exist / not active / title" in a single call. Returns: ``SurveyInfo(sid, title, active)``, or ``None`` when the survey does not exist. """ survey = get_survey_by_sid(client, session_key, sid) if survey is None: return None sid_int = to_int(survey.get("sid")) if sid_int is None: sid_int = to_int(sid) or 0 title = survey.get("surveyls_title") if title is None: title = survey.get("title") return SurveyInfo( sid=sid_int, title=str(title) if title is not None else "", active=is_active_flag(survey.get("active")), )