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:
parent
30fc89e4e2
commit
d7d9dc61bf
27 changed files with 2853 additions and 14 deletions
|
|
@ -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
|
||||
|
|
|
|||
17
.gitignore
vendored
17
.gitignore
vendored
|
|
@ -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/
|
||||
|
|
|
|||
163
README.md
163
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://<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
21
examples/README.md
Normal 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
4
examples/__init__.py
Normal 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
103
examples/example_asgi.py
Normal 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
106
examples/example_cli.py
Normal 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())
|
||||
60
examples/example_cron_export.py
Normal file
60
examples/example_cron_export.py
Normal 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
187
pylimerpc/__init__.py
Normal 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
218
pylimerpc/config.py
Normal 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
85
pylimerpc/errors.py
Normal 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
154
pylimerpc/responses.py
Normal 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
250
pylimerpc/rpc.py
Normal 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
48
pylimerpc/session.py
Normal 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
101
pylimerpc/surveys.py
Normal 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
113
pylimerpc/tokens.py
Normal 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
132
pylimerpc/utils.py
Normal 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
35
pyproject.toml
Normal 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
5
tests/__init__.py
Normal 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
175
tests/test_config.py
Normal 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
Loading…
Reference in a new issue