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
9 changed files with 2853 additions and 14 deletions
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
|
||||
Loading…
Reference in a new issue