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
1 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__",
|
||||
]
|
||||
Loading…
Reference in a new issue