askrobots / dbbasic-forms
Public
A form builder that keeps forms and responses in TSV files: git-friendly, no database, CSV export.
forms.py · 10.6 KB · 374 lines
| 1 | """ |
| 2 | Form builder and response handler for dbbasic-forms |
| 3 | """ |
| 4 | |
| 5 | import json |
| 6 | from datetime import datetime |
| 7 | from pathlib import Path |
| 8 | from typing import Any, Dict, List, Optional |
| 9 | from dbbasic.tsv import TSV |
| 10 | |
| 11 | |
| 12 | class FormBuilder: |
| 13 | """Build and manage forms with TSV storage""" |
| 14 | |
| 15 | def __init__(self, data_dir: str = "data"): |
| 16 | """Initialize form builder |
| 17 | |
| 18 | Args: |
| 19 | data_dir: Directory to store form definitions and responses |
| 20 | """ |
| 21 | self.data_dir = Path(data_dir) |
| 22 | self.data_dir.mkdir(exist_ok=True) |
| 23 | |
| 24 | # Initialize TSV tables |
| 25 | self.forms = TSV( |
| 26 | "forms", |
| 27 | ["id", "name", "description", "fields", "settings", "created_at", "updated_at"], |
| 28 | data_dir=self.data_dir, |
| 29 | indexes=["id"], |
| 30 | ) |
| 31 | |
| 32 | def create_form( |
| 33 | self, |
| 34 | form_id: str, |
| 35 | name: str, |
| 36 | description: str = "", |
| 37 | fields: Optional[List[Dict[str, Any]]] = None, |
| 38 | settings: Optional[Dict[str, Any]] = None, |
| 39 | ) -> "Form": |
| 40 | """Create a new form |
| 41 | |
| 42 | Args: |
| 43 | form_id: Unique identifier for the form |
| 44 | name: Form name |
| 45 | description: Form description |
| 46 | fields: List of field definitions |
| 47 | settings: Form settings (success message, button text, etc.) |
| 48 | |
| 49 | Returns: |
| 50 | Form instance |
| 51 | """ |
| 52 | if fields is None: |
| 53 | fields = [] |
| 54 | if settings is None: |
| 55 | settings = { |
| 56 | "success_message": "Thanks! We'll get back to you soon.", |
| 57 | "button_text": "Submit", |
| 58 | } |
| 59 | |
| 60 | now = datetime.utcnow().isoformat() |
| 61 | |
| 62 | self.forms.insert( |
| 63 | { |
| 64 | "id": form_id, |
| 65 | "name": name, |
| 66 | "description": description, |
| 67 | "fields": json.dumps(fields), |
| 68 | "settings": json.dumps(settings), |
| 69 | "created_at": now, |
| 70 | "updated_at": now, |
| 71 | } |
| 72 | ) |
| 73 | |
| 74 | return Form(form_id, self.data_dir) |
| 75 | |
| 76 | def get_form(self, form_id: str) -> Optional["Form"]: |
| 77 | """Get a form by ID |
| 78 | |
| 79 | Args: |
| 80 | form_id: Form identifier |
| 81 | |
| 82 | Returns: |
| 83 | Form instance or None if not found |
| 84 | """ |
| 85 | form_data = self.forms.query_one(id=form_id) |
| 86 | if not form_data: |
| 87 | return None |
| 88 | return Form(form_id, self.data_dir) |
| 89 | |
| 90 | def list_forms(self) -> List[Dict[str, Any]]: |
| 91 | """List all forms |
| 92 | |
| 93 | Returns: |
| 94 | List of form data dictionaries |
| 95 | """ |
| 96 | forms = [] |
| 97 | for form_data in self.forms.all(): |
| 98 | # Get response count |
| 99 | form = Form(form_data["id"], self.data_dir) |
| 100 | response_count = form.count_responses() |
| 101 | |
| 102 | forms.append( |
| 103 | { |
| 104 | "id": form_data["id"], |
| 105 | "name": form_data["name"], |
| 106 | "description": form_data["description"], |
| 107 | "created_at": form_data["created_at"], |
| 108 | "response_count": response_count, |
| 109 | } |
| 110 | ) |
| 111 | return forms |
| 112 | |
| 113 | def delete_form(self, form_id: str) -> bool: |
| 114 | """Delete a form and all its responses |
| 115 | |
| 116 | Args: |
| 117 | form_id: Form identifier |
| 118 | |
| 119 | Returns: |
| 120 | True if deleted, False if not found |
| 121 | """ |
| 122 | # Delete responses first |
| 123 | form = self.get_form(form_id) |
| 124 | if form: |
| 125 | form._delete_responses_table() |
| 126 | |
| 127 | # Delete form |
| 128 | deleted = self.forms.delete(id=form_id) |
| 129 | return deleted > 0 |
| 130 | |
| 131 | |
| 132 | class Form: |
| 133 | """Individual form with response handling""" |
| 134 | |
| 135 | def __init__(self, form_id: str, data_dir: Path = Path("data")): |
| 136 | """Initialize form |
| 137 | |
| 138 | Args: |
| 139 | form_id: Form identifier |
| 140 | data_dir: Data directory path |
| 141 | """ |
| 142 | self.form_id = form_id |
| 143 | self.data_dir = Path(data_dir) |
| 144 | |
| 145 | # Load form data |
| 146 | forms_table = TSV("forms", data_dir=self.data_dir, indexes=["id"]) |
| 147 | self.form_data = forms_table.query_one(id=form_id) |
| 148 | |
| 149 | if not self.form_data: |
| 150 | raise ValueError(f"Form '{form_id}' not found") |
| 151 | |
| 152 | # Parse JSON fields |
| 153 | self.fields = json.loads(self.form_data["fields"]) |
| 154 | self.settings = json.loads(self.form_data["settings"]) |
| 155 | |
| 156 | # Initialize responses table |
| 157 | self._init_responses_table() |
| 158 | |
| 159 | def _init_responses_table(self): |
| 160 | """Initialize the responses TSV table""" |
| 161 | # Extract field names from form definition |
| 162 | field_names = [field["name"] for field in self.fields] |
| 163 | |
| 164 | # Standard columns plus dynamic fields |
| 165 | columns = ["id", "submitted_at"] + field_names + ["metadata"] |
| 166 | |
| 167 | self.responses = TSV( |
| 168 | f"responses_{self.form_id}", |
| 169 | columns, |
| 170 | data_dir=self.data_dir, |
| 171 | indexes=["id"], |
| 172 | ) |
| 173 | |
| 174 | def _delete_responses_table(self): |
| 175 | """Delete the responses table file""" |
| 176 | tsv_file = self.data_dir / f"responses_{self.form_id}.tsv" |
| 177 | if tsv_file.exists(): |
| 178 | tsv_file.unlink() |
| 179 | |
| 180 | def submit_response(self, response_data: Dict[str, Any]) -> str: |
| 181 | """Submit a response to this form |
| 182 | |
| 183 | Args: |
| 184 | response_data: Dictionary of field names to values |
| 185 | |
| 186 | Returns: |
| 187 | Response ID |
| 188 | """ |
| 189 | # Generate response ID |
| 190 | response_id = f"resp_{datetime.utcnow().strftime('%Y%m%d%H%M%S%f')}" |
| 191 | |
| 192 | # Prepare record |
| 193 | record = { |
| 194 | "id": response_id, |
| 195 | "submitted_at": datetime.utcnow().isoformat(), |
| 196 | } |
| 197 | |
| 198 | # Add field values |
| 199 | for field in self.fields: |
| 200 | field_name = field["name"] |
| 201 | value = response_data.get(field_name, "") |
| 202 | |
| 203 | # Convert lists to JSON for multi-select fields |
| 204 | if isinstance(value, list): |
| 205 | value = json.dumps(value) |
| 206 | |
| 207 | record[field_name] = str(value) |
| 208 | |
| 209 | # Add metadata (IP, user agent, etc.) |
| 210 | metadata = response_data.get("_metadata", {}) |
| 211 | record["metadata"] = json.dumps(metadata) |
| 212 | |
| 213 | # Insert response |
| 214 | self.responses.insert(record) |
| 215 | |
| 216 | return response_id |
| 217 | |
| 218 | def get_responses( |
| 219 | self, limit: Optional[int] = None, offset: int = 0 |
| 220 | ) -> List[Dict[str, Any]]: |
| 221 | """Get form responses |
| 222 | |
| 223 | Args: |
| 224 | limit: Maximum number of responses to return |
| 225 | offset: Number of responses to skip |
| 226 | |
| 227 | Returns: |
| 228 | List of response dictionaries |
| 229 | """ |
| 230 | responses = list(self.responses.all()) |
| 231 | |
| 232 | # Sort by submitted_at descending |
| 233 | responses.sort(key=lambda x: x["submitted_at"], reverse=True) |
| 234 | |
| 235 | # Apply pagination |
| 236 | if offset: |
| 237 | responses = responses[offset:] |
| 238 | if limit: |
| 239 | responses = responses[:limit] |
| 240 | |
| 241 | # Parse JSON fields |
| 242 | for response in responses: |
| 243 | if "metadata" in response: |
| 244 | try: |
| 245 | response["metadata"] = json.loads(response["metadata"]) |
| 246 | except (json.JSONDecodeError, TypeError): |
| 247 | response["metadata"] = {} |
| 248 | |
| 249 | return responses |
| 250 | |
| 251 | def count_responses(self) -> int: |
| 252 | """Count total responses |
| 253 | |
| 254 | Returns: |
| 255 | Number of responses |
| 256 | """ |
| 257 | return self.responses.count() |
| 258 | |
| 259 | def get_response(self, response_id: str) -> Optional[Dict[str, Any]]: |
| 260 | """Get a single response by ID |
| 261 | |
| 262 | Args: |
| 263 | response_id: Response identifier |
| 264 | |
| 265 | Returns: |
| 266 | Response dictionary or None |
| 267 | """ |
| 268 | response = self.responses.query_one(id=response_id) |
| 269 | if response and "metadata" in response: |
| 270 | try: |
| 271 | response["metadata"] = json.loads(response["metadata"]) |
| 272 | except (json.JSONDecodeError, TypeError): |
| 273 | response["metadata"] = {} |
| 274 | return response |
| 275 | |
| 276 | def delete_response(self, response_id: str) -> bool: |
| 277 | """Delete a response |
| 278 | |
| 279 | Args: |
| 280 | response_id: Response identifier |
| 281 | |
| 282 | Returns: |
| 283 | True if deleted, False if not found |
| 284 | """ |
| 285 | deleted = self.responses.delete(id=response_id) |
| 286 | return deleted > 0 |
| 287 | |
| 288 | def update_form( |
| 289 | self, |
| 290 | name: Optional[str] = None, |
| 291 | description: Optional[str] = None, |
| 292 | fields: Optional[List[Dict[str, Any]]] = None, |
| 293 | settings: Optional[Dict[str, Any]]] = None, |
| 294 | ) -> bool: |
| 295 | """Update form configuration |
| 296 | |
| 297 | Args: |
| 298 | name: New form name |
| 299 | description: New description |
| 300 | fields: New fields definition |
| 301 | settings: New settings |
| 302 | |
| 303 | Returns: |
| 304 | True if updated |
| 305 | """ |
| 306 | forms_table = TSV("forms", data_dir=self.data_dir, indexes=["id"]) |
| 307 | |
| 308 | updates = {"updated_at": datetime.utcnow().isoformat()} |
| 309 | |
| 310 | if name is not None: |
| 311 | updates["name"] = name |
| 312 | self.form_data["name"] = name |
| 313 | |
| 314 | if description is not None: |
| 315 | updates["description"] = description |
| 316 | self.form_data["description"] = description |
| 317 | |
| 318 | if fields is not None: |
| 319 | updates["fields"] = json.dumps(fields) |
| 320 | self.form_data["fields"] = json.dumps(fields) |
| 321 | self.fields = fields |
| 322 | |
| 323 | if settings is not None: |
| 324 | updates["settings"] = json.dumps(settings) |
| 325 | self.form_data["settings"] = json.dumps(settings) |
| 326 | self.settings = settings |
| 327 | |
| 328 | updated = forms_table.update({"id": self.form_id}, updates) |
| 329 | return updated > 0 |
| 330 | |
| 331 | def export_responses_csv(self) -> str: |
| 332 | """Export responses as CSV |
| 333 | |
| 334 | Returns: |
| 335 | CSV string |
| 336 | """ |
| 337 | import csv |
| 338 | from io import StringIO |
| 339 | |
| 340 | output = StringIO() |
| 341 | |
| 342 | # Get all responses |
| 343 | responses = self.get_responses() |
| 344 | if not responses: |
| 345 | return "" |
| 346 | |
| 347 | # Write CSV |
| 348 | field_names = ["id", "submitted_at"] + [field["name"] for field in self.fields] |
| 349 | writer = csv.DictWriter(output, fieldnames=field_names) |
| 350 | |
| 351 | writer.writeheader() |
| 352 | for response in responses: |
| 353 | # Filter to only include relevant fields |
| 354 | row = {k: response.get(k, "") for k in field_names} |
| 355 | writer.writerow(row) |
| 356 | |
| 357 | return output.getvalue() |
| 358 | |
| 359 | def to_dict(self) -> Dict[str, Any]: |
| 360 | """Convert form to dictionary |
| 361 | |
| 362 | Returns: |
| 363 | Form data dictionary |
| 364 | """ |
| 365 | return { |
| 366 | "id": self.form_id, |
| 367 | "name": self.form_data["name"], |
| 368 | "description": self.form_data["description"], |
| 369 | "fields": self.fields, |
| 370 | "settings": self.settings, |
| 371 | "created_at": self.form_data["created_at"], |
| 372 | "updated_at": self.form_data["updated_at"], |
| 373 | "response_count": self.count_responses(), |
| 374 | } |