- 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>
120 lines
4.4 KiB
Python
120 lines
4.4 KiB
Python
"""Token management (participants / invite codes) via the RemoteControl API.
|
|
|
|
LS7 RemoteControl methods called here (lay these next to the API docs):
|
|
|
|
- ``add_participants`` — params ``[session_key, sid, [participant dicts]]``
|
|
(+ optional ``create_token`` as 4th param)
|
|
- ``list_participants`` — params ``[session_key, sid, start, limit]``
|
|
(+ optional ``conditions`` and ``language`` in the following positions)
|
|
- ``delete_participants`` — params ``[session_key, sid, [token_ids]]``
|
|
|
|
Each participant is a dict with e.g. ``email``, ``firstname``, ``lastname``,
|
|
``token`` (``token`` is generated by LS on add_participants). Surveys can define
|
|
**extra (custom) token attributes** (``attribute_1``, ``attribute_2``, ...);
|
|
those keys are passed through verbatim in both directions — on add they are
|
|
sent along in the participant dict, on list they are part of the returned dicts.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Any
|
|
|
|
from .errors import LsApiError
|
|
from .rpc import RpcClient
|
|
from .utils import normalize_sid, raise_for_status, to_int
|
|
|
|
|
|
def add_participants(
|
|
client: RpcClient,
|
|
session_key: str,
|
|
sid: int | str,
|
|
participants: list[dict[str, Any]],
|
|
*,
|
|
create_token: bool | None = None,
|
|
) -> Any:
|
|
"""Add participants (tokens) to a survey.
|
|
|
|
LS7 RPC method: ``add_participants`` with params
|
|
``[session_key, sid, participants]`` (+ ``create_token`` as 4th param).
|
|
|
|
Args:
|
|
client: an ``RpcClient``.
|
|
session_key: a valid session key.
|
|
sid: survey ID.
|
|
participants: list of dicts, e.g. ``[{"email": "a@b.c", "firstname": "A"}]``.
|
|
Extra/custom token attributes (``attribute_1``, ...) may be included
|
|
as extra keys; they are sent to LS unchanged.
|
|
create_token: optional; if False, no token is created.
|
|
|
|
Returns:
|
|
The LS result: per participant a dict with e.g. ``tid`` and ``token``.
|
|
"""
|
|
if not isinstance(participants, list) or not all(isinstance(p, dict) for p in participants):
|
|
raise TypeError("participants must be a list of dicts")
|
|
params: list[Any] = [session_key, normalize_sid(sid), participants]
|
|
if create_token is not None:
|
|
params.append(bool(create_token))
|
|
result = client.call("add_participants", params)
|
|
raise_for_status(result, "add_participants")
|
|
return result
|
|
|
|
|
|
def list_participants(
|
|
client: RpcClient,
|
|
session_key: str,
|
|
sid: int | str,
|
|
*,
|
|
start: int = 0,
|
|
limit: int = 100000,
|
|
conditions: dict[str, Any] | None = None,
|
|
language: str | None = None,
|
|
) -> list[dict[str, Any]]:
|
|
"""List the participants of a survey.
|
|
|
|
LS7 RPC method: ``list_participants`` with params
|
|
``[session_key, sid, start, limit]`` (+ optional ``conditions``, ``language``).
|
|
|
|
Returns:
|
|
List of participant dicts (``tid``, ``email``, ``token``, ``completed``, ...,
|
|
plus any extra/custom token attributes such as ``attribute_1`` — returned
|
|
unchanged, exactly as LS sends them).
|
|
"""
|
|
params: list[Any] = [session_key, normalize_sid(sid), int(start), int(limit)]
|
|
if conditions is not None:
|
|
params.append(conditions)
|
|
if language is not None:
|
|
params.append(language)
|
|
result = client.call("list_participants", params)
|
|
raise_for_status(result, "list_participants")
|
|
if isinstance(result, dict) and isinstance(result.get("participants"), list):
|
|
return result["participants"]
|
|
if isinstance(result, list):
|
|
return [p for p in result if isinstance(p, dict)]
|
|
raise LsApiError(
|
|
f"list_participants did not return a list: {result!r}",
|
|
method="list_participants",
|
|
raw=result,
|
|
)
|
|
|
|
|
|
def delete_participants(
|
|
client: RpcClient,
|
|
session_key: str,
|
|
sid: int | str,
|
|
token_ids: list[int | str],
|
|
) -> Any:
|
|
"""Delete participants (tokens) from a survey.
|
|
|
|
LS7 RPC method: ``delete_participants`` with params
|
|
``[session_key, sid, token_ids]``.
|
|
|
|
Returns:
|
|
The LS result: dict with a status per token id (e.g. ``{"1": "OK"}``).
|
|
"""
|
|
if not isinstance(token_ids, (list, tuple)):
|
|
raise TypeError("token_ids must be a list of ids")
|
|
coerced = [to_int(t) if to_int(t) is not None else t for t in token_ids]
|
|
params: list[Any] = [session_key, normalize_sid(sid), coerced]
|
|
result = client.call("delete_participants", params)
|
|
raise_for_status(result, "delete_participants")
|
|
return result
|