flask-deck 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. flask_deck/__init__.py +184 -0
  2. flask_deck/adapters/__init__.py +23 -0
  3. flask_deck/adapters/sqlalchemy.py +272 -0
  4. flask_deck/audit.py +363 -0
  5. flask_deck/auth.py +462 -0
  6. flask_deck/branding.py +217 -0
  7. flask_deck/charts.py +514 -0
  8. flask_deck/cli.py +135 -0
  9. flask_deck/config.py +81 -0
  10. flask_deck/dashboard.py +416 -0
  11. flask_deck/deck.py +4153 -0
  12. flask_deck/demo.py +1066 -0
  13. flask_deck/events.py +309 -0
  14. flask_deck/exceptions.py +34 -0
  15. flask_deck/exporter.py +240 -0
  16. flask_deck/formatters.py +386 -0
  17. flask_deck/i18n.py +399 -0
  18. flask_deck/icons.py +92 -0
  19. flask_deck/importer.py +612 -0
  20. flask_deck/introspection.py +376 -0
  21. flask_deck/jobs.py +382 -0
  22. flask_deck/mfa.py +670 -0
  23. flask_deck/model_view.py +1097 -0
  24. flask_deck/py.typed +0 -0
  25. flask_deck/query.py +1220 -0
  26. flask_deck/schema_graph.py +137 -0
  27. flask_deck/security.py +373 -0
  28. flask_deck/sql_console.py +391 -0
  29. flask_deck/sso.py +293 -0
  30. flask_deck/static/css/deck.css +1333 -0
  31. flask_deck/static/js/deck.js +1433 -0
  32. flask_deck/storage.py +669 -0
  33. flask_deck/templates/flask_deck/audit_list.html +117 -0
  34. flask_deck/templates/flask_deck/base.html +454 -0
  35. flask_deck/templates/flask_deck/custom_page.html +12 -0
  36. flask_deck/templates/flask_deck/dashboard.html +32 -0
  37. flask_deck/templates/flask_deck/diagnostics.html +80 -0
  38. flask_deck/templates/flask_deck/error.html +15 -0
  39. flask_deck/templates/flask_deck/import_wizard.html +143 -0
  40. flask_deck/templates/flask_deck/jobs_list.html +95 -0
  41. flask_deck/templates/flask_deck/login.html +93 -0
  42. flask_deck/templates/flask_deck/login_mfa.html +59 -0
  43. flask_deck/templates/flask_deck/mfa_setup.html +121 -0
  44. flask_deck/templates/flask_deck/model_detail.html +124 -0
  45. flask_deck/templates/flask_deck/model_form.html +389 -0
  46. flask_deck/templates/flask_deck/model_list.html +489 -0
  47. flask_deck/templates/flask_deck/partials/drawer_detail.html +93 -0
  48. flask_deck/templates/flask_deck/partials/widget_grid.html +207 -0
  49. flask_deck/templates/flask_deck/rbac_matrix.html +59 -0
  50. flask_deck/templates/flask_deck/record_history.html +102 -0
  51. flask_deck/templates/flask_deck/schema_inspector.html +83 -0
  52. flask_deck/templates/flask_deck/sql_console.html +87 -0
  53. flask_deck-0.3.0.dist-info/METADATA +382 -0
  54. flask_deck-0.3.0.dist-info/RECORD +57 -0
  55. flask_deck-0.3.0.dist-info/WHEEL +4 -0
  56. flask_deck-0.3.0.dist-info/entry_points.txt +5 -0
  57. flask_deck-0.3.0.dist-info/licenses/LICENSE +21 -0
