- responses.py: get_summary() (raw RPC get_summary), count_responses() -> frozen ResponseCounts(completed, incomplete, total), export_responses_auto() with automatic format fallback (xlsx -> xls -> csv) on IWriter errors - utils.py: summary_counts_full() -> (completed, incomplete, total) with per-LS-version key fallbacks; summary_counts left untouched - surveys.py: get_survey_by_sid() (dict | None), get_survey_info() -> frozen SurveyInfo(sid, title, active) - tokens.py: documented that extra/custom token attributes (attribute_1, ...) pass through unchanged in add_participants/list_participants - LsClient: get_summary, count_responses, get_survey_by_sid, get_survey_info, export_responses_auto; __all__ + re-exports updated - README: new "Response counts & summary" section + usage examples - .gitignore: prompts.md added (local-only docs, like werkdocument.md) - version 0.1.0 -> 0.2.0 (__init__.py + pyproject.toml) - tests: +27 FakeRpc unit tests (96 passed, 2 deselected) Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
174 lines
5.7 KiB
Python
174 lines
5.7 KiB
Python
"""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")),
|
|
)
|