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
9 changed files with 2853 additions and 14 deletions

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