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/storage.py ADDED
@@ -0,0 +1,669 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ import io
5
+ import os
6
+ import re
7
+ import struct
8
+ import tempfile
9
+ import threading
10
+ import uuid
11
+ from dataclasses import dataclass, field
12
+ from datetime import datetime, timezone
13
+ from pathlib import Path
14
+ from typing import Any, BinaryIO, Literal, Protocol, runtime_checkable
15
+
16
+ DEFAULT_IMAGE_MIMES: frozenset[str] = frozenset(
17
+ {"image/png", "image/jpeg", "image/webp", "image/gif"}
18
+ )
19
+ DEFAULT_FILE_MIMES: frozenset[str] = frozenset(
20
+ {
21
+ "image/png",
22
+ "image/jpeg",
23
+ "image/webp",
24
+ "image/gif",
25
+ "application/pdf",
26
+ "text/plain",
27
+ "text/csv",
28
+ "application/json",
29
+ "application/zip",
30
+ "application/gzip",
31
+ }
32
+ )
33
+ RASTER_INLINE_MIMES: frozenset[str] = frozenset(
34
+ {"image/png", "image/jpeg", "image/webp", "image/gif"}
35
+ )
36
+
37
+ _MIME_TO_EXT: dict[str, str] = {
38
+ "image/png": "png",
39
+ "image/jpeg": "jpg",
40
+ "image/webp": "webp",
41
+ "image/gif": "gif",
42
+ "image/svg+xml": "svg",
43
+ "application/pdf": "pdf",
44
+ "text/plain": "txt",
45
+ "text/csv": "csv",
46
+ "application/json": "json",
47
+ "application/zip": "zip",
48
+ "application/gzip": "gz",
49
+ }
50
+
51
+ _PREFIX_SAFE_RE = re.compile(r"[^a-zA-Z0-9/_-]+")
52
+
53
+
54
+ @dataclass(frozen=True, slots=True)
55
+ class StoredFile:
56
+ """Immutable metadata returned after storing an uploaded artifact."""
57
+
58
+ key: str
59
+ filename: str
60
+ content_type: str
61
+ size_bytes: int
62
+ sha256: str
63
+ width: int | None = None
64
+ height: int | None = None
65
+
66
+
67
+ @runtime_checkable
68
+ class StorageBackend(Protocol):
69
+ """Storage-agnostic contract implemented by Local, S3/R2, and Memory backends."""
70
+
71
+ def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
72
+ """Persist validated bytes at opaque key."""
73
+
74
+ def open(self, key: str) -> tuple[BinaryIO, str | None]:
75
+ """Return (readable binary stream, optional content_type) for key."""
76
+
77
+ def delete(self, key: str) -> None:
78
+ """Delete object if present (idempotent)."""
79
+
80
+ def exists(self, key: str) -> bool:
81
+ """Return True if key exists in storage."""
82
+
83
+ def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
84
+ """Optionally return a short-lived signed URL (None for private proxy-only backends)."""
85
+
86
+
87
+ @dataclass(frozen=True, slots=True)
88
+ class FileFieldConfig:
89
+ """Declarative configuration for one file or image upload column on a ModelView."""
90
+
91
+ storage: StorageBackend
92
+ kind: Literal["file", "image"] = "file"
93
+ allowed_mimes: frozenset[str] = field(default_factory=frozenset)
94
+ max_bytes: int | None = None
95
+ max_image_pixels: int = 25_000_000 # 25 MP decompression-bomb cap
96
+ prefix: str = "uploads"
97
+ delete_orphan: bool = False
98
+ allow_svg: bool = False
99
+
100
+ def resolved_allowed_mimes(self) -> frozenset[str]:
101
+ base = self.allowed_mimes or (
102
+ DEFAULT_IMAGE_MIMES if self.kind == "image" else DEFAULT_FILE_MIMES
103
+ )
104
+ if not self.allow_svg:
105
+ return base - {"image/svg+xml"}
106
+ return base | {"image/svg+xml"}
107
+
108
+
109
+ def sanitize_filename(filename: str) -> str:
110
+ """Extract a clean basename without path separators or control characters."""
111
+ base = filename.replace("\\", "/").rsplit("/", 1)[-1]
112
+ cleaned = "".join(ch for ch in base if 32 <= ord(ch) < 127 and ch not in {'"', "'", "<", ">"})
113
+ cleaned = cleaned.strip().lstrip(".")
114
+ return cleaned[:120] or "file"
115
+
116
+
117
+ def build_storage_key(prefix: str, mime: str) -> str:
118
+ """Build a collision-free opaque storage key never trusting user filenames."""
119
+ clean_prefix = _PREFIX_SAFE_RE.sub("", prefix.strip("/")) or "uploads"
120
+ now = datetime.now(timezone.utc)
121
+ ext = _MIME_TO_EXT.get(mime, "bin")
122
+ return f"{clean_prefix}/{now.year:04d}/{now.month:02d}/{uuid.uuid4().hex}.{ext}"
123
+
124
+
125
+ _XML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
126
+ _HTML_ACTIVE_TAG_RE = re.compile(
127
+ r"<\s*(?:!doctype\s+html|html|script|iframe|object|embed|body|head|meta|link|style|img|form)\b",
128
+ re.IGNORECASE,
129
+ )
130
+
131
+
132
+ def _decode_utf8_prefix(data: bytes, limit: int = 4096) -> str | None:
133
+ """Decode up to ``limit`` bytes of UTF-8 without failing on a split trailing multibyte char."""
134
+ chunk = data[:limit]
135
+ if len(data) > limit:
136
+ # Trim up to 3 trailing UTF-8 continuation/incomplete lead bytes at the slice boundary
137
+ for trim in range(4):
138
+ sub = chunk[: len(chunk) - trim] if trim else chunk
139
+ try:
140
+ return sub.decode("utf-8")
141
+ except UnicodeDecodeError:
142
+ continue
143
+ return None
144
+ try:
145
+ return chunk.decode("utf-8")
146
+ except UnicodeDecodeError:
147
+ return None
148
+
149
+
150
+ def detect_mime_from_bytes(data: bytes, filename: str = "") -> str | None:
151
+ """Pure-Python magic-byte MIME sniffer (zero libmagic dependency)."""
152
+ if not data:
153
+ return None
154
+ head = data[:64]
155
+
156
+ if head.startswith(b"\x89PNG\r\n\x1a\n"):
157
+ return "image/png"
158
+ if head.startswith(b"\xff\xd8\xff"):
159
+ return "image/jpeg"
160
+ if head.startswith((b"GIF87a", b"GIF89a")):
161
+ return "image/gif"
162
+ if len(head) >= 12 and head[:4] == b"RIFF" and head[8:12] == b"WEBP":
163
+ return "image/webp"
164
+ if head.startswith(b"%PDF-"):
165
+ return "application/pdf"
166
+ if head.startswith((b"PK\x03\x04", b"PK\x05\x06")):
167
+ return "application/zip"
168
+ if head.startswith(b"\x1f\x8b"):
169
+ return "application/gzip"
170
+
171
+ # Reject binary blobs with NUL bytes before checking text/SVG/JSON/CSV
172
+ if b"\x00" in data[:4096]:
173
+ return None
174
+
175
+ sample = _decode_utf8_prefix(data, 4096)
176
+ if sample is None:
177
+ return None
178
+
179
+ # Strip UTF-8 BOM, leading whitespace, and XML comments before checking SVG / HTML payloads
180
+ stripped = sample.lstrip("\ufeff \t\r\n")
181
+ no_comments = _XML_COMMENT_RE.sub("", stripped).lstrip()
182
+ lower = no_comments.lower()
183
+ if (
184
+ lower.startswith("<svg")
185
+ or lower.startswith("<!doctype svg")
186
+ or (lower.startswith("<?xml") and "<svg" in lower[:2048])
187
+ or "<svg" in lower[:512]
188
+ ):
189
+ return "image/svg+xml"
190
+ if _HTML_ACTIVE_TAG_RE.search(no_comments[:1024]):
191
+ # Never classify HTML/script payloads as safe text or image uploads.
192
+ return None
193
+
194
+ ext = filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
195
+ if stripped.startswith(("{", "[")) and ext == "json":
196
+ return "application/json"
197
+ if ext == "csv":
198
+ return "text/csv"
199
+ if ext == "txt":
200
+ return "text/plain"
201
+ if stripped.startswith(("{", "[")):
202
+ return "application/json"
203
+ return "text/plain"
204
+
205
+
206
+ def _parse_gif_max_dimensions(data: bytes) -> tuple[int, int] | None:
207
+ """Return max (width, height) across the GIF logical screen and all 0x2C image descriptors."""
208
+ if len(data) < 13:
209
+ return None
210
+ max_w, max_h = struct.unpack("<HH", data[6:10])
211
+ packed = data[10]
212
+ idx = 13
213
+ if packed & 0x80:
214
+ gct_size = 3 * (1 << ((packed & 0x07) + 1))
215
+ idx += gct_size
216
+ n = len(data)
217
+ while idx < n:
218
+ block = data[idx]
219
+ idx += 1
220
+ if block == 0x3B: # Trailer
221
+ break
222
+ if block == 0x2C: # Image Descriptor
223
+ if idx + 9 > n:
224
+ break
225
+ _left, _top, fw, fh, ipacked = struct.unpack("<HHHHB", data[idx : idx + 9])
226
+ max_w = max(max_w, fw)
227
+ max_h = max(max_h, fh)
228
+ idx += 9
229
+ if ipacked & 0x80:
230
+ idx += 3 * (1 << ((ipacked & 0x07) + 1))
231
+ if idx >= n:
232
+ break
233
+ idx += 1 # LZW minimum code size
234
+ while idx < n:
235
+ sub_len = data[idx]
236
+ idx += 1
237
+ if sub_len == 0:
238
+ break
239
+ idx += sub_len
240
+ elif block == 0x21: # Extension
241
+ if idx >= n:
242
+ break
243
+ idx += 1 # Extension label
244
+ while idx < n:
245
+ sub_len = data[idx]
246
+ idx += 1
247
+ if sub_len == 0:
248
+ break
249
+ idx += sub_len
250
+ else:
251
+ break
252
+ return int(max_w), int(max_h)
253
+
254
+
255
+ def parse_image_dimensions(data: bytes, mime: str) -> tuple[int, int] | None:
256
+ """Parse image (width, height) directly from binary headers to stop decompression bombs."""
257
+ try:
258
+ if mime == "image/png" and len(data) >= 24 and data[12:16] == b"IHDR":
259
+ w, h = struct.unpack(">II", data[16:24])
260
+ return int(w), int(h)
261
+ if mime == "image/gif" and len(data) >= 10:
262
+ return _parse_gif_max_dimensions(data)
263
+ if mime == "image/webp" and len(data) >= 25:
264
+ chunk = data[12:16]
265
+ if chunk == b"VP8L" and data[20] == 0x2F:
266
+ bits = struct.unpack("<I", data[21:25])[0]
267
+ return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
268
+ if chunk == b"VP8X" and len(data) >= 30:
269
+ w = 1 + int.from_bytes(data[24:27], "little")
270
+ h = 1 + int.from_bytes(data[27:30], "little")
271
+ return w, h
272
+ if chunk == b"VP8 " and len(data) >= 30 and data[23:26] == b"\x9d\x01\x2a":
273
+ w = struct.unpack("<H", data[26:28])[0] & 0x3FFF
274
+ h = struct.unpack("<H", data[28:30])[0] & 0x3FFF
275
+ return int(w), int(h)
276
+ if mime == "image/jpeg" and len(data) >= 4:
277
+ idx = 2
278
+ length = len(data)
279
+ while idx + 4 < length:
280
+ if data[idx] != 0xFF:
281
+ break
282
+ while idx < length and data[idx] == 0xFF:
283
+ idx += 1
284
+ if idx >= length:
285
+ break
286
+ marker = data[idx]
287
+ idx += 1
288
+ if marker in {0xD8, 0xD9, 0x01} or (0xD0 <= marker <= 0xD7):
289
+ continue
290
+ if idx + 2 > length:
291
+ break
292
+ seg_len = struct.unpack(">H", data[idx : idx + 2])[0]
293
+ if seg_len < 2 or idx + seg_len > length:
294
+ break
295
+ if marker in {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB}:
296
+ if idx + 7 <= length:
297
+ h, w = struct.unpack(">HH", data[idx + 3 : idx + 7])
298
+ return int(w), int(h)
299
+ break
300
+ idx += seg_len
301
+ except (struct.error, ValueError, IndexError):
302
+ return None
303
+ return None
304
+
305
+
306
+ def validate_and_read_upload(
307
+ stream: BinaryIO,
308
+ *,
309
+ filename: str,
310
+ config: FileFieldConfig,
311
+ default_max_bytes: int,
312
+ ) -> tuple[bytes, str, int | None, int | None]:
313
+ """Read upload with strict byte ceiling, magic-byte MIME sniff, and pixel bomb check."""
314
+ limit = config.max_bytes if config.max_bytes is not None else default_max_bytes
315
+ chunks: list[bytes] = []
316
+ total = 0
317
+ while True:
318
+ chunk = stream.read(65536)
319
+ if not chunk:
320
+ break
321
+ total += len(chunk)
322
+ if total > limit:
323
+ mb = limit / (1024 * 1024)
324
+ raise ValueError(f"File exceeds maximum allowed size ({mb:.1f} MiB).")
325
+ chunks.append(chunk)
326
+
327
+ data = b"".join(chunks)
328
+ if not data:
329
+ raise ValueError("Uploaded file is empty.")
330
+
331
+ detected = detect_mime_from_bytes(data, filename)
332
+ allowed = config.resolved_allowed_mimes()
333
+ if detected is None or detected not in allowed:
334
+ if detected == "image/svg+xml" and not config.allow_svg:
335
+ raise ValueError("SVG uploads are disabled by security policy.")
336
+ raise ValueError(
337
+ f"Unsupported or disallowed file content ({detected or 'unknown'})."
338
+ )
339
+
340
+ width: int | None = None
341
+ height: int | None = None
342
+ if detected in RASTER_INLINE_MIMES:
343
+ dims = parse_image_dimensions(data, detected)
344
+ if dims is None:
345
+ raise ValueError("Malformed or unreadable image header.")
346
+ width, height = dims
347
+ if width <= 0 or height <= 0 or (width * height) > config.max_image_pixels:
348
+ raise ValueError(
349
+ f"Image dimensions ({width}x{height}) exceed safety limit "
350
+ f"({config.max_image_pixels:,} pixels)."
351
+ )
352
+
353
+ return data, detected, width, height
354
+
355
+
356
+ def store_validated_upload(
357
+ stream: BinaryIO,
358
+ *,
359
+ filename: str,
360
+ config: FileFieldConfig,
361
+ default_max_bytes: int,
362
+ ) -> StoredFile:
363
+ """Validate an uploaded file stream and persist it cleanly to config.storage."""
364
+ data, mime, width, height = validate_and_read_upload(
365
+ stream,
366
+ filename=filename,
367
+ config=config,
368
+ default_max_bytes=default_max_bytes,
369
+ )
370
+ key = build_storage_key(config.prefix, mime)
371
+ stored = config.storage.save(data, key=key, content_type=mime)
372
+ return StoredFile(
373
+ key=stored.key,
374
+ filename=sanitize_filename(filename),
375
+ content_type=mime,
376
+ size_bytes=len(data),
377
+ sha256=stored.sha256,
378
+ width=width,
379
+ height=height,
380
+ )
381
+
382
+
383
+ def _validate_opaque_key(key: str) -> str:
384
+ clean = key.strip().lstrip("/")
385
+ if not clean or "\\" in clean or "\x00" in clean:
386
+ raise ValueError("Invalid storage key")
387
+ parts = clean.split("/")
388
+ if any(p in {"", ".", ".."} for p in parts):
389
+ raise ValueError("Invalid storage key")
390
+ return clean
391
+
392
+
393
+ class LocalFileStorage:
394
+ """Path-traversal-proof local filesystem storage backend with atomic writes."""
395
+
396
+ __slots__ = ("root_dir",)
397
+
398
+ def __init__(self, root_dir: str | Path) -> None:
399
+ self.root_dir = Path(root_dir).resolve()
400
+ self.root_dir.mkdir(parents=True, exist_ok=True)
401
+
402
+ def _resolve_path(self, key: str) -> Path:
403
+ clean = _validate_opaque_key(key)
404
+ candidate = (self.root_dir / clean).resolve()
405
+ if candidate == self.root_dir or not candidate.is_relative_to(self.root_dir):
406
+ raise ValueError("Storage key escapes root directory")
407
+ return candidate
408
+
409
+ def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
410
+ target = self._resolve_path(key)
411
+ target.parent.mkdir(parents=True, exist_ok=True)
412
+ digest = hashlib.sha256(data).hexdigest()
413
+ fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=".dk_tmp_")
414
+ try:
415
+ with os.fdopen(fd, "wb") as fh:
416
+ fh.write(data)
417
+ os.replace(tmp_name, target)
418
+ except Exception:
419
+ if os.path.exists(tmp_name):
420
+ os.unlink(tmp_name)
421
+ raise
422
+ return StoredFile(
423
+ key=_validate_opaque_key(key),
424
+ filename=target.name,
425
+ content_type=content_type,
426
+ size_bytes=len(data),
427
+ sha256=digest,
428
+ )
429
+
430
+ def open(self, key: str) -> tuple[BinaryIO, str | None]:
431
+ target = self._resolve_path(key)
432
+ if not target.is_file():
433
+ raise FileNotFoundError(key)
434
+ fh: BinaryIO = target.open("rb")
435
+ head = fh.read(4096)
436
+ fh.seek(0)
437
+ return fh, detect_mime_from_bytes(head, target.name)
438
+
439
+ def delete(self, key: str) -> None:
440
+ try:
441
+ target = self._resolve_path(key)
442
+ except ValueError:
443
+ return
444
+ if target.is_file():
445
+ target.unlink(missing_ok=True)
446
+
447
+ def exists(self, key: str) -> bool:
448
+ try:
449
+ return self._resolve_path(key).is_file()
450
+ except ValueError:
451
+ return False
452
+
453
+ def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
454
+ _ = (key, expires_in)
455
+ return None
456
+
457
+
458
+ class MemoryFileStorage:
459
+ """Thread-safe in-memory storage backend ideal for demos and test suites."""
460
+
461
+ __slots__ = ("_entries", "_lock")
462
+
463
+ def __init__(self) -> None:
464
+ self._entries: dict[str, tuple[bytes, str]] = {}
465
+ self._lock = threading.Lock()
466
+
467
+ def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
468
+ clean = _validate_opaque_key(key)
469
+ digest = hashlib.sha256(data).hexdigest()
470
+ with self._lock:
471
+ self._entries[clean] = (bytes(data), content_type)
472
+ return StoredFile(
473
+ key=clean,
474
+ filename=clean.rsplit("/", 1)[-1],
475
+ content_type=content_type,
476
+ size_bytes=len(data),
477
+ sha256=digest,
478
+ )
479
+
480
+ def open(self, key: str) -> tuple[BinaryIO, str | None]:
481
+ clean = _validate_opaque_key(key)
482
+ with self._lock:
483
+ entry = self._entries.get(clean)
484
+ if entry is None:
485
+ raise FileNotFoundError(key)
486
+ payload, ctype = entry
487
+ return io.BytesIO(payload), ctype
488
+
489
+ def delete(self, key: str) -> None:
490
+ try:
491
+ clean = _validate_opaque_key(key)
492
+ except ValueError:
493
+ return
494
+ with self._lock:
495
+ self._entries.pop(clean, None)
496
+
497
+ def exists(self, key: str) -> bool:
498
+ try:
499
+ clean = _validate_opaque_key(key)
500
+ except ValueError:
501
+ return False
502
+ with self._lock:
503
+ return clean in self._entries
504
+
505
+ def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
506
+ _ = (key, expires_in)
507
+ return None
508
+
509
+
510
+ class S3StorageBackend:
511
+ """AWS S3 / Cloudflare R2 / MinIO storage backend (lazy optional boto3 or injected client)."""
512
+
513
+ __slots__ = ("_bucket", "_client", "_endpoint_url", "_prefix", "_presign_ttl", "_region_name")
514
+
515
+ def __init__(
516
+ self,
517
+ bucket: str,
518
+ *,
519
+ prefix: str = "",
520
+ client: Any | None = None,
521
+ endpoint_url: str | None = None,
522
+ region_name: str | None = None,
523
+ presign_ttl: int = 300,
524
+ ) -> None:
525
+ if not bucket.strip():
526
+ raise ValueError("S3StorageBackend requires a non-empty bucket name")
527
+ self._bucket = bucket.strip()
528
+ self._prefix = prefix.strip("/")
529
+ self._client = client
530
+ self._endpoint_url = endpoint_url
531
+ self._region_name = region_name
532
+ self._presign_ttl = max(30, int(presign_ttl))
533
+
534
+ def _get_client(self) -> Any:
535
+ if self._client is None:
536
+ try:
537
+ import boto3 # type: ignore[import-not-found]
538
+ except ImportError as exc:
539
+ raise RuntimeError(
540
+ "boto3 is required for S3StorageBackend. Install with: pip install 'flask-deck[s3]'"
541
+ ) from exc
542
+ self._client = boto3.client(
543
+ "s3",
544
+ endpoint_url=self._endpoint_url,
545
+ region_name=self._region_name,
546
+ )
547
+ return self._client
548
+
549
+ def _full_key(self, key: str) -> str:
550
+ clean = _validate_opaque_key(key)
551
+ return f"{self._prefix}/{clean}" if self._prefix else clean
552
+
553
+ def save(self, data: bytes, *, key: str, content_type: str) -> StoredFile:
554
+ clean = _validate_opaque_key(key)
555
+ full = self._full_key(clean)
556
+ digest = hashlib.sha256(data).hexdigest()
557
+ put_kwargs: dict[str, Any] = {
558
+ "Bucket": self._bucket,
559
+ "Key": full,
560
+ "Body": data,
561
+ "ContentType": content_type,
562
+ }
563
+ if content_type not in RASTER_INLINE_MIMES:
564
+ put_kwargs["ContentDisposition"] = "attachment"
565
+ self._get_client().put_object(**put_kwargs)
566
+ return StoredFile(
567
+ key=clean,
568
+ filename=clean.rsplit("/", 1)[-1],
569
+ content_type=content_type,
570
+ size_bytes=len(data),
571
+ sha256=digest,
572
+ )
573
+
574
+ def open(self, key: str) -> tuple[BinaryIO, str | None]:
575
+ full = self._full_key(key)
576
+ try:
577
+ resp = self._get_client().get_object(Bucket=self._bucket, Key=full)
578
+ except FileNotFoundError:
579
+ raise
580
+ except Exception as exc:
581
+ err_resp = getattr(exc, "response", None)
582
+ if isinstance(err_resp, dict):
583
+ code = str(err_resp.get("Error", {}).get("Code", ""))
584
+ status = err_resp.get("ResponseMetadata", {}).get("HTTPStatusCode")
585
+ if code in {"NoSuchKey", "404", "NotFound"} or status == 404:
586
+ raise FileNotFoundError(key) from exc
587
+ raise
588
+ body = resp["Body"]
589
+ try:
590
+ raw: bytes = body.read()
591
+ finally:
592
+ if hasattr(body, "close"):
593
+ body.close()
594
+ ctype = resp.get("ContentType")
595
+ return io.BytesIO(raw), str(ctype) if isinstance(ctype, str) else None
596
+
597
+ def delete(self, key: str) -> None:
598
+ try:
599
+ full = self._full_key(key)
600
+ except ValueError:
601
+ return
602
+ self._get_client().delete_object(Bucket=self._bucket, Key=full)
603
+
604
+ def exists(self, key: str) -> bool:
605
+ try:
606
+ full = self._full_key(key)
607
+ except ValueError:
608
+ return False
609
+ try:
610
+ self._get_client().head_object(Bucket=self._bucket, Key=full)
611
+ return True
612
+ except Exception:
613
+ return False
614
+
615
+ def presigned_url(self, key: str, *, expires_in: int = 300) -> str | None:
616
+ full = self._full_key(key)
617
+ ttl = max(30, min(int(expires_in or self._presign_ttl), 3600))
618
+ params: dict[str, Any] = {"Bucket": self._bucket, "Key": full}
619
+ if not full.lower().endswith((".png", ".jpg", ".jpeg", ".webp", ".gif")):
620
+ params["ResponseContentDisposition"] = "attachment"
621
+ url = self._get_client().generate_presigned_url(
622
+ "get_object",
623
+ Params=params,
624
+ ExpiresIn=ttl,
625
+ )
626
+ return str(url) if url else None
627
+
628
+
629
+ def make_demo_png(
630
+ width: int = 64,
631
+ height: int = 64,
632
+ *,
633
+ bg: tuple[int, int, int] = (24, 24, 27),
634
+ fg: tuple[int, int, int] = (244, 244, 245),
635
+ accent: tuple[int, int, int] = (74, 222, 128),
636
+ ) -> bytes:
637
+ """Synthesize a crisp valid PNG thumbnail in pure Python stdlib (zero Pillow needed)."""
638
+ import zlib
639
+
640
+ def _chunk(tag: bytes, payload: bytes) -> bytes:
641
+ crc = zlib.crc32(tag + payload) & 0xFFFFFFFF
642
+ return struct.pack(">I", len(payload)) + tag + payload + struct.pack(">I", crc)
643
+
644
+ raw_rows = bytearray()
645
+ for y in range(height):
646
+ raw_rows.append(0) # filter byte None
647
+ for x in range(width):
648
+ border = x in {0, width - 1} or y in {0, height - 1}
649
+ diag = abs((x - width // 2) + (y - height // 2)) <= 3
650
+ bar = (height - 14 <= y <= height - 10) and (10 <= x <= width - 10)
651
+ dot = ((x - 14) ** 2 + (y - 14) ** 2) <= 20
652
+ if border:
653
+ r, g_c, b = (50, 50, 61)
654
+ elif dot:
655
+ r, g_c, b = accent
656
+ elif bar or diag:
657
+ r, g_c, b = fg
658
+ else:
659
+ r, g_c, b = bg
660
+ raw_rows.extend((r, g_c, b))
661
+
662
+ ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
663
+ idat = zlib.compress(bytes(raw_rows), 9)
664
+ return (
665
+ b"\x89PNG\r\n\x1a\n"
666
+ + _chunk(b"IHDR", ihdr)
667
+ + _chunk(b"IDAT", idat)
668
+ + _chunk(b"IEND", b"")
669
+ )