- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- 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> |
||
| examples | ||
| pylimerpc | ||
| tests | ||
| .env.example | ||
| .gitignore | ||
| pyproject.toml | ||
| README.md | ||
| test.py | ||
PyLimeRPC
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).
- 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:
- Python >= 3.10 on a Linux machine.
- A LimeSurvey 7 installation with the RemoteControl (JSON-RPC) API enabled —
the endpoint
https://<your-limesurvey-host>/index.php?r=admin/remotecontrolmust be reachable over HTTPS. - A RemoteControl user account (username + password) with permissions for the surveys you want to access.
- A filled-in
.envfile (copy.env.example):LIMESURVEY_BASE_URL,LIMESURVEY_USERNAME,LIMESURVEY_PASSWORD; optionallyLIMESURVEY_TIMEOUT_SECONDS,LIMESURVEY_OWNER_ID,LIMESURVEY_GROUP_ID,LIMESURVEY_VERIFY_SSL. - Network access from your machine to the LimeSurvey host, with a valid TLS
certificate (set
LIMESURVEY_VERIFY_SSL=falseonly for a local test instance with a wrong/self-signed certificate — never in production). - To run the tests:
pip install -e ".[dev]"(adds pytest as a dev extra).
Install (editable)
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
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).
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:
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:
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):
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
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.