flask_deck/jobs.py ADDED
@@ -0,0 +1,382 @@
1
+ from __future__ import annotations
2
+
3
+ import logging
4
+ import threading
5
+ import uuid
6
+ from collections import OrderedDict
7
+ from collections.abc import Callable
8
+ from concurrent.futures import ThreadPoolExecutor
9
+ from dataclasses import dataclass, field, replace
10
+ from datetime import datetime, timezone
11
+ from typing import Any, Literal, Protocol, runtime_checkable
12
+
13
+ from flask import Flask
14
+
15
+ logger = logging.getLogger("flask_deck.jobs")
16
+
17
+ JobStatus = Literal["queued", "running", "succeeded", "failed", "cancelled"]
18
+ TERMINAL_JOB_STATUSES: frozenset[str] = frozenset({"succeeded", "failed", "cancelled"})
19
+
20
+
21
+ @dataclass(slots=True)
22
+ class JobRecord:
23
+ """Mutable tracked state of one asynchronous Flask-Deck background job."""
24
+
25
+ id: str
26
+ name: str
27
+ label: str
28
+ actor_id: str
29
+ actor_name: str
30
+ model_slug: str = ""
31
+ status: JobStatus = "queued"
32
+ progress: int = 0
33
+ message: str = "Queued"
34
+ logs: list[str] = field(default_factory=list)
35
+ created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
36
+ started_at: datetime | None = None
37
+ finished_at: datetime | None = None
38
+ artifact_key: str | None = None
39
+ artifact_filename: str | None = None
40
+ artifact_mime: str | None = None
41
+ error: str | None = None
42
+
43
+ def to_dict(self) -> dict[str, Any]:
44
+ duration_ms: int | None = None
45
+ if self.started_at is not None:
46
+ end = self.finished_at or datetime.now(timezone.utc)
47
+ duration_ms = max(0, int((end - self.started_at).total_seconds() * 1000))
48
+ return {
49
+ "id": self.id,
50
+ "name": self.name,
51
+ "label": self.label,
52
+ "actor_id": self.actor_id,
53
+ "actor_name": self.actor_name,
54
+ "model_slug": self.model_slug,
55
+ "status": self.status,
56
+ "progress": self.progress,
57
+ "message": self.message,
58
+ "logs": list(self.logs),
59
+ "created_at": self.created_at.isoformat(),
60
+ "started_at": self.started_at.isoformat() if self.started_at else None,
61
+ "finished_at": self.finished_at.isoformat() if self.finished_at else None,
62
+ "duration_ms": duration_ms,
63
+ "artifact_filename": self.artifact_filename,
64
+ "error": self.error,
65
+ }
66
+
67
+
68
+ class JobContext:
69
+ """Progress, log, artifact, and cancellation controller passed to async job functions."""
70
+
71
+ __slots__ = ("_backend", "_cancel_event", "job_id")
72
+
73
+ def __init__(
74
+ self,
75
+ backend: ThreadPoolJobBackend,
76
+ job_id: str,
77
+ cancel_event: threading.Event,
78
+ ) -> None:
79
+ self._backend = backend
80
+ self.job_id = job_id
81
+ self._cancel_event = cancel_event
82
+
83
+ def is_cancelled(self) -> bool:
84
+ return self._cancel_event.is_set()
85
+
86
+ def set_progress(self, pct: int, message: str | None = None) -> None:
87
+ self._backend._update(
88
+ self.job_id,
89
+ progress=max(0, min(100, int(pct))),
90
+ message=message,
91
+ )
92
+
93
+ def log(self, line: str) -> None:
94
+ self._backend._append_log(self.job_id, line)
95
+
96
+ def attach_artifact(self, *, key: str, filename: str, content_type: str) -> None:
97
+ self._backend._attach_artifact(
98
+ self.job_id, key=key, filename=filename, content_type=content_type
99
+ )
100
+
101
+
102
+ JobCallable = Callable[[JobContext], str | None]
103
+
104
+
105
+ @runtime_checkable
106
+ class JobBackend(Protocol):
107
+ """Pluggable background job runner contract (ThreadPool built-in; Celery/RQ adaptable)."""
108
+
109
+ def submit(
110
+ self,
111
+ *,
112
+ name: str,
113
+ label: str,
114
+ actor_id: str,
115
+ actor_name: str,
116
+ model_slug: str,
117
+ fn: JobCallable,
118
+ app: Flask | None = None,
119
+ on_complete: Callable[[JobRecord], None] | None = None,
120
+ ) -> JobRecord:
121
+ """Enqueue fn and return initial JobRecord."""
122
+
123
+ def get(self, job_id: str) -> JobRecord | None:
124
+ """Return JobRecord snapshot by ID."""
125
+
126
+ def list_jobs(
127
+ self,
128
+ *,
129
+ actor_id: str | None = None,
130
+ limit: int = 50,
131
+ ) -> list[JobRecord]:
132
+ """Return newest jobs first, optionally filtered by actor_id."""
133
+
134
+ def cancel(self, job_id: str) -> bool:
135
+ """Request cooperative cancellation of a queued or running job."""
136
+
137
+
138
+ class ThreadPoolJobBackend:
139
+ """Zero-dependency bounded thread-pool job runner with Flask app_context propagation."""
140
+
141
+ __slots__ = (
142
+ "_cancel_events",
143
+ "_executor",
144
+ "_jobs",
145
+ "_lock",
146
+ "_max_history",
147
+ "_max_logs",
148
+ "_on_evict",
149
+ )
150
+
151
+ def __init__(
152
+ self,
153
+ *,
154
+ max_workers: int = 2,
155
+ max_history: int = 100,
156
+ max_logs_per_job: int = 100,
157
+ on_evict: Callable[[JobRecord], None] | None = None,
158
+ ) -> None:
159
+ self._executor = ThreadPoolExecutor(
160
+ max_workers=max(1, int(max_workers)),
161
+ thread_name_prefix="flask-deck-job",
162
+ )
163
+ self._jobs: OrderedDict[str, JobRecord] = OrderedDict()
164
+ self._cancel_events: dict[str, threading.Event] = {}
165
+ self._lock = threading.Lock()
166
+ self._max_history = max(10, int(max_history))
167
+ self._max_logs = max(10, int(max_logs_per_job))
168
+ self._on_evict = on_evict
169
+
170
+ def set_on_evict(self, callback: Callable[[JobRecord], None] | None) -> None:
171
+ """Attach an eviction callback (e.g. to purge expired artifact storage keys)."""
172
+ with self._lock:
173
+ self._on_evict = callback
174
+
175
+ @staticmethod
176
+ def _snapshot(rec: JobRecord) -> JobRecord:
177
+ return replace(rec, logs=list(rec.logs))
178
+
179
+ def _update(
180
+ self,
181
+ job_id: str,
182
+ *,
183
+ status: JobStatus | None = None,
184
+ progress: int | None = None,
185
+ message: str | None = None,
186
+ error: str | None = None,
187
+ started_at: datetime | None = None,
188
+ finished_at: datetime | None = None,
189
+ ) -> JobRecord | None:
190
+ with self._lock:
191
+ rec = self._jobs.get(job_id)
192
+ if rec is None:
193
+ return None
194
+ if status is not None:
195
+ rec.status = status
196
+ if progress is not None:
197
+ rec.progress = progress
198
+ if message is not None:
199
+ rec.message = message
200
+ if error is not None:
201
+ rec.error = error
202
+ if started_at is not None:
203
+ rec.started_at = started_at
204
+ if finished_at is not None:
205
+ rec.finished_at = finished_at
206
+ return self._snapshot(rec)
207
+
208
+ def _append_log(self, job_id: str, line: str) -> None:
209
+ ts = datetime.now(timezone.utc).strftime("%H:%M:%S")
210
+ entry = f"[{ts}] {line}"
211
+ with self._lock:
212
+ rec = self._jobs.get(job_id)
213
+ if rec is None:
214
+ return
215
+ rec.logs.append(entry)
216
+ if len(rec.logs) > self._max_logs:
217
+ del rec.logs[: len(rec.logs) - self._max_logs]
218
+
219
+ def _attach_artifact(self, job_id: str, *, key: str, filename: str, content_type: str) -> None:
220
+ with self._lock:
221
+ rec = self._jobs.get(job_id)
222
+ if rec is not None:
223
+ rec.artifact_key = key
224
+ rec.artifact_filename = filename
225
+ rec.artifact_mime = content_type
226
+
227
+ def _evict_terminal_locked(self) -> list[JobRecord]:
228
+ evicted: list[JobRecord] = []
229
+ if len(self._jobs) <= self._max_history:
230
+ return evicted
231
+ terminal_ids = [
232
+ jid for jid, item in self._jobs.items() if item.status in TERMINAL_JOB_STATUSES
233
+ ]
234
+ for jid in terminal_ids:
235
+ if len(self._jobs) <= self._max_history:
236
+ break
237
+ old = self._jobs.pop(jid, None)
238
+ self._cancel_events.pop(jid, None)
239
+ if old is not None:
240
+ evicted.append(self._snapshot(old))
241
+ return evicted
242
+
243
+ def submit(
244
+ self,
245
+ *,
246
+ name: str,
247
+ label: str,
248
+ actor_id: str,
249
+ actor_name: str,
250
+ model_slug: str,
251
+ fn: JobCallable,
252
+ app: Flask | None = None,
253
+ on_complete: Callable[[JobRecord], None] | None = None,
254
+ ) -> JobRecord:
255
+ job_id = uuid.uuid4().hex[:16]
256
+ rec = JobRecord(
257
+ id=job_id,
258
+ name=name,
259
+ label=label,
260
+ actor_id=actor_id,
261
+ actor_name=actor_name,
262
+ model_slug=model_slug,
263
+ )
264
+ cancel_ev = threading.Event()
265
+ with self._lock:
266
+ self._jobs[job_id] = rec
267
+ self._cancel_events[job_id] = cancel_ev
268
+ evicted = self._evict_terminal_locked()
269
+ evict_cb = self._on_evict
270
+ initial_snapshot = self._snapshot(rec)
271
+
272
+ if evict_cb is not None:
273
+ for old_rec in evicted:
274
+ try:
275
+ evict_cb(old_rec)
276
+ except Exception as exc:
277
+ logger.warning("Job eviction cleanup error for %s: %s", old_rec.id, exc)
278
+
279
+ ctx = JobContext(self, job_id, cancel_ev)
280
+
281
+ def _invoke_on_complete(final_rec: JobRecord | None) -> None:
282
+ if final_rec is None or on_complete is None:
283
+ return
284
+ try:
285
+ if app is not None:
286
+ with app.app_context():
287
+ on_complete(final_rec)
288
+ else:
289
+ on_complete(final_rec)
290
+ except Exception as exc:
291
+ logger.warning("Job on_complete callback error for %s: %s", job_id, exc)
292
+
293
+ def _runner() -> None:
294
+ # Atomically check cancellation and transition queued -> running under _lock
295
+ with self._lock:
296
+ cur = self._jobs.get(job_id)
297
+ if cur is None:
298
+ return
299
+ if cancel_ev.is_set() or cur.status == "cancelled":
300
+ cur.status = "cancelled"
301
+ cur.message = "Cancelled before start"
302
+ cur.finished_at = cur.finished_at or datetime.now(timezone.utc)
303
+ cancelled_snap = self._snapshot(cur)
304
+ else:
305
+ cur.status = "running"
306
+ cur.progress = 5
307
+ cur.message = "Running…"
308
+ cur.started_at = datetime.now(timezone.utc)
309
+ cancelled_snap = None
310
+
311
+ if cancelled_snap is not None:
312
+ _invoke_on_complete(cancelled_snap)
313
+ return
314
+
315
+ try:
316
+ if app is not None:
317
+ with app.app_context():
318
+ result_msg = fn(ctx)
319
+ else:
320
+ result_msg = fn(ctx)
321
+ if cancel_ev.is_set():
322
+ final = self._update(
323
+ job_id,
324
+ status="cancelled",
325
+ message="Cancelled by operator",
326
+ finished_at=datetime.now(timezone.utc),
327
+ )
328
+ else:
329
+ final = self._update(
330
+ job_id,
331
+ status="succeeded",
332
+ progress=100,
333
+ message=result_msg or "Completed successfully",
334
+ finished_at=datetime.now(timezone.utc),
335
+ )
336
+ except Exception as exc:
337
+ self._append_log(job_id, f"ERROR: {exc}")
338
+ final = self._update(
339
+ job_id,
340
+ status="failed",
341
+ message="Failed",
342
+ error=str(exc),
343
+ finished_at=datetime.now(timezone.utc),
344
+ )
345
+ _invoke_on_complete(final)
346
+
347
+ self._executor.submit(_runner)
348
+ return initial_snapshot
349
+
350
+ def get(self, job_id: str) -> JobRecord | None:
351
+ with self._lock:
352
+ rec = self._jobs.get(job_id)
353
+ return self._snapshot(rec) if rec is not None else None
354
+
355
+ def list_jobs(
356
+ self,
357
+ *,
358
+ actor_id: str | None = None,
359
+ limit: int = 50,
360
+ ) -> list[JobRecord]:
361
+ with self._lock:
362
+ items = [self._snapshot(j) for j in reversed(self._jobs.values())]
363
+ if actor_id is not None:
364
+ items = [j for j in items if j.actor_id == actor_id]
365
+ return items[: max(1, limit)]
366
+
367
+ def cancel(self, job_id: str) -> bool:
368
+ with self._lock:
369
+ rec = self._jobs.get(job_id)
370
+ ev = self._cancel_events.get(job_id)
371
+ if rec is None or ev is None or rec.status in TERMINAL_JOB_STATUSES:
372
+ return False
373
+ ev.set()
374
+ if rec.status == "queued":
375
+ rec.status = "cancelled"
376
+ rec.message = "Cancelled"
377
+ rec.finished_at = datetime.now(timezone.utc)
378
+ return True
379
+
380
+ def shutdown(self, *, wait: bool = False, cancel_futures: bool = True) -> None:
381
+ """Gracefully shut down the background worker thread pool."""
382
+ self._executor.shutdown(wait=wait, cancel_futures=cancel_futures)