flask-construct-ui 0.11.6__tar.gz → 0.12.0__tar.gz

{flask_construct_ui-0.11.6 → flask_construct_ui-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-construct-ui
-Version: 0.11.6
+Version: 0.12.0
 Summary: A UI toolkit for Flask with CRUD and component features.
 Author-email: Olof Tjerngren <olof@tjerngren.net>
 License-Expression: LGPL-3.0-or-later

{flask_construct_ui-0.11.6 → flask_construct_ui-0.12.0}/flask_construct_ui/__init__.py

@@ -27,6 +27,7 @@ from .components import (
     find_component as find_component,
     find_component_by_id as find_component_by_id,
     LiveComponent as LiveComponent,
+    LiveRefreshComponent as LiveRefreshComponent,
     VerticalLayoutComponent as VerticalLayoutComponent,
     HorizontalLayoutComponent as HorizontalLayoutComponent,
     GridLayoutComponent as GridLayoutComponent,
@@ -45,6 +46,11 @@ from .components import (
     KanbanColumn as KanbanColumn,
     KanbanCard as KanbanCard,
     KanbanCardAction as KanbanCardAction,
+    PivotFormComponent as PivotFormComponent,
+    PivotRow as PivotRow,
+    PivotColumn as PivotColumn,
+    PivotCell as PivotCell,
+    PeriodNavComponent as PeriodNavComponent,
 )
 
 # Authentication & authorization
@@ -98,6 +104,18 @@ from .headless import (
     live_container as live_container,
 )
 
+# Live refresh on commit (see live.py)
+from .live import (
+    ChangeFeed as ChangeFeed,
+    MemoryBroker as MemoryBroker,
+    RedisBroker as RedisBroker,
+    SQLAlchemyChanges as SQLAlchemyChanges,
+)
+
+# Declarative drag-and-drop attributes (see dragdrop.py)
+from .dragdrop import drag_attrs as drag_attrs, drop_attrs as drop_attrs
+from .errors import render_error as render_error
+
 # HTML sanitizer (allowlist-based; for trusted-HTML surfaces such as
 # LiveComponent format="raw" and TextComponent format="html")
 from .sanitize import sanitize_html as sanitize_html

{flask_construct_ui-0.11.6 → flask_construct_ui-0.12.0}/flask_construct_ui/app_hooks.py

@@ -6,7 +6,9 @@ decides the order they run in.
 
 from __future__ import annotations
 
-from flask import Blueprint, current_app, g, render_template, request
+import logging
+
+from flask import Blueprint, current_app, g, jsonify, render_template, request
 import jinja2
 from markupsafe import Markup
 
@@ -18,7 +20,9 @@ from .csrf import (
     generate_csrf_token,
     validate_csrf_token,
 )
-from .headless import live_attributes, live_container
+from .flashes import render_flashes
+from .headless import live_attributes, live_container, sse_event, sse_response
+from .live import live_refresh
 from .icons import render_icon
 from .navigation import resolve_next
 from .pagination import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
@@ -32,6 +36,10 @@ from .resume import (
     resumed_values,
 )
 from .sanitize import sanitize_html
+from .dragdrop import drag_attrs, drop_attrs
+from .urls import current_url, hidden_inputs, query_string
+
+_log = logging.getLogger(__name__)
 
 
 def set_config_defaults(construct, app):
@@ -59,6 +67,10 @@ def set_config_defaults(construct, app):
     app.config.setdefault("CONSTRUCT_RESUME_MAX_BYTES", RESUME_MAX_BYTES)
     app.config.setdefault("CONSTRUCT_RESUME_TTL", RESUME_TTL)
     app.config.setdefault("CONSTRUCT_RESUME_SKIP_FIELDS", RESUME_SKIP_FIELDS)
+    # Seconds a /_construct/live/changes stream waits for a change before
+    # ending; the browser reconnects at once. Bounds how long a worker is held
+    # by a client that has gone away without a write to notice it by.
+    app.config.setdefault("CONSTRUCT_LIVE_WAIT", 25)
 
 
 def install_request_hooks(construct, app):
@@ -171,7 +183,7 @@ def install_template_helpers(construct, app):
 
         # MarkdownIt passes raw HTML through, so the converted output must be
         # sanitized before it is marked safe (stored-XSS boundary).
-        return Markup(
+        return Markup(  # noqa: S704
             sanitize_html(md.render(s))
         )  # nosemgrep: explicit-unescape-with-markup  # nosec B704
 
@@ -181,7 +193,7 @@ def install_template_helpers(construct, app):
             return ""
         from .orgmode import org_to_html
 
-        return Markup(
+        return Markup(  # noqa: S704
             sanitize_html(org_to_html(s))
         )  # nosemgrep: explicit-unescape-with-markup  # nosec B704
 
@@ -209,16 +221,28 @@ def install_template_helpers(construct, app):
     app.jinja_env.globals.update(
         live_container=live_container,
         live_attributes=live_attributes,
+        live_refresh=live_refresh,
         csrf_field=csrf_field,
         csrf_token=generate_csrf_token,
         t=translate,
         icon=render_icon,
         next_url=resolve_next,
+        # The flash region, placed where the page wants it; the layout then
+        # leaves its own out for this request (see flashes.py).
+        flashes=render_flashes,
         # An app template can put its own form back after a re-login
         # with no Python change; see resume.py.
         resumed_value=resumed_value,
         resumed_values=resumed_values,
         has_resumable_form=has_resumable_form,
+        # Links and GET forms that change one query argument and carry the
+        # rest, repeated keys included; see urls.py.
+        current_url=current_url,
+        query_string=query_string,
+        hidden_inputs=hidden_inputs,
+        # Drag a thing onto a zone and POST both ends' fields; see dragdrop.py.
+        drag_attrs=drag_attrs,
+        drop_attrs=drop_attrs,
     )
     # Components render through their own standalone Jinja environment,
     # so the CSRF helpers, translator and icon renderer must be registered
@@ -228,6 +252,12 @@ def install_template_helpers(construct, app):
         csrf_token=generate_csrf_token,
         t=translate,
         icon=render_icon,
+        current_url=current_url,
+        query_string=query_string,
+        hidden_inputs=hidden_inputs,
+        drag_attrs=drag_attrs,
+        drop_attrs=drop_attrs,
+        live_refresh=live_refresh,
     )
     if app.jinja_env.loader:
         jinja_env.loader = jinja2.ChoiceLoader(
@@ -257,11 +287,13 @@ def register_features_blueprint(construct):
     notifications_url = "/notifications"
     menu_url = "/menu"
     footer_url = "/footer"
+    live_url = "/live/changes"
     if construct.enforce_trailing_slash:
         search_url += "/"
         notifications_url += "/"
         menu_url += "/"
         footer_url += "/"
+        live_url += "/"
 
     route_kwargs = {}
     if construct.strict_slashes is not None:
@@ -314,5 +346,43 @@ def register_features_blueprint(construct):
             footer_fragment=True,
         )
 
+    @features_bp.route(live_url, **route_kwargs)
+    def live_changes():
+        # The change feed behind live_refresh(); see live.py. Unconditional
+        # for the same reason as the menu route — `construct.live` may be set
+        # after init_app — so it 404s while no feed is configured. `since` is
+        # the version the page was rendered from; the stream ends with a
+        # `change` event as soon as the version differs from it, or quietly
+        # after CONSTRUCT_LIVE_WAIT seconds (EventSource reconnects by
+        # itself). `?poll=1` answers at once, for browsers that can't stream.
+        feed = construct.live
+        if feed is None:
+            return "", 404
+        since = request.args.get("since", "")
+        no_store = {"Cache-Control": "no-store"}
+        if request.args.get("poll"):
+            version = feed.version()
+            if version is None:
+                return jsonify(error="unavailable"), 503, no_store
+            return jsonify(version=version), 200, no_store
+        # Fail the request, not the stream, when the broker is down: an
+        # EventSource only gives up (and the page falls back to polling and
+        # shows "not updating") on a non-200 answer.
+        if feed.version() is None:
+            return "", 503, no_store
+        wait = float(current_app.config.get("CONSTRUCT_LIVE_WAIT", 25))
+
+        def stream():
+            yield "retry: 2000\n\n"
+            try:
+                version = feed.wait(since, wait)
+            except Exception:  # noqa: BLE001 - the client reconnects and sees the 503
+                _log.warning("live: change feed failed mid-stream", exc_info=True)
+                return
+            if version != since:
+                yield sse_event("change", {"version": version})
+
+        return sse_response(stream())
+
     construct.app.register_blueprint(features_bp)
     construct._blueprint_names.add("construct_features")

{flask_construct_ui-0.11.6 → flask_construct_ui-0.12.0}/flask_construct_ui/auth.py

@@ -124,7 +124,7 @@ class AuthProvider:
 
     #: Flask endpoint name (or literal path) to send unauthenticated users to.
     #: Overridden by the ``CONSTRUCT_LOGIN_ENDPOINT`` config when set.
-    login_endpoint = None
+    login_endpoint: str | None = None
 
     def is_authenticated(self) -> bool:
         raise NotImplementedError
@@ -194,7 +194,7 @@ class AuthProvider:
         nxt = self.return_target()
         try:
             return url_for(target, next=nxt) if nxt else url_for(target)
-        except Exception:
+        except Exception:  # noqa: BLE001 - url_for failure means a literal path
             # Not a known endpoint — treat it as a literal path.
             if not nxt:
                 return target
@@ -296,7 +296,7 @@ class FlaskSecurityAuth(AuthProvider):
                     "icon": "logout",
                 }
             ]
-        except Exception:
+        except Exception:  # noqa: BLE001 - no sign-out route, no link
             return []
 
 
@@ -418,7 +418,7 @@ class FlaskOIDCAuth(AuthProvider):
         code would be spent, and the abort that follows is worse than the
         front page this replaces.
         """
-        if request.blueprint == self.login_endpoint.rsplit(".", 1)[0]:
+        if request.blueprint == (self.login_endpoint or "").rsplit(".", 1)[0]:
             nxt = request.args.get("next")
             if not nxt or not is_safe_next(nxt) or is_fragment_target(nxt):
                 return None
@@ -495,5 +495,5 @@ class FlaskOIDCAuth(AuthProvider):
                     "icon": "logout",
                 }
             ]
-        except Exception:
+        except Exception:  # noqa: BLE001 - no sign-out route, no link
             return []

{flask_construct_ui-0.11.6 → flask_construct_ui-0.12.0}/flask_construct_ui/base.py

@@ -24,6 +24,9 @@ from markupsafe import Markup
 
 from . import app_hooks
 from .auth import auth_stamp
+from .capabilities import UNSET, guard_route, route_capability
+from .errors import check_mapping as check_error_mapping
+from .errors import make_handler as make_error_handler
 from .components import (
     CalendarComponent,
     ChartComponent,
@@ -66,8 +69,25 @@ def edit_action(name, icon):
     return decorator
 
 
-def expose(url="/", methods=None):
+def expose(url="/", methods=None, capability=UNSET):
+    """Route the decorated page method at *url*.
+
+    ``capability="<name>"`` asks the page's ``can_<name>`` hook before the
+    view runs and answers 403 when it refuses — the route-side half of a
+    hidden control. ``"edit"``/``"view"``/``"delete"`` are asked about the
+    record whose id is the route's ``<id>``; ``"add"`` and any name of your
+    own take no row. ``capability=False`` exempts a writing route from the
+    page's ``write_capability``.
+    """
+    if capability is None:
+        raise ValueError(
+            "@expose(capability=None) is ambiguous; omit it, or pass False "
+            "to opt out of the page's write_capability."
+        )
+
     def wrap(f):
+        if capability is not UNSET:
+            f._expose_capability = capability
         if not hasattr(f, "_urls"):
             f._urls = []
         if methods is None:
@@ -220,12 +240,12 @@ class PageMeta(type):
 
 
 class PageBase(metaclass=PageMeta):
-    url = None
-    name = None
+    url: str | None = None
+    name: str | None = None
     # Semantic icon name resolved per icon mode (see icons.ICONS). Apps may
     # override with their own semantic name or a raw icon string.
     icon = "page"
-    endpoint = None
+    endpoint: str | None = None
     # Page-wide auth defaults (only enforced when an AuthProvider is configured).
     # Set ``login_required = False`` to make every route on the page public, or
     # ``required_groups = [...]`` to gate every route — including RCRUD
@@ -233,6 +253,11 @@ class PageBase(metaclass=PageMeta):
     # decorators override these.
     login_required = True
     required_groups = None
+    # Capability asked before every custom @expose route that accepts a
+    # writing method (POST/PUT/PATCH/DELETE) and declares none of its own —
+    # e.g. ``write_capability = "write"`` with a ``can_write(self)`` hook.
+    # Fail-closed for routes added later; ``capability=False`` opts one out.
+    write_capability: str | None = None
 
     def __init__(self, static_folder=None, static_url_path=None, menu=None):
         self.name = self.name or self.__class__.__name__.capitalize()
@@ -333,13 +358,32 @@ class PageBase(metaclass=PageMeta):
 
             url = apply_trailing_slash(url, construct)
 
-            self.blueprint.add_url_rule(url, name, getattr(self, name), **kwargs)
+            view = getattr(self, name)
+            capability = route_capability(type(self), name, methods)
+            if capability is not None:
+                view = guard_route(
+                    self,
+                    view,
+                    capability,
+                    url,
+                    self._capability_row_reader(),
+                    f"{type(self).__name__}.{name}",
+                )
+            self.blueprint.add_url_rule(url, name, view, **kwargs)
 
         return self.blueprint
 
     def _run_view(self, f, *args, **kwargs):
         return f(self, *args, **kwargs)
 
+    def _capability_row_reader(self):
+        """``read(id)`` for row capabilities on custom routes, or ``None``
+        when the page has no dataclass to read a record from."""
+        dataclass = getattr(self, "dataclass", None)
+        if dataclass is None:
+            return None
+        return lambda id: dataclass().read(id)
+
 
 class ComponentPageBase(PageBase):
     """Base class for component-based pages."""
@@ -488,7 +532,7 @@ class ComponentPageBase(PageBase):
 
     def _register_live_endpoints(self, blueprint, construct):
 
-        for source_name, (method, interval) in self.livesources.items():
+        for source_name, (method, _interval) in self.livesources.items():
 
             def make_poll_view(m, sname, page_self):
                 def poll_view():
@@ -766,7 +810,7 @@ class ExtensionsPage(ComponentPageBase):
                 bg_color = "var(--fcu-secondary)"
                 text_color = "var(--fcu-on-secondary)"
 
-            status_badge = Markup(  # nosemgrep: explicit-unescape-with-markup  # nosec B704
+            status_badge = Markup(  # nosemgrep: explicit-unescape-with-markup  # nosec B704  # noqa: S704
                 f'<span style="background-color: {bg_color}; color: {text_color}; '
                 f"padding: 2px 6px; border-radius: var(--fcu-border-radius); font-size: var(--fcu-font-size-sm); "
                 f'font-weight: bold; display: inline-block;">{status}</span>'
@@ -809,7 +853,7 @@ class ExtensionsPage(ComponentPageBase):
 
 class FlaskConstructUI(MenuMixin):
     app = None
-    index_view_class = BaseIndexView
+    index_view_class: type[PageBase] | None = BaseIndexView
 
     def __init__(
         self,
@@ -833,8 +877,15 @@ class FlaskConstructUI(MenuMixin):
         strict_slashes=None,
         check_trailing_slashes=False,
         enforce_trailing_slash=True,
+        app_l10n_dir=None,
+        live=None,
+        error_statuses=None,
     ):
         self._pages = []
+        # Domain exception class -> status (or callable); see add_error_status.
+        self._error_statuses = {}
+        for exc_class, status in (error_statuses or {}).items():
+            self.add_error_status(exc_class, status)
         self._init_menu(menu_poll)
         self._blueprint_names = set()
         self._pages_by_endpoint = {}
@@ -850,9 +901,18 @@ class FlaskConstructUI(MenuMixin):
         # `app.l10n` (only then is it safe to rebuild its search path).
         self._l10n_dirs = []
         self._owns_l10n = False
+        # The application's own catalog directory. None means "find it": see
+        # app_l10n_paths. Not to be confused with the `l10n_dir` property,
+        # which is the library's catalog.
+        self._app_l10n_dir = app_l10n_dir
+        self._app_l10n_resolved = None
         self._auth = auth
         self._search = search
         self._notifications = notifications
+        # The change feed behind live_refresh() (see live.py), or None. May
+        # also be assigned after construction: the route and the marker read
+        # it per request.
+        self.live = live
         # The only structural theme is `whitelabel`; `theme=` is still accepted
         # for backward compatibility but no longer selects templates or assets.
         # Whenever no design is given we fill in `adminlte`, which reproduces
@@ -933,7 +993,7 @@ class FlaskConstructUI(MenuMixin):
             app.cli.add_command(make_cli(self))
         if not hasattr(app, "l10n"):
             # Only add if not already added by the app.
-            app.l10n = Translator()
+            app.l10n = Translator()  # type: ignore[attr-defined]
             self._owns_l10n = True
             self._apply_l10n_paths()
             app.before_request(set_language_from_browser)
@@ -954,6 +1014,9 @@ class FlaskConstructUI(MenuMixin):
 
         app_hooks.register_features_blueprint(self)
 
+        for exc_class, status in self._error_statuses.items():
+            app.register_error_handler(exc_class, make_error_handler(status, self))
+
     def load_extensions(self):
         """Discover and load companion libraries via entry points in the
         group 'flask_construct_ui.extensions'.
@@ -964,7 +1027,7 @@ class FlaskConstructUI(MenuMixin):
             # Fallback for older python / importlib_metadata select API compatibility
             try:
                 eps = entry_points().select(group="flask_construct_ui.extensions")
-            except Exception:
+            except Exception:  # noqa: BLE001 - no extensions rather than no app
                 eps = []
 
         for ep in eps:
@@ -1000,7 +1063,7 @@ class FlaskConstructUI(MenuMixin):
             except Exception as e:
                 ext_info["status"] = "Error"
                 ext_info["error"] = str(e)
-                logger.error(f"Failed to load extension {ep.name}: {e}", exc_info=True)
+                logger.exception("Failed to load extension %s: %s", ep.name, e)
             self._extensions.append(ext_info)
 
         if self._extensions:
@@ -1053,8 +1116,10 @@ class FlaskConstructUI(MenuMixin):
             if not path.endswith("/"):
                 warnings.append((rule.rule, rule.endpoint))
                 app.logger.warning(
-                    f"Construct UI: Route '{rule.rule}' (endpoint '{rule.endpoint}') "
-                    f"does not end with a trailing slash '/'. This may cause 308 redirects."
+                    "Construct UI: Route '%s' (endpoint '%s') does not end with "
+                    "a trailing slash '/'. This may cause 308 redirects.",
+                    rule.rule,
+                    rule.endpoint,
                 )
         return warnings
 
@@ -1098,12 +1163,53 @@ class FlaskConstructUI(MenuMixin):
     def _apply_l10n_paths(self):
         """(Re)build the translator's search path.
 
-        Precedence, highest first: the application's own ``l10n/``, then any
-        directories registered by companion libraries (in registration order),
-        then the library defaults. Only meaningful when this construct owns
+        Precedence, highest first: the application's own ``l10n/`` (see
+        ``app_l10n_paths``), then any directories registered by companion
+        libraries (in registration order), then the library defaults. Only meaningful when this construct owns
         ``app.l10n`` (the host app didn't supply its own).
         """
-        self.app.l10n.set_languages(["l10n", *self._l10n_dirs, self.l10n_dir])
+        # Resolved once: the cwd fallback means "the cwd at startup", and
+        # add_l10n_dir rebuilds must not repeat the warning.
+        if self._app_l10n_resolved is None:
+            self._app_l10n_resolved = self.app_l10n_paths()
+        self.app.l10n.set_languages(
+            [*self._app_l10n_resolved, *self._l10n_dirs, self.l10n_dir]
+        )
+
+    def app_l10n_paths(self):
+        """The directories searched for the application's own catalogs.
+
+        An explicit ``app_l10n_dir=`` is resolved against ``app.root_path``
+        (so an absolute path is used as-is). Otherwise ``l10n/`` next to the
+        app package (``app.root_path``) is searched first, then ``l10n/`` in
+        the working directory as a compatibility fallback. The fallback is
+        what breaks when a server is started from another directory, so
+        finding the catalog *only* there logs a warning.
+        """
+        root = self.app.root_path
+        if self._app_l10n_dir is not None:
+            explicit = path.abspath(path.join(root, self._app_l10n_dir))
+            if not path.isdir(explicit):
+                logger.warning(
+                    "app_l10n_dir %r does not exist; application labels will "
+                    "not be translated",
+                    explicit,
+                )
+            return [explicit]
+        beside_app = path.join(root, "l10n")
+        in_cwd = path.abspath("l10n")
+        if path.abspath(beside_app) == in_cwd:
+            return [in_cwd]
+        if path.isdir(in_cwd) and not path.isdir(beside_app):
+            logger.warning(
+                "Application l10n directory found only relative to the "
+                "working directory (%s); it will be missed when the app is "
+                "started from elsewhere. Move it to %s or pass "
+                "FlaskConstructUI(app_l10n_dir=...).",
+                in_cwd,
+                beside_app,
+            )
+        return [beside_app, in_cwd]
 
     def add_l10n_dir(self, path):
         """Register an extra l10n directory, e.g. one shipped by a companion
@@ -1121,6 +1227,28 @@ class FlaskConstructUI(MenuMixin):
         if self.app is not None and self._owns_l10n:
             self._apply_l10n_paths()
 
+    def add_error_status(self, exc_class, status):
+        """Answer *exc_class* (and subclasses), raised from any route, with the
+        themed error page instead of a 500.
+
+        *status* is an HTTP status (``404``) or a callable taking the exception
+        and returning a status or a ``(status, message)`` pair; *message* is
+        translated and shown in place of the status's default explanation::
+
+            fcu.add_error_status(NotFound, 404)
+            fcu.add_error_status(CommandError, lambda e: (e.status, e.message))
+
+        The page renders in the current layout, so an Unpoly fragment request
+        gets the partial. 403 is the same access-denied page a capability
+        refusal shows. It is a plain Flask error handler on the app, so
+        Flask's rules apply: the most specific registered class wins, and an
+        ``app.errorhandler`` of your own for the same class replaces it.
+        """
+        check_error_mapping(exc_class, status)
+        self._error_statuses[exc_class] = status
+        if self.app is not None:
+            self.app.register_error_handler(exc_class, make_error_handler(status, self))
+
     def add_stylesheet(self, sheet):
         """Register an application stylesheet to link in every full page render.
 
@@ -1360,7 +1488,7 @@ class FlaskConstructUI(MenuMixin):
         """
         try:
             name = (self.titleFromLink or "").strip()
-        except Exception:  # pragma: no cover - defensive
+        except Exception:  # pragma: no cover  # noqa: BLE001 - defensive
             return self.title
         if not name or name == self.title:
             return self.title
@@ -1378,7 +1506,7 @@ class FlaskConstructUI(MenuMixin):
         """
         try:
             name = (self.titleFromLink or "").strip()
-        except Exception:  # pragma: no cover - defensive
+        except Exception:  # pragma: no cover  # noqa: BLE001 - defensive
             name = ""
         return self.t(name) if name else self.title