From d7d9dc61bfcb0ef9fcaf81eb4340b3068212f2e4 Mon Sep 17 00:00:00 2001 From: Tammo ter Hark Date: Thu, 19 Nov 2026 12:26:35 +0100 Subject: [PATCH] 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 --- .env.example | 5 + .gitignore | 17 ++- README.md | 163 +++++++++++++++++++-- examples/README.md | 21 +++ examples/__init__.py | 4 + examples/example_asgi.py | 103 +++++++++++++ examples/example_cli.py | 106 ++++++++++++++ examples/example_cron_export.py | 60 ++++++++ pylimerpc/__init__.py | 187 ++++++++++++++++++++++++ pylimerpc/config.py | 218 ++++++++++++++++++++++++++++ pylimerpc/errors.py | 85 +++++++++++ pylimerpc/responses.py | 154 ++++++++++++++++++++ pylimerpc/rpc.py | 250 ++++++++++++++++++++++++++++++++ pylimerpc/session.py | 48 ++++++ pylimerpc/surveys.py | 101 +++++++++++++ pylimerpc/tokens.py | 113 +++++++++++++++ pylimerpc/utils.py | 132 +++++++++++++++++ pyproject.toml | 35 +++++ tests/__init__.py | 5 + tests/test_config.py | 175 ++++++++++++++++++++++ tests/test_errors.py | 38 +++++ tests/test_examples.py | 129 ++++++++++++++++ tests/test_integration.py | 78 ++++++++++ tests/test_responses_tokens.py | 167 +++++++++++++++++++++ tests/test_rpc.py | 214 +++++++++++++++++++++++++++ tests/test_session_surveys.py | 156 ++++++++++++++++++++ tests/test_utils.py | 99 +++++++++++++ 27 files changed, 2851 insertions(+), 12 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/__init__.py create mode 100644 examples/example_asgi.py create mode 100644 examples/example_cli.py create mode 100644 examples/example_cron_export.py create mode 100644 pylimerpc/__init__.py create mode 100644 pylimerpc/config.py create mode 100644 pylimerpc/errors.py create mode 100644 pylimerpc/responses.py create mode 100644 pylimerpc/rpc.py create mode 100644 pylimerpc/session.py create mode 100644 pylimerpc/surveys.py create mode 100644 pylimerpc/tokens.py create mode 100644 pylimerpc/utils.py create mode 100644 pyproject.toml create mode 100644 tests/__init__.py create mode 100644 tests/test_config.py create mode 100644 tests/test_errors.py create mode 100644 tests/test_examples.py create mode 100644 tests/test_integration.py create mode 100644 tests/test_responses_tokens.py create mode 100644 tests/test_rpc.py create mode 100644 tests/test_session_surveys.py create mode 100644 tests/test_utils.py diff --git a/.env.example b/.env.example index 558e07b..337d8ca 100644 --- a/.env.example +++ b/.env.example @@ -10,3 +10,8 @@ LIMESURVEY_GROUP_ID= # API settings LIMESURVEY_TIMEOUT_SECONDS=30 + +# TLS: the server certificate is verified by default. Set to false ONLY for a +# local test instance with a wrong/self-signed certificate (hostname mismatch). +# NEVER disable verification in production. +# LIMESURVEY_VERIFY_SSL=true diff --git a/.gitignore b/.gitignore index 5e43f79..910537e 100644 --- a/.gitignore +++ b/.gitignore @@ -14,5 +14,20 @@ venv/ # IDE .vscode/ -# Generated exports +# Generated exports / output files — survey data must NEVER be synced to Forgejo. +# Covers the library's default names in any directory plus ad-hoc CSV/XLS exports. output/ +survey_*_responses.* +survey_*_statistics.* +*.csv +*.xls +*.xlsx +*.spss + +# Local working document (never synced to Forgejo) +werkdocument.md + +# Packaging (pip install -e .) +build/ +dist/ +*.egg-info/ diff --git a/README.md b/README.md index b6402fe..8de3cb9 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,154 @@ -This is a minimal script to test the availability of a LimeSurvey backend. -Tested up to version 7.0.14. +# PyLimeRPC -# The script does this: -* ask a session key -* get list of active surveys -* lets you choose a survey that has responses -* gets the responses -* write a CVS with the responses to the output directory +**PyLimeRPC** (import package: `pylimerpc`) is a reusable Python library for +interacting with **LimeSurvey** via the RemoteControl JSON-RPC API (LS7, +endpoint `index.php?r=admin/remotecontrol`). -# Instructions -* Copy .env.example to .env and edit .env to enter the details to your LimeSurvey installation. -* Run test.py +- Python standard library only — no runtime dependencies. +- Usable from cron/URL-triggered data tasks, CLI admin tools and web + dashboards (ASGI). +- Runs on Linux. + +## Prerequisites + +Before using this library or the example scripts, make sure you have: + +1. **Python >= 3.10** on a Linux machine. +2. A **LimeSurvey 7** installation with the **RemoteControl (JSON-RPC) API enabled** — + the endpoint `https:///index.php?r=admin/remotecontrol` + must be reachable over HTTPS. +3. A **RemoteControl user account** (username + password) with permissions for the + surveys you want to access. +4. A filled-in **`.env`** file (copy `.env.example`): `LIMESURVEY_BASE_URL`, + `LIMESURVEY_USERNAME`, `LIMESURVEY_PASSWORD`; optionally `LIMESURVEY_TIMEOUT_SECONDS`, + `LIMESURVEY_OWNER_ID`, `LIMESURVEY_GROUP_ID`, `LIMESURVEY_VERIFY_SSL`. +5. Network access from your machine to the LimeSurvey host, with a **valid TLS + certificate** (set `LIMESURVEY_VERIFY_SSL=false` only for a local test instance + with a wrong/self-signed certificate — never in production). +6. To run the tests: `pip install -e ".[dev]"` (adds pytest as a dev extra). + +## Install (editable) + +```bash +pip install -e . +``` + +## Structure + +``` +pylimerpc/ + __init__.py # package docstring, LsClient, __version__ + 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 + tokens.py # token management: add/list/delete participants + errors.py # LsConnectionError, LsApiError, LsAuthError + utils.py # shared helpers +tests/ +examples/ +pyproject.toml +``` + +## Configuration + +Credentials never live in code or git — only in `.env` (see `.env.example`): + +``` +LIMESURVEY_BASE_URL=https://example.com/index.php?r=admin/remotecontrol +LIMESURVEY_USERNAME=example_user +LIMESURVEY_PASSWORD=example_password +LIMESURVEY_TIMEOUT_SECONDS=30 +``` + +Note: generated exports (`output/`, `survey_*_responses.*`, `survey_*_statistics.*`, +`*.csv`/`*.xls`/`*.xlsx`/`*.spss`) are gitignored — survey data is never synced to git. + +## Usage + +```python +from pylimerpc import LsClient, LsConfig + +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"]) +``` + +Low level (without session management): `RpcClient.from_config(cfg).call(method, params)`. + +```python +with LsClient(cfg) as ls: + data = ls.export_responses(sid, doc_type="csv", output_path="output/") # → Path + stats = ls.export_statistics(sid) # → bytes + ls.add_participants(sid, [{"email": "a@b.c", "firstname": "A"}]) + participants = ls.list_participants(sid) + ls.delete_participants(sid, [participants[0]["tid"]]) +``` + +LS7 RemoteControl methods: `export_responses`, `export_statistics`, +`add_participants`, `list_participants`, `delete_participants` (base64 exports +are decoded automatically). + +Errors: `LsConnectionError` (server unreachable/HTTP error), `LsApiError` +(JSON-RPC error, with `rpc_code`/`rpc_message`), `LsAuthError` (login refused). + +## Diagnose with curl + +Seeing an error? Send the same request by hand: + +```bash +curl -i -X POST 'https://host/index.php?r=admin/remotecontrol' \ + -H 'Content-Type: application/json' \ + -d '{"jsonrpc":"2.0","method":"get_session_key","params":["USER","PASS"],"id":1}' +``` + +`-i` shows the HTTP status + headers + body. Note: the alias `/remotecontrol` +returns HTTP 400 — always use `index.php?r=admin/remotecontrol`. + +### SSL error: `curl: (60) certificate subject name ... does not match` + +The server then presents a certificate for a different hostname (e.g. a local +test box). Diagnose: + +```bash +getent hosts ls.example.com # which IP? +echo | openssl s_client -connect ls.example.com:443 -servername ls.example.com 2>/dev/null \ + | openssl x509 -noout -subject -ext subjectAltName # which cert? +``` + +Solutions: use the hostname that IS in the certificate (works with +verification), or for a test instance use `curl -k`. In the library: set +`LIMESURVEY_VERIFY_SSL=false` in `.env` (or `LsConfig(..., verify_ssl=False)`) — +verification stays ON by default. Without this option you get an +`LsConnectionError` with the `ssl.SSLError` as `cause`. + +## Examples + +See `examples/` — three directly runnable scripts (config from `.env`): + +```bash +python examples/example_cron_export.py --sid 12345 --out output/cron # cron task +python examples/example_cli.py surveys # CLI +python examples/example_cli.py export --sid 12345 --out export.csv +python examples/example_cli.py tokens-list --sid 12345 +# ASGI dashboard: attach examples.example_asgi:app to your own router +# (dev: uvicorn examples.example_asgi:app --port 8000) +``` + +## Tests + +```bash +pip install -e ".[dev]" # installs pytest as a dev extra +python -m pytest # unit tests (integration tests are skipped by default) +python -m pytest -m integration # integration tests against a real instance +``` + +Integration tests read `LIMESURVEY_BASE_URL` / `LIMESURVEY_USERNAME` / +`LIMESURVEY_PASSWORD` from the environment and skip when they are not set. + +## test.py + +`test.py` is the original monolithic script this library grew out of; a next +step is to rewrite it on top of the library. diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..38a835f --- /dev/null +++ b/examples/README.md @@ -0,0 +1,21 @@ +# Examples + +Three minimal scripts that use `pylimerpc` the way the three +application types will. Each reads its config from `.env` and runs directly +from the repo (no `pip install -e .` needed): + +| script | application model | run | +|---|---|---| +| `example_cron_export.py` | cron/URL-triggered data task | `python examples/example_cron_export.py --sid 12345 --out output/cron` | +| `example_cli.py` | distributable CLI admin tool | `python examples/example_cli.py surveys` / `export --sid 12345 --out export.csv` / `tokens-list --sid 12345` | +| `example_asgi.py` | web dashboard via ASGI router | `app` is a plain-ASGI callable; dev: `uvicorn examples.example_asgi:app --port 8000` | + +See the **Prerequisites** section in the main `README.md` for what you need before +running these scripts (Python >= 3.10, a LimeSurvey 7 instance with the +RemoteControl API enabled, an RPC user account, and a filled-in `.env`). + +Config: `.env` in the repo root (`LIMESURVEY_BASE_URL`, `LIMESURVEY_USERNAME`, +`LIMESURVEY_PASSWORD`, optional `LIMESURVEY_TIMEOUT_SECONDS`, `LIMESURVEY_VERIFY_SSL`). + +Generated exports (`output/`, `survey_*_responses.*`, `survey_*_statistics.*`, +`*.csv`/`*.xls`/`*.xlsx`/`*.spss`) are gitignored — survey data is never synced. diff --git a/examples/__init__.py b/examples/__init__.py new file mode 100644 index 0000000..333cb9f --- /dev/null +++ b/examples/__init__.py @@ -0,0 +1,4 @@ +"""Example scripts that use the pylimerpc library. + +See examples/README.md. Each script runs directly from the repo. +""" diff --git a/examples/example_asgi.py b/examples/example_asgi.py new file mode 100644 index 0000000..4436461 --- /dev/null +++ b/examples/example_asgi.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +"""Example 3 — minimal plain-ASGI dashboard: active surveys as HTML. + +No framework needed: ``app`` is a standard ASGI callable ``(scope, receive, send)``. +Attach it to your own router/ASGI server, e.g. (uvicorn is only a dev server): + + uvicorn examples.example_asgi:app --port 8000 + or directly: python examples/example_asgi.py (requires uvicorn) + +Routes: + GET / → HTML table with active surveys + GET /health → "ok" (plain text) + +Config is read from the .env in the repo root (independent of the working dir). +""" + +from __future__ import annotations + +import html +import sys +from pathlib import Path +from typing import Any, Awaitable, Callable + +# Make the library importable when running this script directly from the repo. +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from pylimerpc import LsClient, LsConfig +from pylimerpc.errors import LsError +from pylimerpc.surveys import filter_active + +REPO_ROOT = Path(__file__).resolve().parent.parent + +Send = Callable[[dict[str, Any]], Awaitable[None]] + + +def load_config() -> LsConfig: + """Config from the .env in the repo root.""" + return LsConfig.from_dotenv(REPO_ROOT / ".env") + + +def _html_page(surveys: list[dict[str, Any]]) -> bytes: + rows = "".join( + "" + f"{html.escape(str(s.get('sid', '')))}" + f"{html.escape(str(s.get('surveyls_title', '')))}" + "" + for s in surveys + ) + page = ( + "" + "LimeSurvey — active surveys" + "

