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>
This commit is contained in:
Tammo ter Hark 2026-11-20 11:56:03 +01:00
commit 6822eab467
13 changed files with 633 additions and 24 deletions

3
.gitignore vendored
View file

@ -24,8 +24,9 @@ survey_*_statistics.*
*.xlsx
*.spss
# Local working document (never synced to Forgejo)
# Local working documents (never synced to Forgejo)
werkdocument.md
prompts.md
# Packaging (pip install -e .)
build/

View file

@ -41,8 +41,8 @@ pylimerpc/
config.py # .env reading (standard library, no python-dotenv)
rpc.py # JSON-RPC transport: build request, POST, handle errors
session.py # get_session_key / release_session_key
surveys.py # list_surveys, get_survey_properties
responses.py # export_responses (CSV/JSON), export_statistics
surveys.py # list_surveys, get_survey_properties, get_survey_by_sid, get_survey_info
responses.py # export_responses (CSV/JSON), export_responses_auto, export_statistics, get_summary, count_responses
tokens.py # token management: add/list/delete participants
errors.py # LsConnectionError, LsApiError, LsAuthError
utils.py # shared helpers
@ -74,6 +74,8 @@ cfg = LsConfig.from_dotenv(".env")
with LsClient(cfg) as ls: # opens a session, releases the key on exit
surveys = ls.list_surveys() # all surveys of this user
props = ls.get_survey_properties(surveys[0]["sid"])
info = ls.get_survey_info(surveys[0]["sid"]) # → SurveyInfo(sid, title, active) or None
survey = ls.get_survey_by_sid(surveys[0]["sid"]) # raw dict from list_surveys, or None
```
Low level (without session management): `RpcClient.from_config(cfg).call(method, params)`.
@ -81,15 +83,49 @@ Low level (without session management): `RpcClient.from_config(cfg).call(method,
```python
with LsClient(cfg) as ls:
data = ls.export_responses(sid, doc_type="csv", output_path="output/") # → Path
# automatic format fallback (xlsx → xls → csv) when the LS install lacks a writer:
data, used_format = ls.export_responses_auto(sid) # → (bytes | Path, "xls")
stats = ls.export_statistics(sid) # → bytes
ls.add_participants(sid, [{"email": "a@b.c", "firstname": "A"}])
participants = ls.list_participants(sid)
summary = ls.get_summary(sid) # raw dict
counts = ls.count_responses(sid) # → ResponseCounts(completed, incomplete, total)
# extra/custom token attributes (attribute_1, ...) pass through unchanged:
ls.add_participants(sid, [{"email": "a@b.c", "firstname": "A", "attribute_1": "blue"}])
participants = ls.list_participants(sid) # dicts include any attribute_* keys
ls.delete_participants(sid, [participants[0]["tid"]])
```
LS7 RemoteControl methods: `export_responses`, `export_statistics`,
LS7 RemoteControl methods: `export_responses`, `export_statistics`, `get_summary`,
`add_participants`, `list_participants`, `delete_participants` (base64 exports
are decoded automatically).
are decoded automatically). `count_responses` reads the response counts from
the `get_summary` result (key names differ per LS version; missing/invalid
values count as 0).
## Response counts & summary
`get_summary` returns the raw summary dict of a survey (LS7 RPC `get_summary`,
params `[session_key, sid]`); `count_responses` turns it into a frozen
`ResponseCounts` dataclass:
```python
from pylimerpc import LsClient, LsConfig
cfg = LsConfig.from_dotenv(".env")
with LsClient(cfg) as ls:
summary = ls.get_summary(sid) # raw dict, e.g. {"completed_responses": 14, ...}
counts = ls.count_responses(sid) # ResponseCounts(completed=14, incomplete=41, total=55)
print(counts.completed, counts.incomplete, counts.total)
```
Key names in the summary differ per LS version: `completed_responses`
(fallbacks `responses_completed` / `completed`), `incomplete_responses`
(fallback `in_progress_responses`), and `full_responses` for the total when
present (otherwise `total = completed + incomplete`). Missing or invalid
values count as 0.
Related: `ls.get_survey_info(sid)` → `SurveyInfo(sid, title, active)` or `None`
("does not exist / not active / title" in one call), and
`ls.export_responses_auto(sid)` → `(data, used_format)` with automatic format
fallback (xlsx → xls → csv) when the LS installation lacks a writer.
Errors: `LsConnectionError` (server unreachable/HTTP error), `LsApiError`
(JSON-RPC error, with `rpc_code`/`rpc_message`), `LsAuthError` (login refused).

