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/__init__.py ADDED
@@ -0,0 +1,184 @@
1
+ from __future__ import annotations
2
+
3
+ from flask_deck.adapters.sqlalchemy import (
4
+ FlaskSQLAlchemyAdapter,
5
+ ORMAdapter,
6
+ PureSQLAlchemyAdapter,
7
+ )
8
+ from flask_deck.audit import AuditEntry, AuditStore, InMemoryAuditStore, SQLAlchemyAuditStore
9
+ from flask_deck.auth import (
10
+ AuthProvider,
11
+ BasicAuthProvider,
12
+ DeckUser,
13
+ FlaskLoginAuthProvider,
14
+ OpenAuthProvider,
15
+ RBACAccount,
16
+ RBACAuthProvider,
17
+ Role,
18
+ )
19
+ from flask_deck.branding import ACCENT_PRESETS, BrandConfig
20
+ from flask_deck.config import DeckConfig
21
+ from flask_deck.dashboard import (
22
+ ActivityWidget,
23
+ CalloutWidget,
24
+ ChartWidget,
25
+ DashboardContext,
26
+ GaugeWidget,
27
+ HeatmapWidget,
28
+ KPIWidget,
29
+ MarkdownWidget,
30
+ StatBarWidget,
31
+ TableWidget,
32
+ TimelineWidget,
33
+ Widget,
34
+ )
35
+ from flask_deck.deck import Deck, PageSpec, run_security_audit
36
+ from flask_deck.events import DeckEvent, DeckEventBus, WebhookSink
37
+ from flask_deck.exceptions import (
38
+ DeckError,
39
+ ImportLimitError,
40
+ InvalidPKError,
41
+ PermissionDeniedError,
42
+ ReadOnlyError,
43
+ SecurityConfigurationError,
44
+ ValidationError,
45
+ )
46
+ from flask_deck.formatters import (
47
+ AvatarFormatter,
48
+ BadgeFormatter,
49
+ BooleanIconFormatter,
50
+ CodeFormatter,
51
+ CurrencyFormatter,
52
+ DateTimeFormatter,
53
+ FileFormatter,
54
+ Formatter,
55
+ ImageFormatter,
56
+ LinkFormatter,
57
+ ProgressBarFormatter,
58
+ RelativeTimeFormatter,
59
+ )
60
+ from flask_deck.i18n import BabelTranslator, DictTranslator, Translator
61
+ from flask_deck.jobs import JobBackend, JobContext, JobRecord, ThreadPoolJobBackend
62
+ from flask_deck.mfa import (
63
+ InMemoryMFAStore,
64
+ MFAEnrollment,
65
+ MFAStore,
66
+ SQLAlchemyMFAStore,
67
+ build_otpauth_uri,
68
+ compute_totp,
69
+ generate_totp_secret,
70
+ render_qr_svg,
71
+ verify_totp,
72
+ )
73
+ from flask_deck.model_view import (
74
+ ActionField,
75
+ ActionSpec,
76
+ InlineModelView,
77
+ ModelView,
78
+ action,
79
+ pydantic_validator,
80
+ )
81
+ from flask_deck.query import QuickTab
82
+ from flask_deck.sql_console import SQLQueryResult
83
+ from flask_deck.sso import OIDCAuthProvider, OIDCProviderConfig
84
+ from flask_deck.storage import (
85
+ FileFieldConfig,
86
+ LocalFileStorage,
87
+ MemoryFileStorage,
88
+ S3StorageBackend,
89
+ StorageBackend,
90
+ StoredFile,
91
+ )
92
+
93
+ __version__ = "0.3.0"
94
+
95
+ __all__ = [
96
+ "ACCENT_PRESETS",
97
+ "ActionField",
98
+ "ActionSpec",
99
+ "ActivityWidget",
100
+ "AuditEntry",
101
+ "AuditStore",
102
+ "AuthProvider",
103
+ "AvatarFormatter",
104
+ "BabelTranslator",
105
+ "BadgeFormatter",
106
+ "BasicAuthProvider",
107
+ "BooleanIconFormatter",
108
+ "BrandConfig",
109
+ "CalloutWidget",
110
+ "ChartWidget",
111
+ "CodeFormatter",
112
+ "CurrencyFormatter",
113
+ "DashboardContext",
114
+ "DateTimeFormatter",
115
+ "Deck",
116
+ "DeckConfig",
117
+ "DeckError",
118
+ "DeckEvent",
119
+ "DeckEventBus",
120
+ "DeckUser",
121
+ "DictTranslator",
122
+ "FileFieldConfig",
123
+ "FileFormatter",
124
+ "FlaskLoginAuthProvider",
125
+ "FlaskSQLAlchemyAdapter",
126
+ "Formatter",
127
+ "GaugeWidget",
128
+ "HeatmapWidget",
129
+ "ImageFormatter",
130
+ "ImportLimitError",
131
+ "InMemoryAuditStore",
132
+ "InMemoryMFAStore",
133
+ "InlineModelView",
134
+ "InvalidPKError",
135
+ "JobBackend",
136
+ "JobContext",
137
+ "JobRecord",
138
+ "KPIWidget",
139
+ "LinkFormatter",
140
+ "LocalFileStorage",
141
+ "MFAEnrollment",
142
+ "MFAStore",
143
+ "MarkdownWidget",
144
+ "MemoryFileStorage",
145
+ "ModelView",
146
+ "OIDCAuthProvider",
147
+ "OIDCProviderConfig",
148
+ "ORMAdapter",
149
+ "OpenAuthProvider",
150
+ "PageSpec",
151
+ "PermissionDeniedError",
152
+ "ProgressBarFormatter",
153
+ "PureSQLAlchemyAdapter",
154
+ "QuickTab",
155
+ "RBACAccount",
156
+ "RBACAuthProvider",
157
+ "ReadOnlyError",
158
+ "RelativeTimeFormatter",
159
+ "Role",
160
+ "S3StorageBackend",
161
+ "SQLAlchemyAuditStore",
162
+ "SQLAlchemyMFAStore",
163
+ "SQLQueryResult",
164
+ "SecurityConfigurationError",
165
+ "StatBarWidget",
166
+ "StorageBackend",
167
+ "StoredFile",
168
+ "TableWidget",
169
+ "ThreadPoolJobBackend",
170
+ "TimelineWidget",
171
+ "Translator",
172
+ "ValidationError",
173
+ "WebhookSink",
174
+ "Widget",
175
+ "__version__",
176
+ "action",
177
+ "build_otpauth_uri",
178
+ "compute_totp",
179
+ "generate_totp_secret",
180
+ "pydantic_validator",
181
+ "render_qr_svg",
182
+ "run_security_audit",
183
+ "verify_totp",
184
+ ]
@@ -0,0 +1,23 @@
1
+ from __future__ import annotations
2
+
3
+ from flask_deck.adapters.sqlalchemy import (
4
+ FlaskSQLAlchemyAdapter,
5
+ ORMAdapter,
6
+ PureSQLAlchemyAdapter,
7
+ coerce_pk_value,
8
+ decode_pk,
9
+ encode_pk,
10
+ extract_pk,
11
+ resolve_adapter,
12
+ )
13
+
14
+ __all__ = [
15
+ "FlaskSQLAlchemyAdapter",
16
+ "ORMAdapter",
17
+ "PureSQLAlchemyAdapter",
18
+ "coerce_pk_value",
19
+ "decode_pk",
20
+ "encode_pk",
21
+ "extract_pk",
22
+ "resolve_adapter",
23
+ ]
@@ -0,0 +1,272 @@
1
+ from __future__ import annotations
2
+
3
+ import base64
4
+ import enum
5
+ import json
6
+ import uuid
7
+ from abc import ABC, abstractmethod
8
+ from collections.abc import Callable, Mapping
9
+ from datetime import date, datetime
10
+ from decimal import Decimal
11
+ from typing import Any
12
+ from urllib.parse import quote, unquote
13
+
14
+ from flask import Flask, g
15
+ from sqlalchemy.engine import Engine
16
+ from sqlalchemy.orm import Session, sessionmaker
17
+
18
+ from flask_deck.exceptions import InvalidPKError
19
+ from flask_deck.introspection import FieldMeta, ModelMeta
20
+
21
+
22
+ class ORMAdapter(ABC):
23
+ """Abstract ORM adapter supporting Flask-SQLAlchemy and pure SQLAlchemy 2.0."""
24
+
25
+ @abstractmethod
26
+ def get_session(self) -> Session:
27
+ """Return the active SQLAlchemy Session for the current request."""
28
+
29
+ @abstractmethod
30
+ def get_engine(self) -> Engine:
31
+ """Return the underlying primary SQLAlchemy Engine."""
32
+
33
+ def get_engines(self) -> dict[str, Engine]:
34
+ """Return mapping of bind_key -> Engine (default bind keyed as 'default')."""
35
+ return {"default": self.get_engine()}
36
+
37
+ def get_session_for_bind(self, bind_key: str | None = None) -> Session:
38
+ """Return a Session bound to bind_key (defaults to primary request session)."""
39
+ _ = bind_key
40
+ return self.get_session()
41
+
42
+ def register_teardown(self, app: Flask) -> None:
43
+ """Optionally register request teardown hooks on the Flask app."""
44
+ _ = app
45
+
46
+ def dispose(self) -> None:
47
+ """Dispose underlying SQLAlchemy engine connection pools cleanly."""
48
+ for eng in self.get_engines().values():
49
+ eng.dispose()
50
+
51
+
52
+ class FlaskSQLAlchemyAdapter(ORMAdapter):
53
+ """Adapter for Flask-SQLAlchemy 3.x ``SQLAlchemy`` instances."""
54
+
55
+ __slots__ = ("_db",)
56
+
57
+ def __init__(self, db: Any) -> None:
58
+ self._db = db
59
+
60
+ def get_session(self) -> Session:
61
+ return self._db.session # type: ignore[no-any-return]
62
+
63
+ def get_engine(self) -> Engine:
64
+ return self._db.engine # type: ignore[no-any-return]
65
+
66
+ def get_engines(self) -> dict[str, Engine]:
67
+ engines_map = getattr(self._db, "engines", None)
68
+ if isinstance(engines_map, Mapping):
69
+ out: dict[str, Engine] = {}
70
+ for k, eng in engines_map.items():
71
+ if isinstance(eng, Engine):
72
+ out["default" if k is None else str(k)] = eng
73
+ if out:
74
+ return out
75
+ return {"default": self.get_engine()}
76
+
77
+
78
+ class PureSQLAlchemyAdapter(ORMAdapter):
79
+ """Adapter for pure SQLAlchemy 2.0 ``sessionmaker`` or ``Engine`` (supports multi-bind)."""
80
+
81
+ __slots__ = ("_bind_factories", "_binds", "_engine", "_g_key", "_session_factory")
82
+
83
+ def __init__(
84
+ self,
85
+ *,
86
+ session_factory: sessionmaker[Session] | Callable[[], Session] | None = None,
87
+ engine: Engine | None = None,
88
+ binds: Mapping[str, Engine] | None = None,
89
+ ) -> None:
90
+ if session_factory is None and engine is None:
91
+ raise ValueError("Provide either session_factory or engine for PureSQLAlchemyAdapter")
92
+ if session_factory is None:
93
+ assert engine is not None
94
+ session_factory = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)
95
+ self._session_factory = session_factory
96
+ self._engine = engine or getattr(session_factory, "kw", {}).get("bind")
97
+ self._binds: dict[str, Engine] = dict(binds or {})
98
+ self._bind_factories: dict[str, sessionmaker[Session]] = {
99
+ name: sessionmaker(bind=eng, autoflush=False, expire_on_commit=False)
100
+ for name, eng in self._binds.items()
101
+ }
102
+ self._g_key = f"_flask_deck_sa_session_{id(self)}"
103
+
104
+ def get_session(self) -> Session:
105
+ existing: Session | None = getattr(g, self._g_key, None)
106
+ if existing is None:
107
+ existing = self._session_factory()
108
+ setattr(g, self._g_key, existing)
109
+ return existing
110
+
111
+ def get_session_for_bind(self, bind_key: str | None = None) -> Session:
112
+ if not bind_key or bind_key == "default":
113
+ return self.get_session()
114
+ if bind_key not in self._bind_factories:
115
+ raise KeyError(f"Unknown SQLAlchemy bind_key: {bind_key!r}")
116
+ key = f"{self._g_key}_{bind_key}"
117
+ existing: Session | None = getattr(g, key, None)
118
+ if existing is None:
119
+ existing = self._bind_factories[bind_key]()
120
+ setattr(g, key, existing)
121
+ return existing
122
+
123
+ def get_engine(self) -> Engine:
124
+ if self._engine is not None:
125
+ return self._engine
126
+ sess = self.get_session()
127
+ bind = sess.get_bind()
128
+ if isinstance(bind, Engine):
129
+ self._engine = bind
130
+ return bind
131
+ return bind.engine
132
+
133
+ def get_engines(self) -> dict[str, Engine]:
134
+ out: dict[str, Engine] = {"default": self.get_engine()}
135
+ out.update(self._binds)
136
+ return out
137
+
138
+ def register_teardown(self, app: Flask) -> None:
139
+ g_key = self._g_key
140
+ bind_keys = tuple(self._bind_factories.keys())
141
+
142
+ @app.teardown_appcontext
143
+ def _close_deck_session(exc: BaseException | None) -> None:
144
+ for attr in (g_key, *(f"{g_key}_{bk}" for bk in bind_keys)):
145
+ sess: Session | None = getattr(g, attr, None)
146
+ if sess is not None:
147
+ try:
148
+ if exc is not None:
149
+ sess.rollback()
150
+ except Exception:
151
+ pass
152
+ finally:
153
+ try:
154
+ sess.close()
155
+ finally:
156
+ if hasattr(g, attr):
157
+ delattr(g, attr)
158
+
159
+
160
+ def resolve_adapter(
161
+ db: Any | None = None,
162
+ *,
163
+ session_factory: sessionmaker[Session] | Callable[[], Session] | None = None,
164
+ engine: Engine | None = None,
165
+ binds: Mapping[str, Engine] | None = None,
166
+ ) -> ORMAdapter:
167
+ """Resolve Flask-SQLAlchemy, ORMAdapter, sessionmaker, or Engine into an ORMAdapter."""
168
+ if isinstance(db, ORMAdapter):
169
+ return db
170
+ if db is not None:
171
+ if isinstance(db, Engine):
172
+ return PureSQLAlchemyAdapter(engine=db, binds=binds)
173
+ if callable(db):
174
+ return PureSQLAlchemyAdapter(session_factory=db, engine=engine, binds=binds)
175
+ # Detect Flask-SQLAlchemy without invoking its @property `engine` outside app context.
176
+ db_cls = type(db)
177
+ if hasattr(db, "session") and (hasattr(db_cls, "engine") or hasattr(db, "Model")):
178
+ return FlaskSQLAlchemyAdapter(db)
179
+ raise TypeError(
180
+ "Unsupported db argument. Pass a Flask-SQLAlchemy instance, "
181
+ "SQLAlchemy sessionmaker, Engine, or ORMAdapter."
182
+ )
183
+ return PureSQLAlchemyAdapter(session_factory=session_factory, engine=engine, binds=binds)
184
+
185
+
186
+ def coerce_pk_value(raw: Any, field: FieldMeta) -> Any:
187
+ """Strictly coerce a primary key segment to its declared Python type."""
188
+ if raw is None or raw == "":
189
+ raise InvalidPKError(f"Empty primary key for {field.name}")
190
+ try:
191
+ if field.field_type == "integer":
192
+ if isinstance(raw, bool):
193
+ raise InvalidPKError(f"Invalid integer PK: {raw!r}")
194
+ return int(raw)
195
+ if field.field_type == "uuid":
196
+ return raw if isinstance(raw, uuid.UUID) else uuid.UUID(str(raw))
197
+ if field.field_type == "enum" and field.enum_class is not None:
198
+ if isinstance(raw, field.enum_class):
199
+ return raw
200
+ s = str(raw)
201
+ try:
202
+ return field.enum_class(s)
203
+ except ValueError:
204
+ return field.enum_class[s]
205
+ if field.field_type == "date":
206
+ return raw if isinstance(raw, date) and not isinstance(raw, datetime) else date.fromisoformat(str(raw))
207
+ if field.field_type == "datetime":
208
+ return raw if isinstance(raw, datetime) else datetime.fromisoformat(str(raw))
209
+ if field.field_type == "decimal":
210
+ val = raw if isinstance(raw, Decimal) else Decimal(str(raw))
211
+ if not val.is_finite():
212
+ raise InvalidPKError(f"Non-finite decimal PK: {raw!r}")
213
+ return val
214
+ if field.python_type is int:
215
+ return int(raw)
216
+ return str(raw)
217
+ except InvalidPKError:
218
+ raise
219
+ except (TypeError, ValueError, KeyError) as exc:
220
+ raise InvalidPKError(f"Invalid primary key value for {field.name}: {raw!r}") from exc
221
+
222
+
223
+ def extract_pk(obj: Any, meta: ModelMeta) -> tuple[Any, ...]:
224
+ """Extract primary key values tuple from an ORM instance."""
225
+ return tuple(getattr(obj, pk.name) for pk in meta.primary_keys)
226
+
227
+
228
+ def _pk_part_to_str(val: Any) -> str:
229
+ if isinstance(val, enum.Enum):
230
+ return str(val.value)
231
+ if isinstance(val, (datetime, date)):
232
+ return val.isoformat()
233
+ return str(val)
234
+
235
+
236
+ def encode_pk(values: tuple[Any, ...]) -> str:
237
+ """Encode single or composite primary key values into a URL-safe string."""
238
+ if len(values) == 1:
239
+ text = _pk_part_to_str(values[0])
240
+ if "/" in text:
241
+ return f"pk:{quote(text, safe='')}"
242
+ return text
243
+ serialized = json.dumps([_pk_part_to_str(v) for v in values], separators=(",", ":")).encode("utf-8")
244
+ encoded = base64.urlsafe_b64encode(serialized).decode("ascii").rstrip("=")
245
+ return f"ck:{encoded}"
246
+
247
+
248
+ def decode_pk(raw: str, meta: ModelMeta) -> tuple[Any, ...]:
249
+ """Decode and strictly coerce a URL primary key segment back to typed tuple."""
250
+ if not raw:
251
+ raise InvalidPKError("Primary key cannot be empty")
252
+ if len(meta.primary_keys) == 1:
253
+ val = unquote(raw[3:]) if raw.startswith("pk:") else raw
254
+ return (coerce_pk_value(val, meta.primary_keys[0]),)
255
+
256
+ if not raw.startswith("ck:"):
257
+ raise InvalidPKError("Malformed composite primary key")
258
+ payload = raw[3:]
259
+ padding = "=" * (-len(payload) % 4)
260
+ try:
261
+ decoded = base64.urlsafe_b64decode(payload + padding)
262
+ parts = json.loads(decoded.decode("utf-8"))
263
+ except Exception as exc:
264
+ raise InvalidPKError("Malformed composite primary key payload") from exc
265
+
266
+ if not isinstance(parts, list) or len(parts) != len(meta.primary_keys):
267
+ raise InvalidPKError("Composite primary key arity mismatch")
268
+
269
+ return tuple(
270
+ coerce_pk_value(part, pk_field)
271
+ for part, pk_field in zip(parts, meta.primary_keys, strict=True)
272
+ )