#!/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())