View file

@ -16,8 +16,8 @@ Modules:
config — settings from .env / environment variables (LsConfig)
rpc — JSON-RPC transport (rpc_call, RpcClient, endpoint_url)
session — session keys: get_session_key / release_session_key
surveys — list_surveys, get_survey_properties, filter_active
responses — export_responses (CSV/JSON), export_statistics
surveys — list_surveys, get_survey_properties, get_survey_by_sid, get_survey_info, filter_active
responses — export_responses (CSV/JSON), export_responses_auto, export_statistics, get_summary, count_responses
tokens — token management (participants): add / list / delete
errors — custom exceptions (LsError, LsConnectionError, LsApiError, LsAuthError)
utils — small shared helpers
@ -38,15 +38,29 @@ from . import surveys as _surveys
from . import tokens as _tokens
from .config import LsConfig
from .errors import LsApiError, LsAuthError, LsConnectionError, LsError
from .responses import export_responses, export_statistics
from .responses import (
ResponseCounts,
count_responses,
export_responses,
export_responses_auto,
export_statistics,
get_summary,
)
from .rpc import RpcClient, endpoint_url, rpc_call
from .session import get_session_key, release_session_key
from .surveys import filter_active, get_survey_properties, list_surveys
from .surveys import (
SurveyInfo,
filter_active,
get_survey_by_sid,
get_survey_info,
get_survey_properties,
list_surveys,
)
from .tokens import add_participants, delete_participants, list_participants
logger = logging.getLogger(__name__)
__version__ = "0.1.0"
__version__ = "0.2.0"
class LsClient:
@ -123,6 +137,25 @@ class LsClient:
"""Properties of a single survey (see ``surveys.get_survey_properties``)."""
return _surveys.get_survey_properties(self.rpc, self._require_key(), sid, properties=properties)
def get_survey_by_sid(
self,
sid: int | str,
owner_id: int | str | None = None,
group_id: int | str | None = None,
) -> dict[str, Any] | None:
"""Find one survey by sid (see ``surveys.get_survey_by_sid``); ``None`` if it does not exist."""
return _surveys.get_survey_by_sid(
self.rpc,
self._require_key(),
sid,
owner_id=owner_id if owner_id is not None else self.config.owner_id,
group_id=group_id if group_id is not None else self.config.group_id,
)
def get_survey_info(self, sid: int | str) -> SurveyInfo | None:
"""Compact info (sid/title/active) of a survey (see ``surveys.get_survey_info``)."""
return _surveys.get_survey_info(self.rpc, self._require_key(), sid)
# -- responses / statistics ---------------------------------------
def export_responses(
@ -134,6 +167,18 @@ class LsClient:
"""Export responses of a survey (see ``responses.export_responses``)."""
return _responses.export_responses(self.rpc, self._require_key(), sid, doc_type, **kwargs)
def export_responses_auto(
self,
sid: int | str,
formats: Iterable[str] = ("xlsx", "xls", "csv"),
**kwargs: Any,
) -> tuple[bytes | Path, str]:
"""Export responses with automatic format fallback (see ``responses.export_responses_auto``).
Returns ``(data, used_format)``.
"""
return _responses.export_responses_auto(self.rpc, self._require_key(), sid, formats, **kwargs)
def export_statistics(
self,
sid: int | str,
@ -143,6 +188,16 @@ class LsClient:
"""Export statistics of a survey (see ``responses.export_statistics``)."""
return _responses.export_statistics(self.rpc, self._require_key(), sid, doc_type, **kwargs)
# -- summary / response-tellingen -----------------------------------
def get_summary(self, sid: int | str) -> dict[str, Any]:
"""Raw ``get_summary`` result of a survey (see ``responses.get_summary``)."""
return _responses.get_summary(self.rpc, self._require_key(), sid)
def count_responses(self, sid: int | str) -> ResponseCounts:
"""Response counts (completed/incomplete/total) of a survey (see ``responses.count_responses``)."""
return _responses.count_responses(self.rpc, self._require_key(), sid)
# -- tokens (participants) ------------------------------------------
def add_participants(
@ -177,9 +232,16 @@ __all__ = [
"release_session_key",
"list_surveys",
"get_survey_properties",
"get_survey_by_sid",
"get_survey_info",
"SurveyInfo",
"filter_active",
"export_responses",
"export_responses_auto",
"export_statistics",
"get_summary",
"count_responses",
"ResponseCounts",
"add_participants",
"list_participants",
"delete_participants",

View file

@ -6,22 +6,33 @@ LS7 RemoteControl methods called here (lay these next to the API docs):
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
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).
``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
from typing import Any, Iterable
from .errors import LsApiError
from .rpc import RpcClient
from .utils import normalize_sid, parse_responses_json, raise_for_status
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:
@ -103,6 +114,56 @@ def export_responses(
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,
@ -152,3 +213,57 @@ def 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)

View file

@ -5,11 +5,16 @@
``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
@ -99,3 +104,71 @@ def get_survey_properties(
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")),
)

View file

@ -9,7 +9,10 @@ LS7 RemoteControl methods called here (lay these next to the API docs):
- ``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).
``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
@ -39,6 +42,8 @@ def add_participants(
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:
@ -70,7 +75,9 @@ def list_participants(
``[session_key, sid, start, limit]`` (+ optional ``conditions``, ``language``).
Returns:
List of participant dicts (``tid``, ``email``, ``token``, ``completed``, ...).
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:

View file

@ -3,6 +3,7 @@
- ``to_int`` / ``is_active_flag`` / ``is_filled`` — safe parsing of LS values
- ``parse_responses_json`` / ``decode_export_json`` — decode a JSON responses export
- ``summary_counts`` — completed/total counts from a get_summary result
- ``summary_counts_full`` — (completed, incomplete, total) from a get_summary result
- ``raise_for_status`` — LimeSurvey sometimes puts ``{"status": "..."}`` in the
*result* (instead of ``error``); this detects that and raises an
``LsApiError`` (or ``LsAuthError`` for session/auth texts).
@ -100,6 +101,31 @@ def summary_counts(summary: dict[str, Any]) -> tuple[int | None, int | None]:
return completed, total
def _summary_int(summary: dict[str, Any], keys: tuple[str, ...]) -> int:
"""First present key of ``keys`` as int; missing/invalid → 0."""
for key in keys:
if key in summary:
value = to_int(summary[key])
return value if value is not None else 0
return 0
def summary_counts_full(summary: dict[str, Any]) -> tuple[int, int, int]:
"""Extract (completed, incomplete, total) from a ``get_summary`` result.
Key names differ per LS version; the first present key wins:
``completed_responses`` (fallback ``responses_completed`` / ``completed``) and
``incomplete_responses`` (fallback ``in_progress_responses``). ``total`` is
``full_responses`` when present, else ``completed + incomplete``.
Missing or invalid values count as 0.
"""
completed = _summary_int(summary, ("completed_responses", "responses_completed", "completed"))
incomplete = _summary_int(summary, ("incomplete_responses", "in_progress_responses"))
full = to_int(summary["full_responses"]) if "full_responses" in summary else None
total = full if full is not None else completed + incomplete
return completed, incomplete, total
def is_status_error(result: Any) -> bool:
"""True if ``result`` is an LS error dict: ``{"status": "..."}`` or
``{"status": "...", "error_code": "..."}``.

View file

@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "PyLimeRPC"
version = "0.1.0"
version = "0.2.0"
description = "PyLimeRPC — reusable Python client for the LimeSurvey RemoteControl JSON-RPC API (LS7)"
readme = "README.md"
requires-python = ">=3.10"

View file

@ -52,7 +52,7 @@ def test_sessie_openen_list_surveys_eigenschappen_en_sluiten():
props = ls.get_survey_properties(sid)
assert isinstance(props, dict)
assert props.get("sid") in (sid, str(sid), int(str(sid)) if str(sid).isdigit() else sid)
print(f" properties van sid={sid}: {sorted(props)[:10]} ...")
print(f" properties of sid={sid}: {sorted(props)[:10]} ...")
# context manager released the session cleanly
assert ls.session_key is None

View file

@ -11,7 +11,15 @@ import pytest
from pylimerpc import LsClient, LsConfig
from pylimerpc.errors import LsApiError, LsAuthError
from pylimerpc.responses import export_responses, export_responses_json, export_statistics
from pylimerpc.responses import (
ResponseCounts,
count_responses,
export_responses,
export_responses_auto,
export_responses_json,
export_statistics,
get_summary,
)
from pylimerpc.tokens import add_participants, delete_participants, list_participants
@ -90,6 +98,131 @@ def test_export_statistics_params_en_decode():
assert fake.calls == [("export_statistics", ["KEY", 7, "json", None])]
# -- get_summary / count_responses -------------------------------------------
SUMMARY = {"completed_responses": 14, "incomplete_responses": 41, "full_responses": 55}
def test_get_summary_params_and_dict():
fake = FakeRpc(SUMMARY)
out = get_summary(fake, "KEY", "123") # type: ignore[arg-type]
assert out == SUMMARY
# LS7 get_summary: [session_key, sid] (numeric sid string → int)
assert fake.calls == [("get_summary", ["KEY", 123])]
def test_get_summary_status_error_is_lsapierror():
fake = FakeRpc({"status": "Invalid surveyid"})
with pytest.raises(LsApiError) as excinfo:
get_summary(fake, "KEY", 5) # type: ignore[arg-type]
assert not isinstance(excinfo.value, LsAuthError)
assert "Invalid surveyid" in str(excinfo.value.rpc_message)
def test_get_summary_non_dict_is_lsapierror():
fake = FakeRpc(["not", "a", "dict"])
with pytest.raises(LsApiError):
get_summary(fake, "KEY", 5) # type: ignore[arg-type]
fake2 = FakeRpc("ok")
with pytest.raises(LsApiError):
get_summary(fake2, "KEY", 5) # type: ignore[arg-type]
def test_count_responses_counts():
fake = FakeRpc(SUMMARY)
counts = count_responses(fake, "KEY", 5) # type: ignore[arg-type]
assert counts == ResponseCounts(completed=14, incomplete=41, total=55)
assert (counts.completed, counts.incomplete, counts.total) == (14, 41, 55)
assert fake.calls == [("get_summary", ["KEY", 5])]
def test_count_responses_is_frozen():
fake = FakeRpc(SUMMARY)
counts = count_responses(fake, "KEY", 5) # type: ignore[arg-type]
with pytest.raises(AttributeError):
counts.completed = 99 # type: ignore[misc]
def test_count_responses_fallback_keys_and_total_sum():
# without full_responses → total = completed + incomplete
fake = FakeRpc({"responses_completed": "3", "in_progress_responses": 2})
counts = count_responses(fake, "KEY", 5) # type: ignore[arg-type]
assert (counts.completed, counts.incomplete, counts.total) == (3, 2, 5)
fake2 = FakeRpc({"completed": 1})
counts2 = count_responses(fake2, "KEY", 5) # type: ignore[arg-type]
assert (counts2.completed, counts2.incomplete, counts2.total) == (1, 0, 1)
def test_count_responses_missing_or_invalid_values_become_zero():
fake = FakeRpc({})
counts = count_responses(fake, "KEY", 5) # type: ignore[arg-type]
assert (counts.completed, counts.incomplete, counts.total) == (0, 0, 0)
fake2 = FakeRpc({"completed_responses": "abc", "incomplete_responses": None})
counts2 = count_responses(fake2, "KEY", 5) # type: ignore[arg-type]
assert (counts2.completed, counts2.incomplete, counts2.total) == (0, 0, 0)
# -- export_responses_auto (format fallback) -----------------------------------
def _iwriter_error(doc_type: str) -> LsApiError:
msg = f"Writer for {doc_type} should implement IWriter"
return LsApiError(msg, method="export_responses", rpc_message=msg)
def test_export_responses_auto_fallback_xlsx_to_xls():
raw = b64(b"a,b\n1,2\n")
fake = FakeRpc(_iwriter_error("xlsx"), raw)
data, used = export_responses_auto(fake, "KEY", 5) # type: ignore[arg-type]
assert used == "xls"
assert data == b"a,b\n1,2\n"
# both calls are export_responses; doc_type order was xlsx, then xls
assert [c[0] for c in fake.calls] == ["export_responses", "export_responses"]
assert [c[1][2] for c in fake.calls] == ["xlsx", "xls"]
assert all(c[1][0] == "KEY" and c[1][1] == 5 for c in fake.calls)
def test_export_responses_auto_first_format_works():
raw = b64(b"{}")
fake = FakeRpc(raw)
data, used = export_responses_auto(fake, "KEY", 5, formats=("json", "csv")) # type: ignore[arg-type]
assert used == "json"
assert data == b"{}"
assert len(fake.calls) == 1
def test_export_responses_auto_all_formats_fail_raises_lsapierror():
fake = FakeRpc(_iwriter_error("xlsx"), _iwriter_error("xls"), _iwriter_error("csv"))
with pytest.raises(LsApiError) as excinfo:
export_responses_auto(fake, "KEY", 5) # type: ignore[arg-type]
assert "IWriter" in str(excinfo.value)
assert [c[1][2] for c in fake.calls] == ["xlsx", "xls", "csv"]
def test_export_responses_auto_non_iwriter_error_raises_immediately():
fake = FakeRpc(LsApiError("some other problem", method="export_responses", rpc_message="some other problem"))
with pytest.raises(LsApiError) as excinfo:
export_responses_auto(fake, "KEY", 5) # type: ignore[arg-type]
assert "some other problem" in str(excinfo.value)
assert len(fake.calls) == 1 # no fallback on non-IWriter errors
def test_export_responses_auto_iwriter_in_str_exc_only():
# IWriter only in str(exc), not in rpc_message → still fallback
fake = FakeRpc(LsApiError("Writer for xlsx should implement IWriter"), b64(b"x"))
data, used = export_responses_auto(fake, "KEY", 5, formats=("xlsx", "xls")) # type: ignore[arg-type]
assert (used, data) == ("xls", b"x")
def test_export_responses_auto_with_output_path_returns_path(tmp_path):
fake = FakeRpc(_iwriter_error("xlsx"), b64(b"a,b\n"))
out = tmp_path / "export.bin"
data, used = export_responses_auto(fake, "KEY", 5, output_path=out) # type: ignore[arg-type]
assert used == "xls"
assert isinstance(data, Path)
assert data == out and out.read_bytes() == b"a,b\n"
# -- tokens -----------------------------------------------------------------
@ -122,6 +255,29 @@ def test_list_participants_normaliseert_en_params():
assert fake2.calls == [("list_participants", ["KEY", 5, 10, 50, {"email": "x"}, "nl"])]
def test_add_participants_extra_attributes_pass_through():
# surveys can define custom token attributes (attribute_1, ...); they are
# sent to LS unchanged as extra keys in the participant dict
participants = [{"email": "a@b.c", "firstname": "A", "attribute_1": "blue", "attribute_2": "42"}]
fake = FakeRpc([{"tid": "1", "token": "tok123"}])
out = add_participants(fake, "KEY", 5, participants) # type: ignore[arg-type]
assert out[0]["token"] == "tok123"
assert fake.calls == [("add_participants", ["KEY", 5, participants])]
assert fake.calls[0][1][2][0]["attribute_1"] == "blue"
def test_list_participants_extra_attributes_come_back_unchanged():
rows = [
{"tid": "1", "email": "a@b.c", "token": "t1", "attribute_1": "blue", "attribute_2": "42"},
{"tid": "2", "email": "d@e.f", "token": "t2"}, # no extra attributes here
]
fake = FakeRpc({"participants": rows})
out = list_participants(fake, "KEY", 5) # type: ignore[arg-type]
assert out == rows
assert out[0]["attribute_1"] == "blue"
assert "attribute_1" not in out[1]
def test_delete_participants_params_en_coercitie():
fake = FakeRpc({"1": "OK", "2": "OK"})
out = delete_participants(fake, "KEY", 5, [1, "2"]) # type: ignore[arg-type]
@ -165,3 +321,37 @@ def test_lsclient_responses_en_tokens_delegeren_met_session_key():
# session key is in every call
assert fake.calls[1][1][0] == "KEY"
assert fake.calls[3][1][1] == 5
def test_lsclient_get_summary_and_count_responses():
fake = FakeRpc(
"KEY", # get_session_key
SUMMARY, # get_summary
SUMMARY, # count_responses → get_summary
True, # release_session_key
)
with LsClient(CFG, rpc=fake) as ls: # type: ignore[arg-type]
assert ls.get_summary(5) == SUMMARY
counts = ls.count_responses("5")
assert isinstance(counts, ResponseCounts)
assert (counts.completed, counts.incomplete, counts.total) == (14, 41, 55)
assert fake.calls == [
("get_session_key", ["u", "p"]),
("get_summary", ["KEY", 5]),
("get_summary", ["KEY", 5]),
("release_session_key", ["KEY"]),
]
def test_lsclient_export_responses_auto():
fake = FakeRpc("KEY", _iwriter_error("xlsx"), b64(b"x"), True)
with LsClient(CFG, rpc=fake) as ls: # type: ignore[arg-type]
data, used = ls.export_responses_auto(5)
assert (used, data) == ("xls", b"x")
assert [c[0] for c in fake.calls] == [
"get_session_key",
"export_responses",
"export_responses",
"release_session_key",
]
assert [c[1][2] for c in fake.calls[1:3]] == ["xlsx", "xls"]

View file

@ -64,7 +64,7 @@ class _StubHandler(BaseHTTPRequestHandler):
if method == "with_statistic":
self._send_json({"jsonrpc": "2.0", "id": rid, "result": {"ok": True}, "error": None, "statistic": {"duration_ms": 12, "memory": 2048}})
return
# standaard: echo van method + params
# default: echo of method + params
self._send_json({"jsonrpc": "2.0", "id": rid, "result": {"method": method, "params": payload.get("params")}, "error": None})

View file

@ -9,7 +9,14 @@ import pytest
from pylimerpc import LsClient, LsConfig
from pylimerpc.errors import LsApiError, LsAuthError, LsConnectionError, LsError
from pylimerpc.session import get_session_key, release_session_key
from pylimerpc.surveys import filter_active, get_survey_properties, list_surveys
from pylimerpc.surveys import (
SurveyInfo,
filter_active,
get_survey_by_sid,
get_survey_info,
get_survey_properties,
list_surveys,
)
class FakeRpc:
@ -101,6 +108,61 @@ def test_filter_active():
assert [s["sid"] for s in filter_active(surveys)] == [1, 3]
# -- get_survey_by_sid / get_survey_info --------------------------------------
SURVEYS = [
{"sid": 111, "surveyls_title": "Survey A", "active": "Y"},
{"sid": "222", "surveyls_title": "Survey B", "active": "N"},
]
def test_get_survey_by_sid_hit_and_miss():
fake = FakeRpc(SURVEYS)
hit = get_survey_by_sid(fake, "KEY", 111) # type: ignore[arg-type]
assert hit == SURVEYS[0]
assert fake.calls == [("list_surveys", ["KEY"])]
fake2 = FakeRpc(SURVEYS)
assert get_survey_by_sid(fake2, "KEY", 999) is None # miss → None, no exception # type: ignore[arg-type]
# string sid matches too
fake3 = FakeRpc(SURVEYS)
assert get_survey_by_sid(fake3, "KEY", "222") == SURVEYS[1] # type: ignore[arg-type]
def test_get_survey_by_sid_owner_and_group_params():
surveys = [{"sid": 1, "group_id": 3}, {"sid": 2, "group_id": 4}]
fake = FakeRpc(surveys)
out = get_survey_by_sid(fake, "KEY", 2, owner_id=7, group_id=3) # type: ignore[arg-type]
assert fake.calls == [("list_surveys", ["KEY", 7])]
assert out is None # sid 2 is in group 4, filtered out by group_id=3
def test_get_survey_by_sid_empty_list_is_none():
fake = FakeRpc([])
assert get_survey_by_sid(fake, "KEY", 5) is None # type: ignore[arg-type]
def test_get_survey_by_sid_status_error_is_lsapierror():
fake = FakeRpc({"status": "Some API problem"})
with pytest.raises(LsApiError) as excinfo:
get_survey_by_sid(fake, "KEY", 5) # type: ignore[arg-type]
assert not isinstance(excinfo.value, LsAuthError)
def test_get_survey_info_hit():
fake = FakeRpc(SURVEYS)
info = get_survey_info(fake, "KEY", 111) # type: ignore[arg-type]
assert info == SurveyInfo(sid=111, title="Survey A", active=True)
fake2 = FakeRpc(SURVEYS)
info2 = get_survey_info(fake2, "KEY", "222") # type: ignore[arg-type]
assert info2 == SurveyInfo(sid=222, title="Survey B", active=False)
def test_get_survey_info_miss_is_none():
fake = FakeRpc(SURVEYS)
assert get_survey_info(fake, "KEY", 999) is None # type: ignore[arg-type]
# -- LsClient contextmanager ------------------------------------------------
@ -154,3 +216,21 @@ def test_lsclient_list_surveysGebruikt_config_owner_group():
out = ls.list_surveys()
assert fake.calls[1] == ("list_surveys", ["KEY", 9])
assert [s["sid"] for s in out] == [1] # group_id=3 filtered
def test_lsclient_get_survey_by_sid_and_get_survey_info():
fake = FakeRpc("KEY", SURVEYS, SURVEYS, SURVEYS, SURVEYS, True)
with LsClient(CFG, rpc=fake) as ls: # type: ignore[arg-type]
assert ls.get_survey_by_sid(111) == SURVEYS[0]
assert ls.get_survey_by_sid(999) is None
info = ls.get_survey_info("222")
assert info == SurveyInfo(sid=222, title="Survey B", active=False)
assert ls.get_survey_info(999) is None
assert fake.calls == [
("get_session_key", ["u", "p"]),
("list_surveys", ["KEY"]),
("list_surveys", ["KEY"]),
("list_surveys", ["KEY"]),
("list_surveys", ["KEY"]),
("release_session_key", ["KEY"]),
]

View file

@ -16,6 +16,7 @@ from pylimerpc.utils import (
parse_responses_json,
raise_for_status,
summary_counts,
summary_counts_full,
to_int,
)
@ -71,6 +72,24 @@ def test_summary_counts_key_varianten():
assert summary_counts({}) == (None, None)
def test_summary_counts_full_basis():
summary = {"completed_responses": 14, "incomplete_responses": 41, "full_responses": 55}
assert summary_counts_full(summary) == (14, 41, 55)
def test_summary_counts_full_fallback_keys_and_total_sum():
# without full_responses → total = completed + incomplete
assert summary_counts_full({"responses_completed": "3", "in_progress_responses": 2}) == (3, 2, 5)
assert summary_counts_full({"completed": 1}) == (1, 0, 1)
# full_responses wins when present
assert summary_counts_full({"completed_responses": 2, "incomplete_responses": 3, "full_responses": 99}) == (2, 3, 99)
def test_summary_counts_full_missing_or_invalid_is_zero():
assert summary_counts_full({}) == (0, 0, 0)
assert summary_counts_full({"completed_responses": "abc", "incomplete_responses": None}) == (0, 0, 0)
def test_raise_for_status_auth():
with pytest.raises(LsAuthError):
raise_for_status({"status": "Invalid session key"}, "list_surveys")