PyLimeRPC/pylimerpc/responses.py
Tammo ter Hark 6822eab467 PyLimeRPC 0.2.0 — prompts.md Prompt 1-4
- 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>
2026-11-20 11:56:03 +01:00

269 lines
9.1 KiB
Python

"""Response and statistics export via the RemoteControl API.
LS7 RemoteControl methods called here (lay these next to the API docs):
- ``export_responses`` — params ``[session_key, sid, doc_type, language,
completion_status, field_map, header]``; the result is **base64-encoded**
- ``export_statistics`` — params ``[session_key, sid, doc_type, language]``;
also **base64-encoded**
- ``get_summary`` — params ``[session_key, sid]``; result is a dict with,
among other things, the response counts
``export_responses_auto`` tries several ``doc_type`` formats in order and falls
back on the next one when the LS installation lacks a writer (e.g. the xlsx
writer: "Writer for xlsx should implement IWriter").
Both export functions decode the base64 and return ``bytes``; with
``output_path`` the file is written and the ``Path`` is returned (if
``output_path`` is an existing directory, a default name
``survey_<sid>_responses.<ext>`` is used).
"""
from __future__ import annotations
import base64
import binascii
import logging
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable
from .errors import LsApiError
from .rpc import RpcClient
from .utils import normalize_sid, parse_responses_json, raise_for_status, summary_counts_full
logger = logging.getLogger(__name__)
def _decode_base64(result: Any, method: str) -> bytes:
"""Decode the base64 result of an export RPC; raise LsApiError on empty/invalid data."""
if not isinstance(result, str) or not result:
raise LsApiError(
f"{method} did not return a base64 string: {result!r}",
method=method,
raw=result,
)
try:
return base64.b64decode(result)
except (binascii.Error, ValueError) as exc:
raise LsApiError(
f"{method} did not return valid base64: {exc}",
method=method,
raw=str(result)[:200],
) from exc
def _ext(doc_type: str) -> str:
return doc_type if doc_type.isalnum() else "bin"
def _write_output(data: bytes, output_path: str | Path, default_name: str) -> Path:
path = Path(output_path)
if path.is_dir():
path = path / default_name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(data)
return path
def export_responses(
client: RpcClient,
session_key: str,
sid: int | str,
doc_type: str = "json",
*,
language: str | None = None,
completion_status: str = "all",
field_map: str = "code",
header: str = "short",
output_path: str | Path | None = None,
) -> bytes | Path:
"""Export the responses of a survey.
LS7 RPC method: ``export_responses`` with params
``[session_key, sid, doc_type, language, completion_status, field_map, header]``.
Args:
client: an ``RpcClient``.
session_key: a valid session key.
sid: survey ID.
doc_type: ``"json"``, ``"csv"``, ``"xls"``/``"xlsx"``, ``"spss"``, ...
language: language code or None (default language).
completion_status: ``"all"``, ``"complete"`` or ``"incomplete"``.
field_map: ``"code"`` or ``"title"`` (question coding in the export).
header: ``"short"`` or ``"full"``.
output_path: optional file path (or directory) to save the export to.
Returns:
The decoded export as ``bytes``; with ``output_path``, the ``Path`` of the file.
"""
params: list[Any] = [
session_key,
normalize_sid(sid),
doc_type,
language,
completion_status,
field_map,
header,
]
result = client.call("export_responses", params)
raise_for_status(result, "export_responses")
data = _decode_base64(result, "export_responses")
if output_path is not None:
return _write_output(data, output_path, f"survey_{sid}_responses.{_ext(doc_type)}")
return data
def export_responses_auto(
client: RpcClient,
session_key: str,
sid: int | str,
formats: Iterable[str] = ("xlsx", "xls", "csv"),
**kwargs: Any,
) -> tuple[bytes | Path, str]:
"""Export responses, trying the formats in order until one works.
Not every LS installation has every export writer installed — for example
the xlsx writer may be missing, in which case LS returns an error like
"Writer for xlsx should implement IWriter". This function tries each
format in ``formats`` and falls back to the next one on exactly that error
(an ``LsApiError`` whose message or ``rpc_message`` contains ``"IWriter"``);
any other error is raised immediately.
Args:
client: an ``RpcClient``.
session_key: a valid session key.
sid: survey ID.
formats: doc types to try, in order (default ``("xlsx", "xls", "csv")``).
**kwargs: passed to ``export_responses`` (e.g. ``output_path``).
Returns:
``(data, used_format)`` — ``data`` as ``bytes``, or ``Path`` when
``output_path`` was given; ``used_format`` is the ``doc_type`` that worked.
Raises:
LsApiError: when every format fails with an IWriter error (the last one
is re-raised), or immediately on any other error.
"""
last_exc: LsApiError | None = None
for doc_type in formats:
try:
data = export_responses(client, session_key, sid, doc_type, **kwargs)
except LsApiError as exc:
if "IWriter" in str(exc) or "IWriter" in str(exc.rpc_message or ""):
last_exc = exc
logger.debug("export_responses doc_type=%r unavailable (%s); trying next format", doc_type, exc)
continue
raise
return data, doc_type
if last_exc is not None:
raise last_exc
raise LsApiError(
f"export_responses_auto: no formats to try: {formats!r}",
method="export_responses_auto",
)
def export_responses_json(
client: RpcClient,
session_key: str,
sid: int | str,
**kwargs: Any,
) -> list[dict[str, Any]]:
"""Convenience wrapper: ``export_responses(doc_type="json")`` as ``list[dict]``.
Accepts the same kwargs as ``export_responses`` (except ``doc_type``).
"""
kwargs.pop("doc_type", None)
data = export_responses(client, session_key, sid, "json", **kwargs)
if isinstance(data, Path):
data = data.read_bytes()
return parse_responses_json(data.decode("utf-8"))
def export_statistics(
client: RpcClient,
session_key: str,
sid: int | str,
doc_type: str = "json",
*,
language: str | None = None,
output_path: str | Path | None = None,
) -> bytes | Path:
"""Export the statistics of a survey.
LS7 RPC method: ``export_statistics`` with params
``[session_key, sid, doc_type, language]``.
Args:
client: an ``RpcClient``.
session_key: a valid session key.
sid: survey ID.
doc_type: ``"json"`` or ``"csv"``.
language: language code or None.
output_path: optional file path (or directory) to save the export to.
Returns:
The decoded export as ``bytes``; with ``output_path``, the ``Path`` of the file.
"""
params: list[Any] = [session_key, normalize_sid(sid), doc_type, language]
result = client.call("export_statistics", params)
raise_for_status(result, "export_statistics")
data = _decode_base64(result, "export_statistics")
if output_path is not None:
return _write_output(data, output_path, f"survey_{sid}_statistics.{_ext(doc_type)}")
return data
@dataclass(frozen=True)
class ResponseCounts:
"""Response counts of a survey.
Fields: ``completed`` (finished), ``incomplete`` (in progress) and ``total``.
"""
completed: int
incomplete: int
total: int
def get_summary(client: RpcClient, session_key: str, sid: int | str) -> dict[str, Any]:
"""Raw RPC ``get_summary`` — summary of a survey.
LS7 RPC method: ``get_summary`` with params ``[session_key, sid]``.
Args:
client: an ``RpcClient``.
session_key: a valid session key.
sid: survey ID (a numeric string is normalized to int).
Returns:
The summary dict (contains, among other things, the response counts).
Raises:
LsApiError: on a ``{"status": ...}`` error or if the result is not a dict.
"""
params: list[Any] = [session_key, normalize_sid(sid)]
result = client.call("get_summary", params)
raise_for_status(result, "get_summary")
if not isinstance(result, dict):
raise LsApiError(
f"RPC 'get_summary' returned no dict: {result!r}",
method="get_summary",
raw=result,
)
return result
def count_responses(client: RpcClient, session_key: str, sid: int | str) -> ResponseCounts:
"""Count the responses of a survey via ``get_summary``.
Reads the counts from the summary dict (key names differ per LS version;
missing/invalid values count as 0) — see ``utils.summary_counts_full``.
Returns:
``ResponseCounts(completed, incomplete, total)``.
"""
summary = get_summary(client, session_key, sid)
completed, incomplete, total = summary_counts_full(summary)
return ResponseCounts(completed=completed, incomplete=incomplete, total=total)