From 6822eab467bb47d58c07dea538de134d8c0858e1 Mon Sep 17 00:00:00 2001 From: Tammo ter Hark Date: Fri, 20 Nov 2026 11:56:03 +0100 Subject: [PATCH] =?UTF-8?q?PyLimeRPC=200.2.0=20=E2=80=94=20prompts.md=20Pr?= =?UTF-8?q?ompt=201-4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .gitignore | 3 +- README.md | 48 +++++++-- pylimerpc/__init__.py | 72 ++++++++++++- pylimerpc/responses.py | 125 ++++++++++++++++++++- pylimerpc/surveys.py | 73 +++++++++++++ pylimerpc/tokens.py | 11 +- pylimerpc/utils.py | 26 +++++ pyproject.toml | 2 +- tests/test_integration.py | 2 +- tests/test_responses_tokens.py | 192 ++++++++++++++++++++++++++++++++- tests/test_rpc.py | 2 +- tests/test_session_surveys.py | 82 +++++++++++++- tests/test_utils.py | 19 ++++ 13 files changed, 633 insertions(+), 24 deletions(-) diff --git a/.gitignore b/.gitignore index 910537e..249a764 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/README.md b/README.md index 8de3cb9..a4849c2 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/pylimerpc/__init__.py b/pylimerpc/__init__.py index 85d2155..f90c7bb 100644 --- a/pylimerpc/__init__.py +++ b/pylimerpc/__init__.py @@ -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", diff --git a/pylimerpc/responses.py b/pylimerpc/responses.py index 9bf2d26..fd29c7f 100644 --- a/pylimerpc/responses.py +++ b/pylimerpc/responses.py @@ -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__responses.`` 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__responses.`` 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) diff --git a/pylimerpc/surveys.py b/pylimerpc/surveys.py index 1e6c58a..f3c3b8a 100644 --- a/pylimerpc/surveys.py +++ b/pylimerpc/surveys.py @@ -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")), + ) diff --git a/pylimerpc/tokens.py b/pylimerpc/tokens.py index bb74692..276091e 100644 --- a/pylimerpc/tokens.py +++ b/pylimerpc/tokens.py @@ -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: diff --git a/pylimerpc/utils.py b/pylimerpc/utils.py index d3d03b7..6b12657 100644 --- a/pylimerpc/utils.py +++ b/pylimerpc/utils.py @@ -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": "..."}``. diff --git a/pyproject.toml b/pyproject.toml index cf900c6..8f64e59 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/tests/test_integration.py b/tests/test_integration.py index 4ca7bef..e7d2cbf 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -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 diff --git a/tests/test_responses_tokens.py b/tests/test_responses_tokens.py index d48c6ca..44decb2 100644 --- a/tests/test_responses_tokens.py +++ b/tests/test_responses_tokens.py @@ -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"] diff --git a/tests/test_rpc.py b/tests/test_rpc.py index 91cdd85..155b8d2 100644 --- a/tests/test_rpc.py +++ b/tests/test_rpc.py @@ -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}) diff --git a/tests/test_session_surveys.py b/tests/test_session_surveys.py index cd2c26c..9beb396 100644 --- a/tests/test_session_surveys.py +++ b/tests/test_session_surveys.py @@ -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"]), + ] diff --git a/tests/test_utils.py b/tests/test_utils.py index 226776b..9574c03 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -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")