Active surveys

" + "" + f"{rows}
sidtitle
" + ) + return page.encode("utf-8") + + +async def _respond(send: Send, status: int, content_type: bytes, body: bytes) -> None: + await send( + { + "type": "http.response.start", + "status": status, + "headers": [ + (b"content-type", content_type), + (b"content-length", str(len(body)).encode()), + ], + } + ) + await send({"type": "http.response.body", "body": body}) + + +async def app(scope: dict[str, Any], receive: Any, send: Send) -> None: + """Plain-ASGI app; only ``http`` scopes are handled.""" + if scope["type"] != "http": + return + path = scope.get("path", "/") + if path == "/health": + await _respond(send, 200, b"text/plain; charset=utf-8", b"ok") + return + if path != "/": + await _respond(send, 404, b"text/plain; charset=utf-8", b"not found") + return + try: + cfg = load_config() + with LsClient(cfg) as ls: + surveys = filter_active(ls.list_surveys()) + body = _html_page(surveys) + except LsError as exc: + await _respond(send, 502, b"text/plain; charset=utf-8", f"LS error: {exc}".encode("utf-8")) + return + await _respond(send, 200, b"text/html; charset=utf-8", body) + + +if __name__ == "__main__": + try: + import uvicorn + except ImportError: + print("uvicorn is not installed. Attach `app` to your own ASGI server/router,") + print("or install uvicorn as a dev server: pip install uvicorn") + print(" uvicorn examples.example_asgi:app --port 8000") + raise SystemExit(1) + uvicorn.run(app, host="127.0.0.1", port=8000) diff --git a/examples/example_cli.py b/examples/example_cli.py new file mode 100644 index 0000000..588e4cc --- /dev/null +++ b/examples/example_cli.py @@ -0,0 +1,106 @@ +#!/usr/bin/env python3 +"""Example 2 — distributable CLI admin tool (argparse). + + python examples/example_cli.py surveys + python examples/example_cli.py export --sid 12345 --out export.csv + python examples/example_cli.py export --sid 12345 --doc-type json --out output/ + python examples/example_cli.py tokens-list --sid 12345 [--limit 50] ("tokens-lijst" still works as an alias) + +Config from .env (--env-file). Exit code 0 on success, 1 on error. +""" + +from __future__ import annotations + +import argparse +import sys +from pathlib import Path + +# Make the library importable when running this script directly from the repo. +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from pylimerpc import LsClient, LsConfig +from pylimerpc.errors import LsApiError, LsError +from pylimerpc.surveys import filter_active + + +def cmd_surveys(ls: LsClient) -> None: + surveys = filter_active(ls.list_surveys()) + if not surveys: + print("No active surveys.") + return + for s in surveys: + print(f"sid={s.get('sid')}\t{s.get('surveyls_title')}") + + +def cmd_export(ls: LsClient, args: argparse.Namespace) -> None: + path = ls.export_responses(args.sid, doc_type=args.doc_type, output_path=args.out) + print(f"Export saved: {path} ({Path(path).stat().st_size} bytes)") + + +def cmd_tokens(ls: LsClient, args: argparse.Namespace) -> None: + try: + participants = ls.list_participants(args.sid, limit=args.limit) + except LsApiError as exc: + if exc.rpc_message and "participant" in exc.rpc_message.lower(): + print(f"No participant table for survey {args.sid} (no tokens created yet).") + return + raise + if not participants: + print("No participants.") + return + print(f"{'tid':>6} {'email':<30} {'token':<12} completed") + for p in participants: + print( + f"{str(p.get('tid')):>6} {str(p.get('email')):<30} " + f"{str(p.get('token')):<12} {p.get('completed')}" + ) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="example_cli", + description="LimeSurvey admin CLI (example of a distributable tool)", + ) + parser.add_argument("--env-file", default=".env", help="path to .env (default: .env in current dir)") + sub = parser.add_subparsers(dest="command", required=True) + + sub.add_parser("surveys", help="show active surveys") + + p_export = sub.add_parser("export", help="export responses of a survey") + p_export.add_argument("--sid", required=True, help="survey ID") + p_export.add_argument("--doc-type", default="csv", choices=["csv", "json"]) + p_export.add_argument("--out", default="output", help="output file or directory") + + p_tokens = sub.add_parser( + "tokens-list", aliases=["tokens-lijst"], help="show participants/tokens of a survey" + ) + p_tokens.add_argument("--sid", required=True, help="survey ID") + p_tokens.add_argument("--limit", type=int, default=100) + + return parser + + +def main() -> int: + args = build_parser().parse_args() + try: + cfg = LsConfig.from_dotenv(args.env_file) + except (ValueError, FileNotFoundError) as exc: + print(f"Config error: {exc}", file=sys.stderr) + return 1 + + try: + with LsClient(cfg) as ls: + if args.command == "surveys": + cmd_surveys(ls) + elif args.command == "export": + cmd_export(ls, args) + elif args.command in ("tokens-list", "tokens-lijst"): + cmd_tokens(ls, args) + except LsError as exc: + print(f"ERROR: {exc}", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/examples/example_cron_export.py b/examples/example_cron_export.py new file mode 100644 index 0000000..39a9835 --- /dev/null +++ b/examples/example_cron_export.py @@ -0,0 +1,60 @@ +#!/usr/bin/env python3 +"""Example 1 — cron/URL-triggered data task: export survey responses to an output dir. + +Config comes from .env (LIMESURVEY_BASE_URL/USERNAME/PASSWORD), never in code. +No interactive input; exit code 0 on success, 1 on error (suitable for cron monitoring). + +Run: + .venv/bin/python examples/example_cron_export.py --sid 12345 --out output/cron + +Example crontab (daily at 06:00): + 0 6 * * * cd /path/to/this/repo && .venv/bin/python examples/example_cron_export.py --sid 12345 --out output/cron >> /var/log/ls-export.log 2>&1 +""" + +from __future__ import annotations + +import argparse +import logging +import sys +from pathlib import Path + +# Make the library importable when running this script directly from the repo +# (not needed after `pip install -e .`). +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from pylimerpc import LsClient, LsConfig +from pylimerpc.errors import LsError + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Export survey responses to an output directory (cron task)." + ) + parser.add_argument("--env-file", default=".env", help="path to .env (default: .env in current dir)") + parser.add_argument("--sid", required=True, help="survey ID") + parser.add_argument("--doc-type", default="csv", choices=["csv", "json"], help="export format") + parser.add_argument("--out", default="output", help="output directory (created if missing)") + args = parser.parse_args() + + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s") + + try: + cfg = LsConfig.from_dotenv(args.env_file) + except (ValueError, FileNotFoundError) as exc: + print(f"Config error: {exc}", file=sys.stderr) + return 1 + + try: + with LsClient(cfg) as ls: + path = ls.export_responses(args.sid, doc_type=args.doc_type, output_path=args.out) + except LsError as exc: + print(f"Export failed: {exc}", file=sys.stderr) + return 1 + + path = Path(path) + print(f"OK: export saved to {path} ({path.stat().st_size} bytes)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/pylimerpc/__init__.py b/pylimerpc/__init__.py new file mode 100644 index 0000000..85d2155 --- /dev/null +++ b/pylimerpc/__init__.py @@ -0,0 +1,187 @@ +"""PyLimeRPC — reusable client library for LimeSurvey (import package: ``pylimerpc``). + +Talks to the LimeSurvey RemoteControl JSON-RPC API (LS7, endpoint +``index.php?r=admin/remotecontrol``). Python standard library only. + +Usage (session is opened/closed automatically): + + from pylimerpc import LsClient, LsConfig + + cfg = LsConfig.from_dotenv(".env") + with LsClient(cfg) as ls: + surveys = ls.list_surveys() + props = ls.get_survey_properties(surveys[0]["sid"]) + +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 + tokens — token management (participants): add / list / delete + errors — custom exceptions (LsError, LsConnectionError, LsApiError, LsAuthError) + utils — small shared helpers + +Credentials never live in code or git, only in a .env file or as parameters. +""" + +from __future__ import annotations + +import logging +from pathlib import Path +from types import TracebackType +from typing import Any, Iterable + +from . import responses as _responses +from . import session as _session +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 .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 .tokens import add_participants, delete_participants, list_participants + +logger = logging.getLogger(__name__) + +__version__ = "0.1.0" + + +class LsClient: + """Main client with session management. + + Opens a session on ``__enter__`` (``get_session_key``) and releases the + key on ``__exit__`` (also on exception): + + cfg = LsConfig.from_dotenv(".env") + with LsClient(cfg) as ls: + surveys = ls.list_surveys() + + Args: + config: an ``LsConfig`` (base_url, username, password, timeout, ...). + rpc: optional own ``RpcClient`` (handy for tests); by default one is + built from ``config``. + """ + + def __init__(self, config: LsConfig, *, rpc: RpcClient | None = None) -> None: + self.config = config + self.rpc = rpc if rpc is not None else RpcClient.from_config(config) + self.session_key: str | None = None + + def __enter__(self) -> LsClient: + self.session_key = _session.get_session_key( + self.rpc, self.config.username, self.config.password + ) + logger.debug("Session opened (key ends with ...%s)", self.session_key[-4:]) + return self + + def __exit__( + self, + exc_type: type[BaseException] | None, + exc: BaseException | None, + tb: TracebackType | None, + ) -> None: + self.close() + + def close(self) -> None: + """Release the session key (safe to call repeatedly; errors are only logged).""" + if self.session_key: + try: + _session.release_session_key(self.rpc, self.session_key) + except LsError as exc: + logger.debug("release_session_key failed (ignored): %s", exc) + finally: + self.session_key = None + + def _require_key(self) -> str: + if not self.session_key: + raise LsError("No active session — use 'with LsClient(cfg) as ls:'") + return self.session_key + + # -- surveys ------------------------------------------------------ + + def list_surveys( + self, + owner_id: int | str | None = None, + group_id: int | str | None = None, + ) -> list[dict[str, Any]]: + """List of surveys (see ``surveys.list_surveys``).""" + return _surveys.list_surveys( + self.rpc, + self._require_key(), + 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_properties( + self, + sid: int | str, + properties: Iterable[str] | None = None, + ) -> dict[str, Any]: + """Properties of a single survey (see ``surveys.get_survey_properties``).""" + return _surveys.get_survey_properties(self.rpc, self._require_key(), sid, properties=properties) + + # -- responses / statistics --------------------------------------- + + def export_responses( + self, + sid: int | str, + doc_type: str = "json", + **kwargs: Any, + ) -> bytes | Path: + """Export responses of a survey (see ``responses.export_responses``).""" + return _responses.export_responses(self.rpc, self._require_key(), sid, doc_type, **kwargs) + + def export_statistics( + self, + sid: int | str, + doc_type: str = "json", + **kwargs: Any, + ) -> bytes | Path: + """Export statistics of a survey (see ``responses.export_statistics``).""" + return _responses.export_statistics(self.rpc, self._require_key(), sid, doc_type, **kwargs) + + # -- tokens (participants) ------------------------------------------ + + def add_participants( + self, + sid: int | str, + participants: list[dict[str, Any]], + **kwargs: Any, + ) -> Any: + """Add participants (see ``tokens.add_participants``).""" + return _tokens.add_participants(self.rpc, self._require_key(), sid, participants, **kwargs) + + def list_participants(self, sid: int | str, **kwargs: Any) -> list[dict[str, Any]]: + """List participants (see ``tokens.list_participants``).""" + return _tokens.list_participants(self.rpc, self._require_key(), sid, **kwargs) + + def delete_participants(self, sid: int | str, token_ids: list[int | str]) -> Any: + """Delete participants (see ``tokens.delete_participants``).""" + return _tokens.delete_participants(self.rpc, self._require_key(), sid, token_ids) + + +__all__ = [ + "LsClient", + "LsConfig", + "RpcClient", + "rpc_call", + "endpoint_url", + "LsError", + "LsConnectionError", + "LsApiError", + "LsAuthError", + "get_session_key", + "release_session_key", + "list_surveys", + "get_survey_properties", + "filter_active", + "export_responses", + "export_statistics", + "add_participants", + "list_participants", + "delete_participants", + "__version__", +] diff --git a/pylimerpc/config.py b/pylimerpc/config.py new file mode 100644 index 0000000..6a945f1 --- /dev/null +++ b/pylimerpc/config.py @@ -0,0 +1,218 @@ +"""Configuration management: settings from .env / environment variables. + +Standard library only (no python-dotenv). Known keys: + +- ``LIMESURVEY_BASE_URL`` — e.g. https://example.com/index.php?r=admin/remotecontrol +- ``LIMESURVEY_USERNAME`` — RemoteControl user +- ``LIMESURVEY_PASSWORD`` — password (or API token) +- ``LIMESURVEY_TIMEOUT_SECONDS`` — optional, default 30 +- ``LIMESURVEY_OWNER_ID`` — optional, filter by owner +- ``LIMESURVEY_GROUP_ID`` — optional, filter by group +- ``LIMESURVEY_VERIFY_SSL`` — optional, default true; ``false`` ONLY for + test instances with a wrong/self-signed certificate (never production) + +Precedence (highest first): explicit parameters > environment variables > .env file. + +Usage: + >>> cfg = LsConfig.from_dotenv(".env") # from .env + os.environ + >>> cfg = LsConfig.from_env() # environment only + >>> cfg = LsConfig.from_dotenv(".env", timeout=60) # parameter wins + >>> cfg = LsConfig(base_url=..., username=..., password=...) # direct +""" + +from __future__ import annotations + +import os +from collections.abc import Mapping +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +# LsConfig field name -> environment variable +_ENV_KEYS: dict[str, str] = { + "base_url": "LIMESURVEY_BASE_URL", + "username": "LIMESURVEY_USERNAME", + "password": "LIMESURVEY_PASSWORD", + "timeout": "LIMESURVEY_TIMEOUT_SECONDS", + "owner_id": "LIMESURVEY_OWNER_ID", + "group_id": "LIMESURVEY_GROUP_ID", + "verify_ssl": "LIMESURVEY_VERIFY_SSL", +} + +_REQUIRED_FIELDS: tuple[str, ...] = ("base_url", "username", "password") + +DEFAULT_TIMEOUT = 30 + + +def _strip_quotes(value: str) -> str: + """Strip a pair of surrounding single or double quotes.""" + if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'): + return value[1:-1] + return value + + +def parse_dotenv(path: str | Path) -> dict[str, str]: + """Parse a .env file into a ``dict``. + + Rules: ``KEY=value`` (split on the first ``=``). Empty lines and lines + starting with ``#`` are ignored. Surrounding quotes around the value are + removed. + """ + values: dict[str, str] = {} + for raw_line in Path(path).read_text(encoding="utf-8").splitlines(): + line = raw_line.strip() + if not line or line.startswith("#") or "=" not in line: + continue + key, value = line.split("=", 1) + key = key.strip() + if not key: + continue + values[key] = _strip_quotes(value.strip()) + return values + + +def load_dotenv(path: str | Path, *, override: bool = False) -> dict[str, str]: + """Load a .env file into ``os.environ``. + + By default an already-set environment variable wins (``setdefault``); + with ``override=True`` the file wins. Returns the loaded pairs. + """ + loaded = parse_dotenv(path) + for key, value in loaded.items(): + if override: + os.environ[key] = value + else: + os.environ.setdefault(key, value) + return loaded + + +def _to_int(value: Any) -> int | None: + """Safe conversion to int; ``None`` for empty/invalid values.""" + if value is None: + return None + text = str(value).strip() + if not text: + return None + try: + return int(text) + except ValueError: + return None + + +def _collect(environ: Mapping[str, str], file_values: Mapping[str, str]) -> dict[str, Any]: + """Map environment variables (these win) and .env values to field names.""" + merged: dict[str, Any] = {} + for field, env_key in _ENV_KEYS.items(): + if env_key in environ: + merged[field] = environ[env_key] + elif env_key in file_values: + merged[field] = file_values[env_key] + return merged + + +@dataclass(frozen=True) +class LsConfig: + """Configuration for the LimeSurvey RemoteControl API. + + Required: ``base_url``, ``username``, ``password``. + Optional: ``timeout`` (seconds, default 30), ``owner_id``, ``group_id``, + ``verify_ssl`` (default True). + """ + + base_url: str + username: str + password: str + timeout: int = DEFAULT_TIMEOUT + owner_id: int | None = None + group_id: int | None = None + verify_ssl: bool = True + + @classmethod + def from_env(cls, environ: Mapping[str, str] | None = None, **overrides: Any) -> LsConfig: + """Build an ``LsConfig`` from environment variables (default ``os.environ``).""" + if environ is None: + environ = os.environ + return cls._build(_collect(environ, {}), overrides) + + @classmethod + def from_dotenv( + cls, + path: str | Path = ".env", + environ: Mapping[str, str] | None = None, + **overrides: Any, + ) -> LsConfig: + """Build an ``LsConfig`` from a .env file. + + Precedence: explicit parameters > environment variables > .env file. + Raises ``FileNotFoundError`` if ``path`` does not exist, and + ``ValueError`` if ``BASE_URL`` or credentials are missing. + """ + env_path = Path(path) + if not env_path.is_file(): + raise FileNotFoundError(f".env file not found: {env_path}") + if environ is None: + environ = os.environ + return cls._build(_collect(environ, parse_dotenv(env_path)), overrides) + + @classmethod + def _build(cls, values: Mapping[str, Any], overrides: Mapping[str, Any]) -> LsConfig: + unknown = sorted(set(overrides) - set(_ENV_KEYS)) + if unknown: + raise TypeError(f"Unknown LsConfig parameter(s): {', '.join(unknown)}") + + merged: dict[str, Any] = dict(values) + for field, value in overrides.items(): + if value is not None: + merged[field] = value + + missing = [_ENV_KEYS[field] for field in _REQUIRED_FIELDS if not str(merged.get(field, "")).strip()] + if missing: + raise ValueError( + "Missing required LimeSurvey configuration: " + + ", ".join(missing) + + " — set these in the .env file, as environment variables, " + "or pass them as parameters." + ) + + base_url = str(merged["base_url"]).strip() + if not base_url.startswith(("http://", "https://")): + raise ValueError( + f"LIMESURVEY_BASE_URL must start with http:// or https://, got: {base_url!r}" + ) + + timeout_raw = str(merged.get("timeout", "")).strip() + if timeout_raw: + timeout = _to_int(timeout_raw) + if timeout is None or timeout <= 0: + raise ValueError( + f"LIMESURVEY_TIMEOUT_SECONDS must be a positive integer, got: {timeout_raw!r}" + ) + else: + timeout = DEFAULT_TIMEOUT + + owner_raw = str(merged.get("owner_id", "")).strip() + group_raw = str(merged.get("group_id", "")).strip() + owner_id = _to_int(owner_raw) if owner_raw else None + group_id = _to_int(group_raw) if group_raw else None + if owner_raw and owner_id is None: + raise ValueError(f"LIMESURVEY_OWNER_ID must be an integer, got: {owner_raw!r}") + if group_raw and group_id is None: + raise ValueError(f"LIMESURVEY_GROUP_ID must be an integer, got: {group_raw!r}") + + verify_raw = str(merged.get("verify_ssl", "")).strip().lower() + if verify_raw in ("", "1", "true", "yes", "on"): + verify_ssl = True + elif verify_raw in ("0", "false", "no", "off"): + verify_ssl = False + else: + raise ValueError(f"LIMESURVEY_VERIFY_SSL must be true/false, got: {verify_raw!r}") + + return cls( + base_url=base_url, + username=str(merged["username"]).strip(), + password=str(merged["password"]), + timeout=timeout, + owner_id=owner_id, + group_id=group_id, + verify_ssl=verify_ssl, + ) diff --git a/pylimerpc/errors.py b/pylimerpc/errors.py new file mode 100644 index 0000000..dbd468b --- /dev/null +++ b/pylimerpc/errors.py @@ -0,0 +1,85 @@ +"""Custom exceptions of the library. + +Hierarchy: + +- ``LsError`` — base class for all pylimerpc errors +- ``LsConnectionError(LsError)`` — network/server unreachable (DNS, timeout, + HTTP error status, no valid JSON-RPC response); keeps ``url``, ``cause``, + ``http_status`` and ``body`` +- ``LsApiError(LsError)`` — the API returned a JSON-RPC error; keeps the + original RPC error (``rpc_code``, ``rpc_message``, ``raw``) plus ``method``, + ``http_status`` and ``body`` for diagnosis +- ``LsAuthError(LsApiError)`` — login refused or session key invalid/expired + +This lets callers catch specifically: connection problem vs. API error vs. auth error. +""" + +from __future__ import annotations + +from typing import Any + + +class LsError(Exception): + """Base class for all pylimerpc errors.""" + + +class LsConnectionError(LsError): + """The server was unreachable or did not return a valid JSON-RPC response. + + Attributes: + url — the endpoint that was called + cause — the underlying exception (e.g. ``urllib.error.URLError``) + http_status — HTTP status if the server did respond (e.g. 500), else None + body — (truncated) response body, for diagnosis + """ + + def __init__( + self, + message: str, + *, + url: str | None = None, + cause: BaseException | None = None, + http_status: int | None = None, + body: str | None = None, + ) -> None: + super().__init__(message) + self.url = url + self.cause = cause + self.http_status = http_status + self.body = body + + +class LsApiError(LsError): + """LimeSurvey returned a JSON-RPC error. + + Keeps the original RPC error plus diagnostic info: + method — the RPC method that was called (e.g. ``list_surveys``) + rpc_code — the status/code from the JSON-RPC error object + rpc_message — the message from the JSON-RPC error object + raw — the complete, original error object + http_status — HTTP status of the response + body — (truncated) response body + """ + + def __init__( + self, + message: str, + *, + method: str | None = None, + rpc_code: int | str | None = None, + rpc_message: str | None = None, + raw: Any = None, + http_status: int | None = None, + body: str | None = None, + ) -> None: + super().__init__(message) + self.method = method + self.rpc_code = rpc_code + self.rpc_message = rpc_message + self.raw = raw + self.http_status = http_status + self.body = body + + +class LsAuthError(LsApiError): + """Login failed or the session key is invalid / expired / refused.""" diff --git a/pylimerpc/responses.py b/pylimerpc/responses.py new file mode 100644 index 0000000..9bf2d26 --- /dev/null +++ b/pylimerpc/responses.py @@ -0,0 +1,154 @@ +"""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__responses.`` 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 diff --git a/pylimerpc/rpc.py b/pylimerpc/rpc.py new file mode 100644 index 0000000..5855f6f --- /dev/null +++ b/pylimerpc/rpc.py @@ -0,0 +1,250 @@ +"""JSON-RPC 2.0 transport for the LimeSurvey RemoteControl API. + +Standard library only (``urllib.request``). + +- ``endpoint_url(base_url)`` — turns a base URL into the correct endpoint + ``{base}index.php?r=admin/remotecontrol``. Note: the alias ``/remotecontrol`` + returns HTTP 400 in LimeSurvey — always use the ``index.php?r=...`` form. +- ``rpc_call(url, method, params, timeout=30)`` — performs one JSON-RPC 2.0 + POST and returns the ``result`` field. +- ``RpcClient`` — thin wrapper with a fixed endpoint URL and timeout; used by + session/surveys/responses/tokens. + +Error handling (everything diagnosable: method, params, HTTP status and body +are in the exception message and attributes): + +- network errors (urllib exceptions, timeout, HTTP error status, invalid JSON) + → ``LsConnectionError`` +- JSON-RPC ``error`` in the response → ``LsApiError`` (``LsAuthError`` for + auth errors) + +Debug logging (``logging.getLogger("pylimerpc.rpc")``) logs the +request, the response and the ``statistic`` field when LimeSurvey sends one. + +TLS: the server certificate is verified by default. With +``make_ssl_context(False)`` / ``LsConfig(verify_ssl=False)`` the check can be +disabled for test instances with a wrong certificate (never for production). +SSL errors (including certificate mismatch) surface as ``LsConnectionError`` +(``cause`` holds the underlying ``ssl.SSLError``). +""" + +from __future__ import annotations + +import itertools +import json +import logging +import ssl +import urllib.error +import urllib.request +from typing import Any + +from .config import LsConfig +from .errors import LsApiError, LsAuthError, LsConnectionError + +logger = logging.getLogger(__name__) + +DEFAULT_TIMEOUT = 30 +MAX_SNIPPET = 500 + +_ids = itertools.count(1) + +# strings that indicate an auth problem in an RPC error +_AUTH_HINTS = ( + "session key", + "invalid user", + "password", + "unauthorized", + "not authorized", + "permission", + "login", +) + + +def endpoint_url(base_url: str) -> str: + """Turn a base URL into the RemoteControl endpoint. + + ``https://host/limesurvey`` → ``https://host/limesurvey/index.php?r=admin/remotecontrol``. + If the URL already contains ``index.php`` (as in our .env), it is kept as-is. + """ + base = base_url.strip().rstrip("/") + if "index.php" in base: + return base + return f"{base}/index.php?r=admin/remotecontrol" + + +def make_ssl_context(verify_ssl: bool = True) -> ssl.SSLContext | None: + """Create an SSLContext for the HTTPS connection. + + ``verify_ssl=True`` (default) → ``None`` (urllib then uses its standard, + verifying context). ``verify_ssl=False`` → context without hostname and + certificate check — ONLY for local test instances with a wrong/self-signed + certificate, NEVER for production. + """ + if verify_ssl: + return None + ctx = ssl.create_default_context() + ctx.check_hostname = False + ctx.verify_mode = ssl.CERT_NONE + return ctx + + +def _snippet(value: Any, limit: int = MAX_SNIPPET) -> str: + """Make a short, log-safe snippet of a value.""" + text = value if isinstance(value, str) else repr(value) + if len(text) <= limit: + return text + return text[:limit] + "...(truncated)" + + +def _looks_like_auth_error(method: str, message: str | None) -> bool: + if method == "get_session_key": + return True + msg = (message or "").lower() + return any(hint in msg for hint in _AUTH_HINTS) + + +def rpc_call( + url: str, + method: str, + params: list[Any], + timeout: int = DEFAULT_TIMEOUT, + ssl_context: ssl.SSLContext | None = None, +) -> Any: + """Perform one JSON-RPC 2.0 call to ``url`` and return ``result``. + + Args: + url: the full RemoteControl endpoint (see ``endpoint_url``). + method: RPC method, e.g. ``"get_session_key"``. + params: list of parameters (positional order matters in LimeSurvey). + timeout: timeout in seconds for the HTTP call. + ssl_context: optional ``ssl.SSLContext`` (see ``make_ssl_context``); + ``None`` = standard verifying context. + + Returns: + The ``result`` field of the JSON-RPC response. + + Raises: + LsConnectionError: server unreachable, timeout, SSL error (incl. + certificate mismatch), HTTP error status or no valid JSON-RPC + response (method/params/HTTP status/body in message and attributes). + LsApiError: the response contains a JSON-RPC ``error`` (original + ``rpc_code``/``rpc_message`` in the attributes). + LsAuthError: subtype of LsApiError for login/session-key problems. + """ + req_id = next(_ids) + payload = {"jsonrpc": "2.0", "method": method, "params": params, "id": req_id} + body = json.dumps(payload, ensure_ascii=False).encode("utf-8") + request = urllib.request.Request( + url, + data=body, + headers={"Content-Type": "application/json", "Accept": "application/json"}, + method="POST", + ) + logger.debug( + "RPC request → POST %s | method=%s params=%s", + url, + method, + _snippet(json.dumps(params, ensure_ascii=False, default=str)), + ) + + http_status: int | None = None + raw_body = b"" + try: + with urllib.request.urlopen(request, timeout=timeout, context=ssl_context) as response: + http_status = response.status + raw_body = response.read() + except urllib.error.HTTPError as exc: + # the server did respond, but with an HTTP error status — the body often holds the cause + try: + raw_body = exc.read() + except Exception: + raw_body = b"" + text = raw_body.decode("utf-8", errors="replace") + snippet = _snippet(text) + raise LsConnectionError( + f"RPC {method!r} (params={_snippet(params)}) to {url} → HTTP {exc.code}, body: {snippet}", + url=url, + cause=exc, + http_status=exc.code, + body=snippet, + ) from exc + except (urllib.error.URLError, TimeoutError, OSError) as exc: + raise LsConnectionError( + f"RPC {method!r} (params={_snippet(params)}) to {url} failed — server unreachable/timeout: {exc}", + url=url, + cause=exc, + ) from exc + + text = raw_body.decode("utf-8", errors="replace") + logger.debug("RPC response ← method=%s HTTP %s body=%s", method, http_status, _snippet(text)) + + try: + out = json.loads(text) + except json.JSONDecodeError as exc: + raise LsConnectionError( + f"RPC {method!r} (params={_snippet(params)}) to {url} returned no valid JSON (HTTP {http_status}), body: {_snippet(text)}", + url=url, + cause=exc, + http_status=http_status, + body=_snippet(text), + ) from exc + + if not isinstance(out, dict): + raise LsConnectionError( + f"RPC {method!r} to {url} returned no JSON-RPC object (HTTP {http_status}), body: {_snippet(text)}", + url=url, + http_status=http_status, + body=_snippet(text), + ) + + if out.get("statistic") is not None: + logger.debug("RPC statistic field for %s: %s", method, out["statistic"]) + + if out.get("error"): + err = out["error"] + if isinstance(err, dict): + code = err.get("code") + message = err.get("message") + else: + code = None + message = str(err) + exc_cls = LsAuthError if _looks_like_auth_error(method, message) else LsApiError + raise exc_cls( + f"RPC {method!r} (params={_snippet(params)}) to {url} → HTTP {http_status}, " + f"API error code={code}: {message} | body: {_snippet(text)}", + method=method, + rpc_code=code, + rpc_message=message, + raw=err, + http_status=http_status, + body=_snippet(text), + ) + + return out.get("result") + + +class RpcClient: + """Wrapper around ``rpc_call`` with a fixed endpoint URL and timeout.""" + + def __init__( + self, + url: str, + timeout: int = DEFAULT_TIMEOUT, + ssl_context: ssl.SSLContext | None = None, + ) -> None: + self.url = url + self.timeout = timeout + self.ssl_context = ssl_context + + @classmethod + def from_config(cls, config: LsConfig) -> RpcClient: + """Build a client from an ``LsConfig`` (base_url, timeout, verify_ssl).""" + return cls( + endpoint_url(config.base_url), + timeout=config.timeout, + ssl_context=make_ssl_context(config.verify_ssl), + ) + + def call(self, method: str, params: list[Any]) -> Any: + """Perform an RPC call on the fixed endpoint URL.""" + return rpc_call(self.url, method, params, timeout=self.timeout, ssl_context=self.ssl_context) diff --git a/pylimerpc/session.py b/pylimerpc/session.py new file mode 100644 index 0000000..e439e51 --- /dev/null +++ b/pylimerpc/session.py @@ -0,0 +1,48 @@ +"""Session management: create and release session keys via the RemoteControl API. + +- ``get_session_key(client, username, password) -> str`` + Raises ``LsAuthError`` when the login is refused. Note: LimeSurvey puts + ``{"status": "Invalid user name or password!"}`` in the **result** (not in + ``error``) on a failed login — this is handled here. +- ``release_session_key(client, session_key)`` +""" + +from __future__ import annotations + +from typing import Any + +from .errors import LsAuthError +from .rpc import RpcClient + + +def get_session_key(client: RpcClient, username: str, password: str) -> str: + """Request a session key from the RemoteControl endpoint. + + Args: + client: an ``RpcClient`` (fixed endpoint URL). + username: RemoteControl user. + password: password (or API token). + + Returns: + The session key as a string. + + Raises: + LsAuthError: when the login is refused (wrong credentials or blocked user). + LsConnectionError: when the server is unreachable. + """ + result = client.call("get_session_key", [username, password]) + if isinstance(result, str) and result: + return result + # LS error pattern: result = {"status": "Invalid user name or password!"} + status = result.get("status") if isinstance(result, dict) else result + raise LsAuthError( + f"Login failed (get_session_key): {status!r}", + method="get_session_key", + rpc_message=str(status), + raw=result, + ) + + +def release_session_key(client: RpcClient, session_key: str) -> Any: + """Release a session key properly (returns the RPC result).""" + return client.call("release_session_key", [session_key]) diff --git a/pylimerpc/surveys.py b/pylimerpc/surveys.py new file mode 100644 index 0000000..1e6c58a --- /dev/null +++ b/pylimerpc/surveys.py @@ -0,0 +1,101 @@ +"""Query surveys via the RemoteControl API. + +- ``list_surveys(client, session_key, owner_id=None, group_id=None)`` — list of + survey dicts (``owner_id`` is sent as the 2nd RPC param ``iUserID``; + ``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 +- ``filter_active(surveys)`` — only active surveys (``active == "Y"``) +""" + +from __future__ import annotations + +from typing import Any, Iterable + +from .errors import LsApiError +from .rpc import RpcClient +from .utils import is_active_flag, raise_for_status, to_int + +_GROUP_KEYS = ("group_id", "gsid", "group") + + +def _survey_group_id(survey: dict[str, Any]) -> Any: + for key in _GROUP_KEYS: + if key in survey: + return survey[key] + return None + + +def list_surveys( + client: RpcClient, + session_key: str, + owner_id: int | str | None = None, + group_id: int | str | None = None, +) -> list[dict[str, Any]]: + """List all surveys the session key has access to. + + Args: + client: an ``RpcClient``. + session_key: a valid session key. + owner_id: optional, sent as the 2nd RPC parameter (``iUserID``). + group_id: optional, client-side filter on a group field in the result. + + Returns: + List of survey dicts (``sid``, ``surveyls_title``, ``active``, ...). + + Raises: + LsAuthError: invalid session key; LsApiError: other API errors. + """ + params: list[Any] = [session_key] + if owner_id is not None: + as_int = to_int(owner_id) + params.append(as_int if as_int is not None else owner_id) + result = client.call("list_surveys", params) + raise_for_status(result, "list_surveys") + if not isinstance(result, list): + raise LsApiError( + f"list_surveys did not return a list: {result!r}", + method="list_surveys", + raw=result, + ) + surveys = [s for s in result if isinstance(s, dict)] + if group_id is not None: + surveys = [s for s in surveys if str(_survey_group_id(s)) == str(group_id)] + return surveys + + +def get_survey_properties( + client: RpcClient, + session_key: str, + sid: int | str, + properties: Iterable[str] | None = None, +) -> dict[str, Any]: + """Get the properties of a single survey. + + Args: + client: an ``RpcClient``. + session_key: a valid session key. + sid: survey ID (numeric strings are converted to int). + properties: optional list of property names; None = all. + + Returns: + Dict with survey properties (contains e.g. ``sid``, ``surveyls_title``, ``active``). + """ + sid_int = to_int(sid) + params: list[Any] = [session_key, sid_int if sid_int is not None else sid] + if properties: + params.append(list(properties)) + result = client.call("get_survey_properties", params) + raise_for_status(result, "get_survey_properties") + if not isinstance(result, dict): + raise LsApiError( + f"get_survey_properties did not return a dict: {result!r}", + method="get_survey_properties", + raw=result, + ) + return result + + +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"))] diff --git a/pylimerpc/tokens.py b/pylimerpc/tokens.py new file mode 100644 index 0000000..bb74692 --- /dev/null +++ b/pylimerpc/tokens.py @@ -0,0 +1,113 @@ +"""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). +""" + +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"}]``. + 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``, ...). + """ + 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 diff --git a/pylimerpc/utils.py b/pylimerpc/utils.py new file mode 100644 index 0000000..d3d03b7 --- /dev/null +++ b/pylimerpc/utils.py @@ -0,0 +1,132 @@ +"""Small shared helpers (pure functions, no state). + +- ``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 +- ``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). +""" + +from __future__ import annotations + +import base64 +import json +from typing import Any + +from .errors import LsApiError, LsAuthError + +_AUTH_STATUS_HINTS = ( + "session key", + "invalid user", + "password", + "permission", + "unauthorized", + "not authorized", + "login", +) + + +def to_int(value: Any) -> int | None: + """Safe conversion to int; ``None`` for empty/invalid values.""" + if value is None: + return None + text = str(value).strip() + if not text: + return None + try: + return int(text) + except ValueError: + return None + + +def is_active_flag(value: Any) -> bool: + """LS ``active`` field: ``"Y"`` / ``"1"`` / ``"true"`` → True.""" + return str(value).strip().upper() in {"Y", "1", "TRUE"} + + +def is_filled(value: Any) -> bool: + """Is an answer value filled (not None, empty string or ``"[]"``)?""" + if value is None: + return False + if isinstance(value, str) and value.strip() == "": + return False + if value == "[]": + return False + return True + + +def parse_responses_json(text: str) -> list[dict[str, Any]]: + """Parse a JSON responses export (already base64-decoded) into ``list[dict]``.""" + parsed = json.loads(text) + if isinstance(parsed, dict) and isinstance(parsed.get("responses"), list): + return parsed["responses"] + if isinstance(parsed, list): + return parsed + if isinstance(parsed, dict): + return [parsed] + return [] + + +def decode_export_json(result: Any) -> list[dict[str, Any]]: + """Decode a base64 JSON ``export_responses`` result into ``list[dict]``.""" + if not isinstance(result, str) or not result: + return [] + decoded = base64.b64decode(result) + return parse_responses_json(decoded.decode("utf-8")) + + +def normalize_sid(sid: Any) -> Any: + """Numeric sid strings → int (LS expects ``iSurveyID`` as int).""" + as_int = to_int(sid) + return as_int if as_int is not None else sid + + +def summary_counts(summary: dict[str, Any]) -> tuple[int | None, int | None]: + """Extract (completed, total) response counts from a ``get_summary`` result. + + Key names differ per LS version; the first match wins. + """ + completed = None + total = None + for key in ("completed_responses", "responses_completed", "completed"): + if key in summary: + completed = to_int(summary.get(key)) + break + for key in ("responses", "full_responses", "responses_total", "all_responses"): + if key in summary: + total = to_int(summary.get(key)) + break + return completed, total + + +def is_status_error(result: Any) -> bool: + """True if ``result`` is an LS error dict: ``{"status": "..."}`` or + ``{"status": "...", "error_code": "..."}``. + + A survey-properties dict has a ``status`` key among many other keys and + must therefore NOT be treated as an error. + """ + return ( + isinstance(result, dict) + and "status" in result + and set(result.keys()) <= {"status", "error_code", "error"} + ) + + +def raise_for_status(result: Any, method: str) -> Any: + """Raise LsApiError/LsAuthError if ``result`` is a ``{"status": ...}`` error dict. + + Returns ``result`` unchanged otherwise. + """ + if is_status_error(result): + status = str(result["status"]) + low = status.lower() + exc_cls = LsAuthError if any(h in low for h in _AUTH_STATUS_HINTS) else LsApiError + raise exc_cls( + f"RPC {method!r} returned a status error: {status!r}", + method=method, + rpc_message=status, + raw=result, + ) + return result diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..cf900c6 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,35 @@ +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + +[project] +name = "PyLimeRPC" +version = "0.1.0" +description = "PyLimeRPC — reusable Python client for the LimeSurvey RemoteControl JSON-RPC API (LS7)" +readme = "README.md" +requires-python = ">=3.10" +authors = [{ name = "Respondage" }] +keywords = ["limesurvey", "remotecontrol", "json-rpc", "surveys"] +classifiers = [ + "Intended Audience :: Developers", + "Operating System :: POSIX :: Linux", + "Programming Language :: Python :: 3", + "Topic :: Internet :: WWW/HTTP :: WSGI", +] +# No runtime dependencies: Python standard library only. +dependencies = [] + +# Development/tests only; not needed for normal use. +[project.optional-dependencies] +dev = ["pytest>=8"] + +# Explicit package list (avoids flat-layout detection issues with test.py/tests/). +[tool.setuptools] +packages = ["pylimerpc"] + +[tool.pytest.ini_options] +markers = [ + "integration: tests against a real LimeSurvey instance (skipped by default; run with: pytest -m integration)", +] +# Integration tests are OFF by default; run only those with 'pytest -m integration'. +addopts = "-m 'not integration'" diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..eeafd9d --- /dev/null +++ b/tests/__init__.py @@ -0,0 +1,5 @@ +"""Tests for pylimerpc. + +Unit tests use fakes/stub servers (no real LimeSurvey needed); +integration tests live in test_integration.py and are skipped by default. +""" diff --git a/tests/test_config.py b/tests/test_config.py new file mode 100644 index 0000000..8eb73e0 --- /dev/null +++ b/tests/test_config.py @@ -0,0 +1,175 @@ +"""Unit tests for pylimerpc.config (pytest).""" + +from __future__ import annotations + +import os + +import pytest + +from pylimerpc.config import LsConfig, load_dotenv, parse_dotenv + +DOTENV = """\ +# comment line +LIMESURVEY_BASE_URL=https://ls.example.com/index.php?r=admin/remotecontrol + +LIMESURVEY_USERNAME=test_user +LIMESURVEY_PASSWORD="secret with spaces" +LIMESURVEY_TIMEOUT_SECONDS=45 +LIMESURVEY_OWNER_ID=123 +""" + +BASE_ENV = { + "LIMESURVEY_BASE_URL": "https://ls.example.com/index.php?r=admin/remotecontrol", + "LIMESURVEY_USERNAME": "test_user", + "LIMESURVEY_PASSWORD": "geheim", +} + + +def test_parse_dotenv(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text(DOTENV, encoding="utf-8") + values = parse_dotenv(env_file) + assert values["LIMESURVEY_BASE_URL"] == "https://ls.example.com/index.php?r=admin/remotecontrol" + assert values["LIMESURVEY_USERNAME"] == "test_user" + # quotes stripped, but inner content (spaces) is preserved + assert values["LIMESURVEY_PASSWORD"] == "secret with spaces" + assert values["LIMESURVEY_TIMEOUT_SECONDS"] == "45" + assert values["LIMESURVEY_OWNER_ID"] == "123" + assert not any("comment" in key for key in values) + + +def test_from_dotenv_leest_bestand(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text(DOTENV, encoding="utf-8") + cfg = LsConfig.from_dotenv(env_file, environ={}) + assert cfg.base_url == "https://ls.example.com/index.php?r=admin/remotecontrol" + assert cfg.username == "test_user" + assert cfg.password == "secret with spaces" + assert cfg.timeout == 45 + assert cfg.owner_id == 123 + assert cfg.group_id is None + + +def test_from_dotenv_bestaat_niet(tmp_path): + with pytest.raises(FileNotFoundError): + LsConfig.from_dotenv(tmp_path / "missing.env", environ={}) + + +def test_from_dotenv_verplichte_velden_ontbreken(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text("LIMESURVEY_BASE_URL=https://x.example.com\n", encoding="utf-8") + with pytest.raises(ValueError) as excinfo: + LsConfig.from_dotenv(env_file, environ={}) + msg = str(excinfo.value) + assert "LIMESURVEY_USERNAME" in msg + assert "LIMESURVEY_PASSWORD" in msg + assert "LIMESURVEY_BASE_URL" not in msg # that one was set + + +def test_parameters_overschrijven_bestand(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text(DOTENV, encoding="utf-8") + cfg = LsConfig.from_dotenv(env_file, environ={}, username="ander", timeout=99) + assert cfg.username == "ander" + assert cfg.timeout == 99 + # non-overridden fields come from the file + assert cfg.base_url == "https://ls.example.com/index.php?r=admin/remotecontrol" + + +def test_environment_wint_van_bestand(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text(DOTENV, encoding="utf-8") + environ = dict(BASE_ENV, LIMESURVEY_USERNAME="env_user") + cfg = LsConfig.from_dotenv(env_file, environ=environ) + assert cfg.username == "env_user" + + +def test_from_env(monkeypatch): + for key, value in BASE_ENV.items(): + monkeypatch.setenv(key, value) + monkeypatch.setenv("LIMESURVEY_TIMEOUT_SECONDS", "15") + cfg = LsConfig.from_env() + assert cfg.base_url == BASE_ENV["LIMESURVEY_BASE_URL"] + assert cfg.username == "test_user" + assert cfg.timeout == 15 + assert cfg.owner_id is None + assert cfg.group_id is None + + +def test_from_env_ontbreekt(monkeypatch): + monkeypatch.delenv("LIMESURVEY_BASE_URL", raising=False) + monkeypatch.delenv("LIMESURVEY_USERNAME", raising=False) + monkeypatch.delenv("LIMESURVEY_PASSWORD", raising=False) + with pytest.raises(ValueError) as excinfo: + LsConfig.from_env(environ={}) + assert "LIMESURVEY_BASE_URL" in str(excinfo.value) + + +def test_timeout_default_en_foutief(tmp_path): + env_file = tmp_path / ".env" + basis = "LIMESURVEY_BASE_URL=https://x.example.com\nLIMESURVEY_USERNAME=u\nLIMESURVEY_PASSWORD=p\n" + env_file.write_text(basis, encoding="utf-8") + assert LsConfig.from_dotenv(env_file, environ={}).timeout == 30 + + env_file.write_text(basis + "LIMESURVEY_TIMEOUT_SECONDS=abc\n", encoding="utf-8") + with pytest.raises(ValueError): + LsConfig.from_dotenv(env_file, environ={}) + + +def test_owner_group_optioneel(tmp_path): + env_file = tmp_path / ".env" + basis = "LIMESURVEY_BASE_URL=https://x.example.com\nLIMESURVEY_USERNAME=u\nLIMESURVEY_PASSWORD=p\n" + env_file.write_text(basis + "LIMESURVEY_GROUP_ID=7\n", encoding="utf-8") + cfg = LsConfig.from_dotenv(env_file, environ={}) + assert cfg.owner_id is None + assert cfg.group_id == 7 + + env_file.write_text(basis + "LIMESURVEY_OWNER_ID=abc\n", encoding="utf-8") + with pytest.raises(ValueError): + LsConfig.from_dotenv(env_file, environ={}) + + +def test_onbekende_parameter(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text(DOTENV, encoding="utf-8") + with pytest.raises(TypeError): + LsConfig.from_dotenv(env_file, environ={}, typo_veld=1) + + +def test_base_url_moet_http_zijn(tmp_path): + env_file = tmp_path / ".env" + env_file.write_text( + "LIMESURVEY_BASE_URL=ftp://x.example.com\nLIMESURVEY_USERNAME=u\nLIMESURVEY_PASSWORD=p\n", + encoding="utf-8", + ) + with pytest.raises(ValueError): + LsConfig.from_dotenv(env_file, environ={}) + + +def test_load_dotenv_setdefault_en_override(tmp_path, monkeypatch): + env_file = tmp_path / ".env" + env_file.write_text(DOTENV, encoding="utf-8") + monkeypatch.setenv("LIMESURVEY_USERNAME", "already_set") + load_dotenv(env_file) + assert os.environ["LIMESURVEY_USERNAME"] == "already_set" # env wins (setdefault) + load_dotenv(env_file, override=True) + assert os.environ["LIMESURVEY_USERNAME"] == "test_user" # file wins + + +def test_verify_ssl_parsing(tmp_path): + env_file = tmp_path / ".env" + basis = "LIMESURVEY_BASE_URL=https://x.example.com\nLIMESURVEY_USERNAME=u\nLIMESURVEY_PASSWORD=p\n" + env_file.write_text(basis, encoding="utf-8") + assert LsConfig.from_dotenv(env_file, environ={}).verify_ssl is True # default = on + + for raw, expected in [("false", False), ("0", False), ("FALSE", False), ("no", False), ("true", True), ("1", True)]: + env_file.write_text(basis + f"LIMESURVEY_VERIFY_SSL={raw}\n", encoding="utf-8") + assert LsConfig.from_dotenv(env_file, environ={}).verify_ssl is expected + + env_file.write_text(basis + "LIMESURVEY_VERIFY_SSL=jawel\n", encoding="utf-8") + with pytest.raises(ValueError): + LsConfig.from_dotenv(env_file, environ={}) + + # explicit parameter wins + env_file.write_text(basis + "LIMESURVEY_VERIFY_SSL=true\n", encoding="utf-8") + assert LsConfig.from_dotenv(env_file, environ={}, verify_ssl=False).verify_ssl is False diff --git a/tests/test_errors.py b/tests/test_errors.py new file mode 100644 index 0000000..ebe4abc --- /dev/null +++ b/tests/test_errors.py @@ -0,0 +1,38 @@ +"""Unit tests for pylimerpc.errors (pytest).""" + +from __future__ import annotations + +from pylimerpc.errors import LsApiError, LsAuthError, LsConnectionError, LsError + + +def test_api_error_bewaart_originele_rpc_fout(): + raw = {"code": -32602, "message": "Invalid params"} + err = LsApiError( + "list_surveys failed", + method="list_surveys", + rpc_code=raw["code"], + rpc_message=raw["message"], + raw=raw, + ) + assert isinstance(err, LsError) + assert err.method == "list_surveys" + assert err.rpc_code == -32602 + assert err.rpc_message == "Invalid params" + assert err.raw == raw + assert "list_surveys failed" in str(err) + + +def test_auth_error_is_een_api_error(): + err = LsAuthError("login refused", rpc_message="Invalid user name or password!") + assert isinstance(err, LsApiError) + assert isinstance(err, LsError) + assert err.rpc_message == "Invalid user name or password!" + + +def test_connection_error_bewaart_url_en_cause(): + cause = OSError("connection timed out") + err = LsConnectionError("server onbereikbaar", url="https://ls.example.com", cause=cause) + assert isinstance(err, LsError) + assert not isinstance(err, LsApiError) + assert err.url == "https://ls.example.com" + assert err.cause is cause diff --git a/tests/test_examples.py b/tests/test_examples.py new file mode 100644 index 0000000..e230ce5 --- /dev/null +++ b/tests/test_examples.py @@ -0,0 +1,129 @@ +"""Tests for the example scripts: ASGI app and CLI with a fake LsClient/LsConfig.""" + +from __future__ import annotations + +import asyncio +import sys +from pathlib import Path +from typing import Any + +from pylimerpc.errors import LsError + + +class FakeLs: + """Duck-typed replacement for LsClient with canned data.""" + + surveys = [ + {"sid": 1, "surveyls_title": "Test ", "active": "Y"}, + {"sid": 2, "surveyls_title": "Inactief", "active": "N"}, + ] + + def __init__(self, cfg: Any) -> None: + pass + + def __enter__(self) -> FakeLs: + return self + + def __exit__(self, *args: Any) -> None: + return None + + def list_surveys(self) -> list[dict[str, Any]]: + return list(self.surveys) + + def export_responses(self, sid: Any, doc_type: str = "csv", output_path: Any = None) -> Path: + out = Path(output_path) if output_path else Path("output") + if out.is_dir(): + out = out / f"survey_{sid}_responses.{doc_type}" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_bytes(b"fake-export") + return out + + def list_participants(self, sid: Any, **kwargs: Any) -> list[dict[str, Any]]: + return [{"tid": "1", "email": "a@b.c", "token": "tok", "completed": "N"}] + + +class FakeCfg: + @classmethod + def from_dotenv(cls, path: Any) -> FakeCfg: + return cls() + + +def _patch(monkeypatch, module) -> None: + monkeypatch.setattr(module, "LsClient", FakeLs) + monkeypatch.setattr(module, "LsConfig", FakeCfg) + + +def _run_asgi(app, path: str = "/") -> tuple[int, bytes]: + sent: list[dict[str, Any]] = [] + + async def receive() -> dict[str, Any]: + return {"type": "http.request", "body": b"", "more_body": False} + + async def send(msg: dict[str, Any]) -> None: + sent.append(msg) + + asyncio.run(app({"type": "http", "method": "GET", "path": path, "headers": []}, receive, send)) + status = sent[0]["status"] + body = b"".join(m.get("body", b"") for m in sent if m["type"] == "http.response.body") + return status, body + + +# -- ASGI ------------------------------------------------------------------- + + +def test_asgi_index_toont_alleen_actieve_surveys(monkeypatch): + import examples.example_asgi as ex + + _patch(monkeypatch, ex) + status, body = _run_asgi(ex.app, "/") + assert status == 200 + assert b"Test <b>" in body # HTML-ge-escaped + assert b"Inactief" not in body # inactive survey filtered out + assert b"1" in body + + +def test_asgi_health_en_404(monkeypatch): + import examples.example_asgi as ex + + _patch(monkeypatch, ex) + assert _run_asgi(ex.app, "/health") == (200, b"ok") + status, _ = _run_asgi(ex.app, "/anders") + assert status == 404 + + +def test_asgi_502_bij_ls_fout(monkeypatch): + import examples.example_asgi as ex + + class BrokenLs(FakeLs): + def list_surveys(self): + raise LsError("stuk") + + monkeypatch.setattr(ex, "LsClient", BrokenLs) + monkeypatch.setattr(ex, "LsConfig", FakeCfg) + status, body = _run_asgi(ex.app, "/") + assert status == 502 + assert b"stuk" in body + + +# -- CLI --------------------------------------------------------------------- + + +def test_cli_export_tokens_surveys(monkeypatch, tmp_path, capsys): + import examples.example_cli as cli + + _patch(monkeypatch, cli) + + monkeypatch.setattr(sys, "argv", ["example_cli.py", "export", "--sid", "5", "--out", str(tmp_path)]) + assert cli.main() == 0 + assert (tmp_path / "survey_5_responses.csv").read_bytes() == b"fake-export" + + monkeypatch.setattr(sys, "argv", ["example_cli.py", "tokens-lijst", "--sid", "5"]) + assert cli.main() == 0 + out = capsys.readouterr().out + assert "a@b.c" in out and "tok" in out + + monkeypatch.setattr(sys, "argv", ["example_cli.py", "surveys"]) + assert cli.main() == 0 + out = capsys.readouterr().out + assert "Test " in out + assert "Inactief" not in out # active surveys only diff --git a/tests/test_integration.py b/tests/test_integration.py new file mode 100644 index 0000000..4ca7bef --- /dev/null +++ b/tests/test_integration.py @@ -0,0 +1,78 @@ +"""Integration tests against a real (local) LimeSurvey instance. + +Skipped by default (pyproject: addopts = -m "not integration"). +Run them manually with the local endpoint via environment variables: + + LIMESURVEY_BASE_URL='https://localhost/limesurvey/index.php?r=admin/remotecontrol' \ + LIMESURVEY_USERNAME='...' LIMESURVEY_PASSWORD='...' \ + .venv/bin/python -m pytest -m integration -v + +Without those variables the tests are skipped. +Optional: LIMESURVEY_VERIFY_SSL=false for a test instance with a wrong certificate. +""" + +from __future__ import annotations + +import os + +import pytest + +from pylimerpc import LsClient, LsConfig +from pylimerpc.errors import LsApiError +from pylimerpc.utils import parse_responses_json + +pytestmark = pytest.mark.integration + + +def _config_from_env() -> LsConfig: + base_url = os.environ.get("LIMESURVEY_BASE_URL", "").strip() + username = os.environ.get("LIMESURVEY_USERNAME", "").strip() + password = os.environ.get("LIMESURVEY_PASSWORD", "").strip() + if not (base_url and username and password): + pytest.skip( + "Set LIMESURVEY_BASE_URL, LIMESURVEY_USERNAME and LIMESURVEY_PASSWORD " + "(local LimeSurvey endpoint) to run the integration tests" + ) + timeout = int(os.environ.get("LIMESURVEY_TIMEOUT_SECONDS", "30") or 30) + verify_ssl = os.environ.get("LIMESURVEY_VERIFY_SSL", "true").strip().lower() not in ("0", "false", "no", "off") + return LsConfig(base_url=base_url, username=username, password=password, timeout=timeout, verify_ssl=verify_ssl) + + +def test_sessie_openen_list_surveys_eigenschappen_en_sluiten(): + cfg = _config_from_env() + with LsClient(cfg) as ls: + assert ls.session_key, "no session key received" + surveys = ls.list_surveys() + assert isinstance(surveys, list) + print(f"\n{len(surveys)} surveys gevonden:") + for s in surveys[:10]: + print(f" sid={s.get('sid')} | active={s.get('active')} | {s.get('surveyls_title')}") + if surveys: + sid = surveys[0].get("sid") + 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]} ...") + # context manager released the session cleanly + assert ls.session_key is None + + +def test_export_responses_en_statistieken_readonly(): + """Read-only export against the real instance (no data modified).""" + cfg = _config_from_env() + with LsClient(cfg) as ls: + surveys = ls.list_surveys() + if not surveys: + pytest.skip("no surveys on this instance") + sid = surveys[0]["sid"] + data = ls.export_responses(sid, doc_type="json") + assert isinstance(data, bytes) + rows = parse_responses_json(data.decode("utf-8")) if data else [] + print(f"\nexport_responses sid={sid}: {len(rows)} response-rows, {len(data)} bytes") + try: + stats = ls.export_statistics(sid, doc_type="json") + except LsApiError as exc: + # server may return an empty statistics export (statistics off / no permission) + pytest.skip(f"export_statistics returned an empty export on this instance: {exc}") + assert isinstance(stats, bytes) + print(f"export_statistics sid={sid}: {len(stats)} bytes") diff --git a/tests/test_responses_tokens.py b/tests/test_responses_tokens.py new file mode 100644 index 0000000..d48c6ca --- /dev/null +++ b/tests/test_responses_tokens.py @@ -0,0 +1,167 @@ +"""Unit tests for responses.py and tokens.py (FakeRpc, no server) + LsClient wiring.""" + +from __future__ import annotations + +import base64 +import json +from pathlib import Path +from typing import Any + +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.tokens import add_participants, delete_participants, list_participants + + +class FakeRpc: + def __init__(self, *responses: Any) -> None: + self.responses = list(responses) + self.calls: list[tuple[str, list[Any]]] = [] + + def call(self, method: str, params: list[Any]) -> Any: + self.calls.append((method, list(params))) + item = self.responses.pop(0) + if isinstance(item, BaseException): + raise item + return item + + +CFG = LsConfig(base_url="https://ls.example.com/index.php?r=admin/remotecontrol", username="u", password="p") + + +def b64(payload: bytes) -> str: + return base64.b64encode(payload).decode("ascii") + + +# -- responses -------------------------------------------------------------- + + +def test_export_responses_params_en_base64_decode(): + raw = json.dumps({"responses": [{"id": "1"}]}).encode("utf-8") + fake = FakeRpc(b64(raw)) + data = export_responses(fake, "KEY", "123") # type: ignore[arg-type] + assert data == raw + # LS7 export_responses: [session_key, sid, doc_type, language, completion, field_map, header] + assert fake.calls == [("export_responses", ["KEY", 123, "json", None, "all", "code", "short"])] + + +def test_export_responses_doc_type_csv_en_output_path(tmp_path): + fake = FakeRpc(b64(b"a,b\n1,2\n")) + out = export_responses(fake, "KEY", 5, doc_type="csv", output_path=tmp_path / "export.csv") # type: ignore[arg-type] + assert isinstance(out, Path) + assert out.read_bytes() == b"a,b\n1,2\n" + assert fake.calls[0][1][2] == "csv" + + +def test_export_responses_output_path_is_directory(tmp_path): + fake = FakeRpc(b64(b"{}")) + out = export_responses(fake, "KEY", 9, doc_type="json", output_path=tmp_path) # type: ignore[arg-type] + assert out == tmp_path / "survey_9_responses.json" + assert out.exists() + + +def test_export_responses_json_wrapper(): + payload = {"responses": [{"id": "1", "Q1": "ja"}, {"id": "2", "Q1": "nee"}]} + fake = FakeRpc(b64(json.dumps(payload).encode("utf-8"))) + rows = export_responses_json(fake, "KEY", 5) # type: ignore[arg-type] + assert rows == payload["responses"] + + +def test_export_responses_status_fout_is_lsautherror(): + fake = FakeRpc({"status": "Invalid session key"}) + with pytest.raises(LsAuthError): + export_responses(fake, "OUDE-KEY", 5) # type: ignore[arg-type] + + +def test_export_responses_leeg_resultaat_is_lsapierror(): + fake = FakeRpc("") + with pytest.raises(LsApiError): + export_responses(fake, "KEY", 5) # type: ignore[arg-type] + + +def test_export_statistics_params_en_decode(): + raw = json.dumps({"statistics": []}).encode("utf-8") + fake = FakeRpc(b64(raw)) + data = export_statistics(fake, "KEY", 7, doc_type="json") # type: ignore[arg-type] + assert data == raw + # LS7 export_statistics: [session_key, sid, doc_type, language] + assert fake.calls == [("export_statistics", ["KEY", 7, "json", None])] + + +# -- tokens ----------------------------------------------------------------- + + +def test_add_participants_params(): + participants = [{"email": "a@b.c", "firstname": "A", "lastname": "B"}] + fake = FakeRpc([{"tid": "1", "token": "tok123", "email": "a@b.c"}]) + out = add_participants(fake, "KEY", 5, participants) # type: ignore[arg-type] + assert out[0]["token"] == "tok123" + assert fake.calls == [("add_participants", ["KEY", 5, participants])] + + +def test_add_participants_create_token_param_en_typecheck(): + fake = FakeRpc([]) + add_participants(fake, "KEY", 5, [], create_token=False) # type: ignore[arg-type] + assert fake.calls == [("add_participants", ["KEY", 5, [], False])] + with pytest.raises(TypeError): + add_participants(fake, "KEY", 5, "not-a-list") # type: ignore[arg-type] + + +def test_list_participants_normaliseert_en_params(): + fake = FakeRpc({"participants": [{"tid": "1", "email": "a@b.c"}]}) + out = list_participants(fake, "KEY", 5) # type: ignore[arg-type] + assert out == [{"tid": "1", "email": "a@b.c"}] + # LS7 list_participants: [session_key, sid, start, limit] (+ conditions, language) + assert fake.calls == [("list_participants", ["KEY", 5, 0, 100000])] + + fake2 = FakeRpc([{"tid": "2"}]) + out2 = list_participants(fake2, "KEY", 5, start=10, limit=50, conditions={"email": "x"}, language="nl") # type: ignore[arg-type] + assert out2 == [{"tid": "2"}] + assert fake2.calls == [("list_participants", ["KEY", 5, 10, 50, {"email": "x"}, "nl"])] + + +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] + assert out == {"1": "OK", "2": "OK"} + # LS7 delete_participants: [session_key, sid, [token_ids]] + assert fake.calls == [("delete_participants", ["KEY", 5, [1, 2]])] + with pytest.raises(TypeError): + delete_participants(fake, "KEY", 5, "not-a-list") # type: ignore[arg-type] + + +# -- LsClient wiring ---------------------------------------------------------- + + +def test_lsclient_responses_en_tokens_delegeren_met_session_key(): + raw = b64(json.dumps({"responses": []}).encode("utf-8")) + fake = FakeRpc( + "KEY", # get_session_key + raw, # export_responses + raw, # export_statistics + [{"tid": "1"}], # add_participants + {"participants": [{"tid": "1"}]}, # list_participants + {"1": "OK"}, # delete_participants + True, # release_session_key + ) + with LsClient(CFG, rpc=fake) as ls: # type: ignore[arg-type] + assert isinstance(ls.export_responses(5), bytes) + assert isinstance(ls.export_statistics(5), bytes) + ls.add_participants(5, [{"email": "a@b.c"}]) + assert ls.list_participants(5) == [{"tid": "1"}] + assert ls.delete_participants(5, [1]) == {"1": "OK"} + methods = [c[0] for c in fake.calls] + assert methods == [ + "get_session_key", + "export_responses", + "export_statistics", + "add_participants", + "list_participants", + "delete_participants", + "release_session_key", + ] + # session key is in every call + assert fake.calls[1][1][0] == "KEY" + assert fake.calls[3][1][1] == 5 diff --git a/tests/test_rpc.py b/tests/test_rpc.py new file mode 100644 index 0000000..91cdd85 --- /dev/null +++ b/tests/test_rpc.py @@ -0,0 +1,214 @@ +"""Unit tests for pylimerpc.rpc. + +Uses a stub HTTP server (stdlib http.server in a thread) — no real +LimeSurvey needed. +""" + +from __future__ import annotations + +import json +import logging +import socket +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from types import SimpleNamespace +from typing import Any + +import pytest + +from pylimerpc.errors import LsApiError, LsAuthError, LsConnectionError +from pylimerpc.rpc import endpoint_url, rpc_call + + +class _StubHandler(BaseHTTPRequestHandler): + def log_message(self, *args: Any) -> None: # keep test output quiet + pass + + def _send_bytes(self, out: bytes, status: int, content_type: str) -> None: + self.send_response(status) + self.send_header("Content-Type", content_type) + self.send_header("Content-Length", str(len(out))) + self.end_headers() + self.wfile.write(out) + + def _send_json(self, obj: dict, status: int = 200) -> None: + self._send_bytes(json.dumps(obj).encode("utf-8"), status, "application/json") + + def do_POST(self) -> None: + length = int(self.headers.get("Content-Length") or 0) + body = self.rfile.read(length) + self.server.last_request = { # type: ignore[attr-defined] + "path": self.path, + "content_type": self.headers.get("Content-Type"), + "body": body, + } + try: + payload = json.loads(body.decode("utf-8")) + except json.JSONDecodeError: + payload = {} + method = payload.get("method") + rid = payload.get("id") + + if self.path == "/http500": + self._send_bytes(b"

