276 lines
8 KiB
Python
276 lines
8 KiB
Python
|
|
#!/usr/bin/env python3
|
||
|
|
"""LimeSurvey helper script.
|
||
|
|
|
||
|
|
What it does:
|
||
|
|
1. Reads credentials/config from .env
|
||
|
|
2. Gets a LimeSurvey session key
|
||
|
|
3. Lists active surveys and their response counts
|
||
|
|
4. Shows surveys with at least N responses
|
||
|
|
5. Lets you choose a survey (or use --survey-id)
|
||
|
|
6. Shows a compact preview of responses
|
||
|
|
7. Exports all responses to CSV in output/
|
||
|
|
"""
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
import argparse
|
||
|
|
import base64
|
||
|
|
import json
|
||
|
|
import os
|
||
|
|
import sys
|
||
|
|
import urllib.request
|
||
|
|
from pathlib import Path
|
||
|
|
from typing import Any
|
||
|
|
|
||
|
|
|
||
|
|
def load_dotenv(path: Path) -> None:
|
||
|
|
if not path.exists():
|
||
|
|
return
|
||
|
|
for line in path.read_text(encoding="utf-8").splitlines():
|
||
|
|
line = line.strip()
|
||
|
|
if not line or line.startswith("#") or "=" not in line:
|
||
|
|
continue
|
||
|
|
key, value = line.split("=", 1)
|
||
|
|
os.environ.setdefault(key.strip(), value.strip())
|
||
|
|
|
||
|
|
|
||
|
|
def to_int(value: Any) -> int | None:
|
||
|
|
try:
|
||
|
|
if value is None:
|
||
|
|
return None
|
||
|
|
return int(str(value).strip())
|
||
|
|
except Exception:
|
||
|
|
return None
|
||
|
|
|
||
|
|
|
||
|
|
class LimeSurveyClient:
|
||
|
|
def __init__(self, base_url: str, timeout: int = 30) -> None:
|
||
|
|
self.base_url = base_url
|
||
|
|
self.timeout = timeout
|
||
|
|
self._req_id = 1
|
||
|
|
|
||
|
|
def rpc(self, method: str, params: list[Any]) -> Any:
|
||
|
|
payload = {"method": method, "params": params, "id": self._req_id}
|
||
|
|
self._req_id += 1
|
||
|
|
req = urllib.request.Request(
|
||
|
|
self.base_url,
|
||
|
|
data=json.dumps(payload).encode("utf-8"),
|
||
|
|
headers={"Content-Type": "application/json"},
|
||
|
|
)
|
||
|
|
with urllib.request.urlopen(req, timeout=self.timeout) as response:
|
||
|
|
out = json.loads(response.read().decode("utf-8"))
|
||
|
|
|
||
|
|
if out.get("error"):
|
||
|
|
raise RuntimeError(f"{method} failed: {out['error']}")
|
||
|
|
return out.get("result")
|
||
|
|
|
||
|
|
|
||
|
|
def summary_counts(summary: dict[str, Any]) -> tuple[int | None, int | None]:
|
||
|
|
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_active_flag(value: Any) -> bool:
|
||
|
|
return str(value).strip().upper() in {"Y", "1", "TRUE"}
|
||
|
|
|
||
|
|
|
||
|
|
def decode_export_json(result: Any) -> list[dict[str, Any]]:
|
||
|
|
if not isinstance(result, str) or not result:
|
||
|
|
return []
|
||
|
|
decoded = base64.b64decode(result)
|
||
|
|
parsed = json.loads(decoded.decode("utf-8"))
|
||
|
|
|
||
|
|
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 is_filled(value: Any) -> bool:
|
||
|
|
if value is None:
|
||
|
|
return False
|
||
|
|
if isinstance(value, str) and value.strip() == "":
|
||
|
|
return False
|
||
|
|
if value == "[]":
|
||
|
|
return False
|
||
|
|
return True
|
||
|
|
|
||
|
|
|
||
|
|
def choose_survey(surveys: list[dict[str, Any]], preselected_sid: str | None) -> dict[str, Any]:
|
||
|
|
if preselected_sid:
|
||
|
|
for survey in surveys:
|
||
|
|
if survey["sid"] == preselected_sid:
|
||
|
|
return survey
|
||
|
|
raise ValueError(f"Survey ID not found in active list: {preselected_sid}")
|
||
|
|
|
||
|
|
while True:
|
||
|
|
selected = input("Choose survey ID (sid): ").strip()
|
||
|
|
for survey in surveys:
|
||
|
|
if survey["sid"] == selected:
|
||
|
|
return survey
|
||
|
|
print("Invalid sid. Please choose one from the list above.")
|
||
|
|
|
||
|
|
|
||
|
|
def main() -> int:
|
||
|
|
parser = argparse.ArgumentParser(description="LimeSurvey active survey and response exporter")
|
||
|
|
parser.add_argument("--env-file", default=".env", help="Path to .env file")
|
||
|
|
parser.add_argument("--survey-id", default=None, help="Select survey sid without prompt")
|
||
|
|
parser.add_argument("--min-responses", type=int, default=2, help="Minimum total responses to highlight")
|
||
|
|
parser.add_argument("--show", type=int, default=20, help="How many response previews to print")
|
||
|
|
parser.add_argument("--output-dir", default="output", help="Directory for CSV export")
|
||
|
|
args = parser.parse_args()
|
||
|
|
|
||
|
|
load_dotenv(Path(args.env_file))
|
||
|
|
|
||
|
|
base_url = os.environ.get("LIMESURVEY_BASE_URL", "").strip()
|
||
|
|
username = os.environ.get("LIMESURVEY_USERNAME", "").strip()
|
||
|
|
password = os.environ.get("LIMESURVEY_PASSWORD", "").strip()
|
||
|
|
timeout = to_int(os.environ.get("LIMESURVEY_TIMEOUT_SECONDS", "30")) or 30
|
||
|
|
|
||
|
|
if not base_url or not username or not password:
|
||
|
|
print(
|
||
|
|
"Missing required env vars: LIMESURVEY_BASE_URL, LIMESURVEY_USERNAME, LIMESURVEY_PASSWORD",
|
||
|
|
file=sys.stderr,
|
||
|
|
)
|
||
|
|
return 1
|
||
|
|
|
||
|
|
client = LimeSurveyClient(base_url=base_url, timeout=timeout)
|
||
|
|
session_key = None
|
||
|
|
|
||
|
|
try:
|
||
|
|
session_key = client.rpc("get_session_key", [username, password])
|
||
|
|
if not session_key or isinstance(session_key, dict):
|
||
|
|
print(f"Failed to get session key: {session_key!r}", file=sys.stderr)
|
||
|
|
return 1
|
||
|
|
print("Session key acquired.")
|
||
|
|
|
||
|
|
raw_surveys = client.rpc("list_surveys", [session_key])
|
||
|
|
if not isinstance(raw_surveys, list):
|
||
|
|
print(f"Unexpected list_surveys payload: {raw_surveys!r}", file=sys.stderr)
|
||
|
|
return 1
|
||
|
|
|
||
|
|
active_surveys: list[dict[str, Any]] = []
|
||
|
|
for item in raw_surveys:
|
||
|
|
if not isinstance(item, dict):
|
||
|
|
continue
|
||
|
|
if not is_active_flag(item.get("active")):
|
||
|
|
continue
|
||
|
|
|
||
|
|
sid = str(item.get("sid") or item.get("survey_id") or "").strip()
|
||
|
|
if not sid:
|
||
|
|
continue
|
||
|
|
|
||
|
|
title = str(item.get("surveyls_title") or item.get("title") or "(no title)")
|
||
|
|
summary = client.rpc("get_summary", [session_key, sid])
|
||
|
|
if not isinstance(summary, dict):
|
||
|
|
summary = {}
|
||
|
|
completed_responses, total_responses = summary_counts(summary)
|
||
|
|
|
||
|
|
active_surveys.append(
|
||
|
|
{
|
||
|
|
"sid": sid,
|
||
|
|
"title": title,
|
||
|
|
"completed_responses": completed_responses,
|
||
|
|
"total_responses": total_responses,
|
||
|
|
}
|
||
|
|
)
|
||
|
|
|
||
|
|
if not active_surveys:
|
||
|
|
print("No active surveys found.")
|
||
|
|
return 0
|
||
|
|
|
||
|
|
print("\nActive surveys:")
|
||
|
|
for survey in active_surveys:
|
||
|
|
print(
|
||
|
|
f"- sid={survey['sid']} | title={survey['title']} | "
|
||
|
|
f"completed={survey['completed_responses']} | total={survey['total_responses']}"
|
||
|
|
)
|
||
|
|
|
||
|
|
eligible = [
|
||
|
|
s for s in active_surveys if (s.get("total_responses") is not None and s["total_responses"] >= args.min_responses)
|
||
|
|
]
|
||
|
|
|
||
|
|
print(f"\nSurveys with {args.min_responses}+ responses:")
|
||
|
|
if not eligible:
|
||
|
|
print("- None")
|
||
|
|
return 0
|
||
|
|
for survey in eligible:
|
||
|
|
print(f"- sid={survey['sid']} | title={survey['title']} | total={survey['total_responses']}")
|
||
|
|
|
||
|
|
chosen = choose_survey(eligible, args.survey_id)
|
||
|
|
chosen_sid = chosen["sid"]
|
||
|
|
print(f"\nSelected survey sid={chosen_sid} title={chosen['title']}")
|
||
|
|
|
||
|
|
exported_json = client.rpc(
|
||
|
|
"export_responses",
|
||
|
|
[session_key, chosen_sid, "json", None, "all", "code", "short"],
|
||
|
|
)
|
||
|
|
responses = decode_export_json(exported_json)
|
||
|
|
print(f"Total responses fetched: {len(responses)}")
|
||
|
|
|
||
|
|
meta_keys = {"id", "submitdate", "lastpage", "startlanguage", "seed", "startdate", "datestamp"}
|
||
|
|
shown = 0
|
||
|
|
for row in responses:
|
||
|
|
if not isinstance(row, dict):
|
||
|
|
continue
|
||
|
|
|
||
|
|
filled = [(k, v) for k, v in row.items() if k not in meta_keys and is_filled(v)]
|
||
|
|
if not filled:
|
||
|
|
continue
|
||
|
|
|
||
|
|
shown += 1
|
||
|
|
print(
|
||
|
|
f"RESPONSE id={row.get('id')} submitdate={row.get('submitdate')} "
|
||
|
|
f"startdate={row.get('startdate')} lastpage={row.get('lastpage')} "
|
||
|
|
f"filled_answers={len(filled)}"
|
||
|
|
)
|
||
|
|
sample = {k: v for k, v in filled[:8]}
|
||
|
|
print(" sample_answers=" + json.dumps(sample, ensure_ascii=False))
|
||
|
|
|
||
|
|
if shown >= args.show:
|
||
|
|
break
|
||
|
|
|
||
|
|
print(f"Previewed responses: {shown}")
|
||
|
|
|
||
|
|
exported_csv = client.rpc(
|
||
|
|
"export_responses",
|
||
|
|
[session_key, chosen_sid, "csv", None, "all", "code", "short"],
|
||
|
|
)
|
||
|
|
if not isinstance(exported_csv, str) or not exported_csv:
|
||
|
|
print("CSV export failed: empty payload", file=sys.stderr)
|
||
|
|
return 1
|
||
|
|
|
||
|
|
csv_bytes = base64.b64decode(exported_csv)
|
||
|
|
output_dir = Path(args.output_dir)
|
||
|
|
output_dir.mkdir(parents=True, exist_ok=True)
|
||
|
|
output_path = output_dir / f"survey_{chosen_sid}_responses.csv"
|
||
|
|
output_path.write_bytes(csv_bytes)
|
||
|
|
print(f"CSV exported to: {output_path}")
|
||
|
|
print(f"CSV size (bytes): {output_path.stat().st_size}")
|
||
|
|
|
||
|
|
return 0
|
||
|
|
finally:
|
||
|
|
if session_key and not isinstance(session_key, dict):
|
||
|
|
try:
|
||
|
|
client.rpc("release_session_key", [session_key])
|
||
|
|
except Exception:
|
||
|
|
pass
|
||
|
|
|
||
|
|
|
||
|
|
if __name__ == "__main__":
|
||
|
|
raise SystemExit(main())
|