PyLimeRPC: package pylimerpc + pyproject + tests/examples (overname van minimalLS)

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

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
Tammo ter Hark 2026-11-19 12:26:35 +01:00
commit d7d9dc61bf
27 changed files with 2853 additions and 14 deletions

View file

@ -10,3 +10,8 @@ LIMESURVEY_GROUP_ID=
# API settings # API settings
LIMESURVEY_TIMEOUT_SECONDS=30 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

17
.gitignore vendored
View file

@ -14,5 +14,20 @@ venv/
# IDE # IDE
.vscode/ .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/ 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/

163
README.md
View file

@ -1,13 +1,154 @@
This is a minimal script to test the availability of a LimeSurvey backend. # PyLimeRPC
Tested up to version 7.0.14.
# The script does this: **PyLimeRPC** (import package: `pylimerpc`) is a reusable Python library for
* ask a session key interacting with **LimeSurvey** via the RemoteControl JSON-RPC API (LS7,
* get list of active surveys endpoint `index.php?r=admin/remotecontrol`).
* lets you choose a survey that has responses
* gets the responses
* write a CVS with the responses to the output directory
# Instructions - Python standard library only — no runtime dependencies.
* Copy .env.example to .env and edit .env to enter the details to your LimeSurvey installation. - Usable from cron/URL-triggered data tasks, CLI admin tools and web
* Run test.py 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://<your-limesurvey-host>/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.

21
examples/README.md Normal file
View file

@ -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.

4
examples/__init__.py Normal file
View file

@ -0,0 +1,4 @@
"""Example scripts that use the pylimerpc library.
See examples/README.md. Each script runs directly from the repo.
"""

103
examples/example_asgi.py Normal file
View file

@ -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(
"<tr>"
f"<td>{html.escape(str(s.get('sid', '')))}</td>"
f"<td>{html.escape(str(s.get('surveyls_title', '')))}</td>"
"</tr>"
for s in surveys
)
page = (
"<!doctype html><html><head><meta charset='utf-8'>"
"<title>LimeSurvey — active surveys</title></head><body>"
"<h1>Active surveys</h1>"
"<table border='1' cellpadding='4'><tr><th>sid</th><th>title</th></tr>"
f"{rows}</table></body></html>"
)
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)

106
examples/example_cli.py Normal file
View file

@ -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())

View file

@ -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())

187
pylimerpc/__init__.py Normal file
View file

@ -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__",
]

218
pylimerpc/config.py Normal file
View file

@ -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,
)

85
pylimerpc/errors.py Normal file
View file

@ -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."""

154
pylimerpc/responses.py Normal file
View file

@ -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_<sid>_responses.<ext>`` is used).
"""
from __future__ import annotations
import base64
import binascii
from pathlib import Path
from typing import Any
from .errors import LsApiError
from .rpc import RpcClient
from .utils import normalize_sid, parse_responses_json, raise_for_status
def _decode_base64(result: Any, method: str) -> bytes:
"""Decode the base64 result of an export RPC; raise LsApiError on empty/invalid data."""
if not isinstance(result, str) or not result:
raise LsApiError(
f"{method} did not return a base64 string: {result!r}",
method=method,
raw=result,
)
try:
return base64.b64decode(result)
except (binascii.Error, ValueError) as exc:
raise LsApiError(
f"{method} did not return valid base64: {exc}",
method=method,
raw=str(result)[:200],
) from exc
def _ext(doc_type: str) -> str:
return doc_type if doc_type.isalnum() else "bin"
def _write_output(data: bytes, output_path: str | Path, default_name: str) -> Path:
path = Path(output_path)
if path.is_dir():
path = path / default_name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(data)
return path
def export_responses(
client: RpcClient,
session_key: str,
sid: int | str,
doc_type: str = "json",
*,
language: str | None = None,
completion_status: str = "all",
field_map: str = "code",
header: str = "short",
output_path: str | Path | None = None,
) -> bytes | Path:
"""Export the responses of a survey.
LS7 RPC method: ``export_responses`` with params
``[session_key, sid, doc_type, language, completion_status, field_map, header]``.
Args:
client: an ``RpcClient``.
session_key: a valid session key.
sid: survey ID.
doc_type: ``"json"``, ``"csv"``, ``"xls"``/``"xlsx"``, ``"spss"``, ...
language: language code or None (default language).
completion_status: ``"all"``, ``"complete"`` or ``"incomplete"``.
field_map: ``"code"`` or ``"title"`` (question coding in the export).
header: ``"short"`` or ``"full"``.
output_path: optional file path (or directory) to save the export to.
Returns:
The decoded export as ``bytes``; with ``output_path``, the ``Path`` of the file.
"""
params: list[Any] = [
session_key,
normalize_sid(sid),
doc_type,
language,
completion_status,
field_map,
header,
]
result = client.call("export_responses", params)
raise_for_status(result, "export_responses")
data = _decode_base64(result, "export_responses")
if output_path is not None:
return _write_output(data, output_path, f"survey_{sid}_responses.{_ext(doc_type)}")
return data
def export_responses_json(
client: RpcClient,
session_key: str,
sid: int | str,
**kwargs: Any,
) -> list[dict[str, Any]]:
"""Convenience wrapper: ``export_responses(doc_type="json")`` as ``list[dict]``.
Accepts the same kwargs as ``export_responses`` (except ``doc_type``).
"""
kwargs.pop("doc_type", None)
data = export_responses(client, session_key, sid, "json", **kwargs)
if isinstance(data, Path):
data = data.read_bytes()
return parse_responses_json(data.decode("utf-8"))
def export_statistics(
client: RpcClient,
session_key: str,
sid: int | str,
doc_type: str = "json",
*,
language: str | None = None,
output_path: str | Path | None = None,
) -> bytes | Path:
"""Export the statistics of a survey.
LS7 RPC method: ``export_statistics`` with params
``[session_key, sid, doc_type, language]``.
Args:
client: an ``RpcClient``.
session_key: a valid session key.
sid: survey ID.
doc_type: ``"json"`` or ``"csv"``.
language: language code or None.
output_path: optional file path (or directory) to save the export to.
Returns:
The decoded export as ``bytes``; with ``output_path``, the ``Path`` of the file.
"""
params: list[Any] = [session_key, normalize_sid(sid), doc_type, language]
result = client.call("export_statistics", params)
raise_for_status(result, "export_statistics")
data = _decode_base64(result, "export_statistics")
if output_path is not None:
return _write_output(data, output_path, f"survey_{sid}_statistics.{_ext(doc_type)}")
return data

250
pylimerpc/rpc.py Normal file
View file

@ -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)

48
pylimerpc/session.py Normal file
View file

@ -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])

101
pylimerpc/surveys.py Normal file
View file

@ -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"))]

113
pylimerpc/tokens.py Normal file
View file

@ -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

132
pylimerpc/utils.py Normal file
View file

@ -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

35
pyproject.toml Normal file
View file

@ -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'"

5
tests/__init__.py Normal file
View file

@ -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.
"""

175
tests/test_config.py Normal file
View file

@ -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

Some files were not shown because too many files have changed in this diff Show more