500 Internal Server Error

", 500, "text/html") + return + if self.path == "/badjson": + self._send_bytes(b"this is not valid json", 200, "application/json") + return + if method == "fail_api": + self._send_json({"jsonrpc": "2.0", "id": rid, "result": None, "error": {"code": -32602, "message": "Invalid params"}}) + return + if method == "fail_auth": + self._send_json({"jsonrpc": "2.0", "id": rid, "result": None, "error": {"code": -32000, "message": "Invalid session key"}}) + return + 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 + self._send_json({"jsonrpc": "2.0", "id": rid, "result": {"method": method, "params": payload.get("params")}, "error": None}) + + +@pytest.fixture() +def stub(): + server = ThreadingHTTPServer(("127.0.0.1", 0), _StubHandler) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + port = server.server_address[1] + yield SimpleNamespace(url=f"http://127.0.0.1:{port}", server=server) + server.shutdown() + server.server_close() + thread.join(timeout=5) + + +def test_rpc_call_succes_geeft_result_en_stuurt_juiste_request(stub): + result = rpc_call(f"{stub.url}/rpc", "echo", ["a", 1], timeout=5) + assert result == {"method": "echo", "params": ["a", 1]} + + req = stub.server.last_request # type: ignore[attr-defined] + assert req["path"] == "/rpc" + assert req["content_type"] == "application/json" + sent = json.loads(req["body"].decode("utf-8")) + assert sent["jsonrpc"] == "2.0" + assert sent["method"] == "echo" + assert sent["params"] == ["a", 1] + assert isinstance(sent["id"], int) + + +def test_api_fout_wordt_lsapierror_met_diagnose(stub): + with pytest.raises(LsApiError) as excinfo: + rpc_call(f"{stub.url}/rpc", "fail_api", [123], timeout=5) + err = excinfo.value + assert not isinstance(err, LsAuthError) + assert err.rpc_code == -32602 + assert err.rpc_message == "Invalid params" + assert err.method == "fail_api" + assert err.http_status == 200 + assert err.raw == {"code": -32602, "message": "Invalid params"} + # method, params and body are in the message → diagnosable + assert "fail_api" in str(err) + assert "123" in str(err) + assert "Invalid params" in str(err) + + +def test_auth_fout_wordt_lsautherror(stub): + with pytest.raises(LsAuthError) as excinfo: + rpc_call(f"{stub.url}/rpc", "fail_auth", ["oude-key"], timeout=5) + err = excinfo.value + assert isinstance(err, LsApiError) # LsAuthError is a subtype + assert err.rpc_message == "Invalid session key" + + +def test_http_foutstatus_wordt_lsconnectionerror_met_body(stub): + with pytest.raises(LsConnectionError) as excinfo: + rpc_call(f"{stub.url}/http500", "echo", [], timeout=5) + err = excinfo.value + assert err.http_status == 500 + assert "500" in str(err) + assert err.body is not None and "Internal Server Error" in err.body + assert err.cause is not None + + +def test_ongeldige_json_wordt_lsconnectionerror(stub): + with pytest.raises(LsConnectionError) as excinfo: + rpc_call(f"{stub.url}/badjson", "echo", [], timeout=5) + assert "no valid JSON" in str(excinfo.value) + assert excinfo.value.http_status == 200 + + +def test_server_onbereikbaar_wordt_lsconnectionerror(): + # find a free port and close it → connect is refused + sock = socket.socket() + sock.bind(("127.0.0.1", 0)) + port = sock.getsockname()[1] + sock.close() + url = f"http://127.0.0.1:{port}/rpc" + with pytest.raises(LsConnectionError) as excinfo: + rpc_call(url, "echo", [], timeout=2) + assert excinfo.value.url == url + assert excinfo.value.cause is not None + assert excinfo.value.http_status is None + + +def test_statistic_veld_wordt_debug_gelogd(stub, caplog): + with caplog.at_level(logging.DEBUG, logger="pylimerpc.rpc"): + result = rpc_call(f"{stub.url}/rpc", "with_statistic", [], timeout=5) + assert result == {"ok": True} + assert any("statistic" in rec.getMessage().lower() and "duration_ms" in rec.getMessage() for rec in caplog.records) + + +def test_endpoint_url(): + assert endpoint_url("https://host.nl/limesurvey") == "https://host.nl/limesurvey/index.php?r=admin/remotecontrol" + assert endpoint_url("https://host.nl/limesurvey/") == "https://host.nl/limesurvey/index.php?r=admin/remotecontrol" + assert endpoint_url("https://host.nl/index.php?r=admin/remotecontrol") == "https://host.nl/index.php?r=admin/remotecontrol" + + +def test_from_config_verify_ssl_false_maakt_ongeverifieerde_context(): + import ssl + + from pylimerpc.config import LsConfig + from pylimerpc.rpc import RpcClient + + cfg = LsConfig( + base_url="https://ls.example.com/index.php?r=admin/remotecontrol", + username="u", + password="p", + verify_ssl=False, + ) + client = RpcClient.from_config(cfg) + assert client.ssl_context is not None + assert client.ssl_context.verify_mode == ssl.CERT_NONE + assert client.ssl_context.check_hostname is False + + # default (verify_ssl=True) → None = urllib's standard verifying context + cfg_ok = LsConfig(base_url="https://ls.example.com/index.php?r=admin/remotecontrol", username="u", password="p") + assert RpcClient.from_config(cfg_ok).ssl_context is None + + +def test_rpc_call_geeft_ssl_context_en_timeout_door_aan_urlopen(monkeypatch, stub): + import ssl + import urllib.request + + captured: dict = {} + + class FakeResp: + status = 200 + + def __enter__(self): + return self + + def __exit__(self, *args): + return False + + def read(self): + return json.dumps({"jsonrpc": "2.0", "id": 1, "result": "ok", "error": None}).encode() + + def fake_urlopen(req, timeout=None, context=None, **kwargs): + captured["timeout"] = timeout + captured["context"] = context + return FakeResp() + + monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen) + ctx = ssl.create_default_context() + assert rpc_call(f"{stub.url}/rpc", "echo", [], timeout=7, ssl_context=ctx) == "ok" + assert captured["timeout"] == 7 + assert captured["context"] is ctx diff --git a/tests/test_session_surveys.py b/tests/test_session_surveys.py new file mode 100644 index 0000000..cd2c26c --- /dev/null +++ b/tests/test_session_surveys.py @@ -0,0 +1,156 @@ +"""Unit tests for session.py, surveys.py and the LsClient context manager (fake RPC, no server).""" + +from __future__ import annotations + +from typing import Any + +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 + + +class FakeRpc: + """Duck-typed replacement for RpcClient: returns pre-set responses.""" + + def __init__(self, *responses: Any) -> None: + self.responses = list(responses) + self.calls: list[tuple[str, list[Any]]] = [] + + def call(self, method: str, params: list[Any]) -> Any: + self.calls.append((method, list(params))) + item = self.responses.pop(0) + if isinstance(item, BaseException): + raise item + return item + + +CFG = LsConfig(base_url="https://ls.example.com/index.php?r=admin/remotecontrol", username="u", password="p") + + +# -- session --------------------------------------------------------------- + + +def test_get_session_key_succes(): + fake = FakeRpc("KEY123") + assert get_session_key(fake, "u", "p") == "KEY123" # type: ignore[arg-type] + assert fake.calls == [("get_session_key", ["u", "p"])] + + +def test_get_session_key_foute_login_is_lsautherror(): + # LS puts {"status": "..."} in result (not in error) on a failed login + fake = FakeRpc({"status": "Invalid user name or password!"}) + with pytest.raises(LsAuthError) as excinfo: + get_session_key(fake, "u", "wrong") # type: ignore[arg-type] + assert "Invalid user name or password!" in str(excinfo.value.rpc_message) + + +def test_release_session_key(): + fake = FakeRpc(True) + assert release_session_key(fake, "KEY123") is True # type: ignore[arg-type] + assert fake.calls == [("release_session_key", ["KEY123"])] + + +# -- surveys --------------------------------------------------------------- + + +def test_list_surveys_succes(): + payload = [{"sid": 1, "active": "Y"}, {"sid": 2, "active": "N"}] + fake = FakeRpc(payload) + out = list_surveys(fake, "KEY") # type: ignore[arg-type] + assert out == payload + assert fake.calls == [("list_surveys", ["KEY"])] + + +def test_list_surveys_met_owner_id_param(): + fake = FakeRpc([]) + list_surveys(fake, "KEY", owner_id=7) # type: ignore[arg-type] + assert fake.calls == [("list_surveys", ["KEY", 7])] + + +def test_list_surveys_status_fout_is_lsautherror(): + fake = FakeRpc({"status": "Invalid session key"}) + with pytest.raises(LsAuthError): + list_surveys(fake, "OLD-KEY") # type: ignore[arg-type] + + +def test_list_surveys_geen_lijst_is_lsapierror(): + fake = FakeRpc(" weird-value ") + with pytest.raises(LsApiError): + list_surveys(fake, "KEY") # type: ignore[arg-type] + + +def test_get_survey_properties_succes_en_sid_coercitie(): + props = {"sid": 123, "surveyls_title": "Test", "active": "Y", "status": "Y"} + fake = FakeRpc(props) + out = get_survey_properties(fake, "KEY", "123") # type: ignore[arg-type] + assert out == props + assert fake.calls == [("get_survey_properties", ["KEY", 123])] + + +def test_get_survey_properties_met_properties_lijst(): + fake = FakeRpc({"sid": 5, "surveyls_title": "X"}) + get_survey_properties(fake, "KEY", 5, properties=["surveyls_title", "active"]) # type: ignore[arg-type] + assert fake.calls == [("get_survey_properties", ["KEY", 5, ["surveyls_title", "active"]])] + + +def test_filter_active(): + surveys = [{"sid": 1, "active": "Y"}, {"sid": 2, "active": "N"}, {"sid": 3, "active": "1"}] + assert [s["sid"] for s in filter_active(surveys)] == [1, 3] + + +# -- LsClient contextmanager ------------------------------------------------ + + +def test_lsclient_opent_en_sluit_sessie(): + fake = FakeRpc("KEY", [{"sid": 1, "active": "Y"}], True) + with LsClient(CFG, rpc=fake) as ls: # type: ignore[arg-type] + assert ls.session_key == "KEY" + surveys = ls.list_surveys() + assert surveys == [{"sid": 1, "active": "Y"}] + assert ls.session_key is None + assert fake.calls == [ + ("get_session_key", ["u", "p"]), + ("list_surveys", ["KEY"]), + ("release_session_key", ["KEY"]), + ] + + +def test_lsclient_sluit_sessie_ook_bij_exceptie(): + fake = FakeRpc("KEY", LsConnectionError("boom"), True) + with pytest.raises(LsConnectionError): + with LsClient(CFG, rpc=fake) as ls: # type: ignore[arg-type] + ls.list_surveys() + assert ls.session_key is None + assert fake.calls[-1] == ("release_session_key", ["KEY"]) + + +def test_lsclient_release_falen_gooit_niets(): + fake = FakeRpc("KEY", LsConnectionError("release stuk")) + with LsClient(CFG, rpc=fake): # type: ignore[arg-type] + pass + # no exception escapes; session is cleaned up + assert fake.calls == [("get_session_key", ["u", "p"]), ("release_session_key", ["KEY"])] + + +def test_lsclient_zonder_sessie_gooit_lserror(): + ls = LsClient(CFG, rpc=FakeRpc()) # type: ignore[arg-type] + with pytest.raises(LsError): + ls.list_surveys() + + +def test_lsclient_list_surveysGebruikt_config_owner_group(): + cfg = LsConfig( + base_url="https://ls.example.com/index.php?r=admin/remotecontrol", + username="u", + password="p", + owner_id=9, + group_id=3, + ) + fake = FakeRpc("KEY", [{"sid": 1, "group_id": 3}, {"sid": 2, "group_id": 4}], True) + with LsClient(cfg, rpc=fake) as ls: # type: ignore[arg-type] + out = ls.list_surveys() + assert fake.calls[1] == ("list_surveys", ["KEY", 9]) + assert [s["sid"] for s in out] == [1] # group_id=3 filtered diff --git a/tests/test_utils.py b/tests/test_utils.py new file mode 100644 index 0000000..226776b --- /dev/null +++ b/tests/test_utils.py @@ -0,0 +1,99 @@ +"""Unit tests for pylimerpc.utils (pytest).""" + +from __future__ import annotations + +import base64 +import json + +import pytest + +from pylimerpc.errors import LsApiError, LsAuthError +from pylimerpc.utils import ( + decode_export_json, + is_active_flag, + is_filled, + normalize_sid, + parse_responses_json, + raise_for_status, + summary_counts, + to_int, +) + + +def test_to_int(): + assert to_int("42") == 42 + assert to_int(7) == 7 + assert to_int("") is None + assert to_int(None) is None + assert to_int("abc") is None + + +def test_is_active_flag(): + assert is_active_flag("Y") is True + assert is_active_flag("1") is True + assert is_active_flag("true") is True + assert is_active_flag("N") is False + assert is_active_flag(None) is False + + +def test_is_filled(): + assert is_filled("x") is True + assert is_filled("") is False + assert is_filled(" ") is False + assert is_filled(None) is False + assert is_filled("[]") is False + assert is_filled("[]x") is True + + +def test_normalize_sid(): + assert normalize_sid("123") == 123 + assert normalize_sid(5) == 5 + assert normalize_sid("abc") == "abc" + + +def test_parse_responses_json_varianten(): + assert parse_responses_json('{"responses": [{"id": "1"}]}') == [{"id": "1"}] + assert parse_responses_json('[{"id": "2"}]') == [{"id": "2"}] + assert parse_responses_json('{"id": "3"}') == [{"id": "3"}] + + +def test_decode_export_json_base64(): + payload = json.dumps({"responses": [{"id": "1", "Q1": "a"}]}).encode("utf-8") + b64 = base64.b64encode(payload).decode("ascii") + assert decode_export_json(b64) == [{"id": "1", "Q1": "a"}] + assert decode_export_json("") == [] + assert decode_export_json(None) == [] + + +def test_summary_counts_key_varianten(): + assert summary_counts({"completed_responses": "3", "responses": "10"}) == (3, 10) + assert summary_counts({"completed": 1, "full_responses": 5}) == (1, 5) + assert summary_counts({}) == (None, None) + + +def test_raise_for_status_auth(): + with pytest.raises(LsAuthError): + raise_for_status({"status": "Invalid session key"}, "list_surveys") + + +def test_raise_for_status_api(): + with pytest.raises(LsApiError) as excinfo: + raise_for_status({"status": "Survey not found"}, "get_survey_properties") + assert not isinstance(excinfo.value, LsAuthError) + + +def test_raise_for_status_met_error_code(): + # LS returns e.g. {"status": "Error: No survey participant list", "error_code": "ERR_NO_PARTICIPANT_TABLE"} + with pytest.raises(LsApiError) as excinfo: + raise_for_status( + {"status": "Error: No survey participant list", "error_code": "ERR_NO_PARTICIPANT_TABLE"}, + "list_participants", + ) + assert not isinstance(excinfo.value, LsAuthError) + assert "No survey participant list" in str(excinfo.value.rpc_message) + + +def test_raise_for_status_passthrough(): + props = {"sid": 1, "status": "Y", "surveyls_title": "X"} # status-key tussen andere keys = géén fout + assert raise_for_status(props, "get_survey_properties") == props + assert raise_for_status([{"sid": 1}], "list_surveys") == [{"sid": 1}]