PyLimeRPC/pylimerpc/responses.py
Tammo ter Hark d7d9dc61bf PyLimeRPC: package pylimerpc + pyproject + tests/examples (overname van minimalLS)
- nieuwe package `pylimerpc/` (rpc, session, surveys, tokens, responses, errors, utils, config)
- pyproject.toml (name PyLimeRPC, versie 0.1.0)
- tests/ (69 passed, 2 deselected) en examples/
- .env.example: TLS-verificatie documentatie (LIMESURVEY_VERIFY_SSL)
- README/.gitignore bijgewerkt

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 12:26:35 +01:00

154 lines
5 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**
Both 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
from pathlib import Path
from typing import Any
from .errors import LsApiError
from .rpc import RpcClient
from .utils import normalize_sid, parse_responses_json, raise_for_status
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_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