flask-construct-ui 0.10.2__tar.gz → 0.11.0__tar.gz

{flask_construct_ui-0.10.2 → flask_construct_ui-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-construct-ui
-Version: 0.10.2
+Version: 0.11.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.10.2 → flask_construct_ui-0.11.0}/flask_construct_ui/__init__.py

@@ -8,6 +8,7 @@ from .base import tab_action as tab_action
 from .base import edit_action as edit_action
 from .base import datasource as datasource
 from .base import livesource as livesource
+from .base import gridsource as gridsource
 from .base import SSE_DONE as SSE_DONE
 
 # Component-based pages and the component library. Exposed at the package root
@@ -36,6 +37,7 @@ from .components import (
     RichTextComponent as RichTextComponent,
     ButtonComponent as ButtonComponent,
     TableComponent as TableComponent,
+    GridComponent as GridComponent,
     CalendarComponent as CalendarComponent,
     KanbanComponent as KanbanComponent,
     KanbanColumn as KanbanColumn,

{flask_construct_ui-0.10.2 → flask_construct_ui-0.11.0}/flask_construct_ui/auth.py

@@ -216,10 +216,7 @@ class AuthProvider:
     def on_forbidden(self):
         """Default: render the themed access-denied page with HTTP 403."""
         construct = getattr(g, "construct", None)
-        theme = getattr(construct, "theme", None) or "whitelabel"
-        return render_template(
-            f"themes/{theme}/errors/forbidden.html", construct=construct
-        ), 403
+        return render_template("errors/forbidden.html", construct=construct), 403
 
 
 class FlaskSecurityAuth(AuthProvider):

{flask_construct_ui-0.10.2 → flask_construct_ui-0.11.0}/flask_construct_ui/base.py

@@ -1,59 +1,58 @@
 from __future__ import annotations
+
+from functools import wraps
+from importlib.metadata import entry_points
 import inspect
 import json
-from os import path
-from functools import wraps
 import logging
-from importlib.metadata import entry_points
-
-logger = logging.getLogger("flask_construct_ui")
+from os import path
+from typing import Callable, Optional
 
 from flask import (
-    Flask,
     Blueprint,
+    Flask,
+    Response,
+    current_app,
+    g,
+    jsonify,
     render_template,
-    send_from_directory,
     request,
-    url_for,
-    current_app,
-    Response,
+    send_from_directory,
     stream_with_context,
-    g,
+    url_for,
 )
+import jinja2
 from markupsafe import Markup
-from .language import Translator, set_language_from_browser
-from typing import Callable, Optional
+
+from .auth import AUTH_STAMP_HEADER, auth_stamp
 from .components import (
+    CalendarComponent,
+    ChartComponent,
     Component,
-    components,
     Field,
+    FormComponent,
     LiveComponent,
-    ChartComponent,
-    CalendarComponent,
     TabsComponent,
-    FormComponent,
+    components,
     jinja_env,
 )
-from .sanitize import sanitize_html
-from .headless import live_container, live_attributes
-from .navigation import resolve_next
-from .icons import render_icon
-
-
 from .csrf import (
-    CSRF_SESSION_KEY,
-    CSRF_FORM_FIELD,
-    CSRF_HEADER,
     CSRF_UNSAFE_METHODS,
-    generate_csrf_token,
     csrf_field,
+    generate_csrf_token,
     validate_csrf_token,
 )
+from .headless import live_attributes, live_container
+from .icons import render_icon
+from .language import Translator, set_language_from_browser
+from .navigation import resolve_next
 from .pagination import (
     DEFAULT_PAGE_SIZE,
     MAX_PAGE_SIZE,
 )
-from .auth import AUTH_STAMP_HEADER, auth_stamp
+from .sanitize import sanitize_html
+
+logger = logging.getLogger("flask_construct_ui")
 
 
 def list_action(name, icon):
@@ -113,6 +112,24 @@ def datasource(name=None):
 SSE_DONE = "done"
 
 
+def apply_trailing_slash(url, construct):
+    """Append a trailing slash to a generated route when the construct asks for it.
+
+    Left alone: the root, urls that already end in a slash, and last segments
+    that look like a filename — a static-file route must stay slash-free.
+    """
+    if not getattr(construct, "enforce_trailing_slash", False):
+        return url
+    if not url or url == "/" or url.endswith("/"):
+        return url
+    if not url.startswith("/"):
+        # An absolute or external link (a menu entry pointing off-site).
+        return url
+    if "." in url.rsplit("/", 1)[-1]:
+        return url
+    return url + "/"
+
+
 def livesource(name=None, interval=10):
     def wrap(f):
         f._livesource_name = name or f.__name__
@@ -122,6 +139,25 @@ def livesource(name=None, interval=10):
     return wrap
 
 
+def gridsource(name=None):
+    """Declare the datasource behind a :class:`GridComponent`.
+
+    The decorated method returns a :class:`~flask_construct_ui.data.DataBase`
+    instance; the page then registers the grid's row endpoints on its own
+    blueprint, so a component naming ``grid_source="tasks"`` needs no routes of
+    its own. An app that must own the routes (to apply its own authorization,
+    or to re-derive the configuration from somewhere the client cannot reach)
+    passes ``dataclass=``/``endpoint=`` to the component instead and drives a
+    :class:`~flask_construct_ui.grid.GridController` itself.
+    """
+
+    def wrap(f):
+        f._gridsource_name = name or f.__name__
+        return f
+
+    return wrap
+
+
 # Base views
 def _wrap_view(f):
     # Avoid wrapping view method twice
@@ -151,6 +187,7 @@ class PageMeta(type):
         cls.edit_actions = []
         cls._datasources = {}
         cls._livesources = {}
+        cls._gridsources = {}
         cls._auth_rules = {}
 
         for p in dir(cls):
@@ -162,6 +199,9 @@ class PageMeta(type):
             if hasattr(attr, "_livesource_name"):
                 cls._livesources[attr._livesource_name] = (p, attr._livesource_interval)
 
+            if hasattr(attr, "_gridsource_name"):
+                cls._gridsources[attr._gridsource_name] = p
+
             if hasattr(attr, "_construct_auth"):
                 cls._auth_rules[p] = attr._construct_auth
 
@@ -256,6 +296,10 @@ class PageBase(metaclass=PageMeta):
         for name, (method_name, interval) in self._livesources.items():
             self.livesources[name] = (getattr(self, method_name), interval)
 
+        self.gridsources = {}
+        for name, method_name in self._gridsources.items():
+            self.gridsources[name] = getattr(self, method_name)
+
     def t(self, msg_id, args=None):
         return self.construct.t(msg_id, args)
 
@@ -318,10 +362,7 @@ class PageBase(metaclass=PageMeta):
             if getattr(construct, "strict_slashes", None) is not None:
                 kwargs["strict_slashes"] = construct.strict_slashes
 
-            if getattr(construct, "enforce_trailing_slash", False):
-                if url != "/" and url != "" and not url.endswith("/"):
-                    if "." not in url.split("/")[-1]:
-                        url = url + "/"
+            url = apply_trailing_slash(url, construct)
 
             self.blueprint.add_url_rule(url, name, getattr(self, name), **kwargs)
 
@@ -339,8 +380,143 @@ class ComponentPageBase(PageBase):
     def get_blueprint(self, construct):
         blueprint = super().get_blueprint(construct)
         self._register_live_endpoints(blueprint, construct)
+        self._register_grid_endpoints(blueprint, construct)
         return blueprint
 
+    # -- grids ------------------------------------------------------------
+
+    def grid_can_write(self, source_name):
+        """Whether the current user may write through grid *source_name*.
+
+        The page's own ``login_required``/``required_groups`` already gate
+        every route on the blueprint, so this is the place for a narrower
+        rule — read for everyone, write for some. It is asked by the
+        endpoints, not only by the render, because a hidden button is not a
+        guard.
+        """
+        return True
+
+    def _grid_component(self, source_name):
+        """The grid naming *source_name*, located in a fresh ``definition()``.
+
+        Rebuilt per request rather than cached: the spec is the page's own
+        declaration and a client must never be able to hand one in, so the
+        only trustworthy copy is the one the page just built.
+        """
+        from .components import GridComponent
+
+        root = self.definition()
+        return self.find_component(
+            root,
+            lambda c: isinstance(c, GridComponent) and c.grid_source == source_name,
+        )
+
+    def _grid_controller(self, source_name):
+        """``(controller, error_response)`` for one grid request."""
+        from .grid import GridController, GridError
+
+        component = self._grid_component(source_name)
+        if component is None or source_name not in self.gridsources:
+            return None, ({"error": "not_found", "message": "No such grid"}, 404)
+        ds = self.gridsources[source_name]()
+        component.resolved_datasource = ds
+        try:
+            # apply_request=False: sort and column filters are the reader's
+            # display choices. Letting them reach a write would hand the
+            # client the filters that decide which rows it may touch.
+            spec = component.spec(ds, apply_request=False)
+        except GridError as error:
+            return None, ({"error": "bad_config", "message": error.fallback}, 500)
+        return (
+            GridController(
+                ds,
+                spec,
+                grid_id=component.state_id,
+                can_write=self.grid_can_write(source_name),
+            ),
+            None,
+        )
+
+    def _register_grid_endpoints(self, blueprint, construct):
+        """Row endpoints for every ``@gridsource`` on the page.
+
+        Three rules, mirroring the live endpoints: one JSON collection URL
+        (window + insert), one JSON member URL (patch + delete) and one form
+        URL for the JavaScript-free path. The form URL is a separate rule
+        because it answers with a redirect rather than JSON — a browser
+        submitting a plain form has to land on a page.
+        """
+        rule_kwargs = {}
+        if getattr(construct, "strict_slashes", None) is not None:
+            rule_kwargs["strict_slashes"] = construct.strict_slashes
+
+        def make_json_view(sname, with_row):
+            def view(row_id=None):
+                controller, failure = self._grid_controller(sname)
+                if failure is not None:
+                    return jsonify(failure[0]), failure[1]
+                return controller.handle_json(row_id)
+
+            view.__name__ = f"grid_{'row' if with_row else 'rows'}_{sname}"
+            return view
+
+        def make_form_view(sname):
+            def view():
+                controller, failure = self._grid_controller(sname)
+                if failure is not None:
+                    return jsonify(failure[0]), failure[1]
+                return controller.handle_form()
+
+            view.__name__ = f"grid_form_{sname}"
+            return view
+
+        for source_name in self.gridsources:
+            base = f"/grid/{source_name}/rows"
+            blueprint.add_url_rule(
+                base,
+                f"grid_rows_{source_name}",
+                make_json_view(source_name, False),
+                methods=["GET", "POST"],
+                **rule_kwargs,
+            )
+            blueprint.add_url_rule(
+                f"{base}/<row_id>",
+                f"grid_row_{source_name}",
+                make_json_view(source_name, True),
+                methods=["PATCH", "DELETE"],
+                **rule_kwargs,
+            )
+            blueprint.add_url_rule(
+                f"{base}/form",
+                f"grid_form_{source_name}",
+                make_form_view(source_name),
+                methods=["POST"],
+                **rule_kwargs,
+            )
+
+    def _resolve_gridsources(self, component: Component):
+        """Attach each grid's datasource and endpoint before it renders."""
+        from .components import GridComponent
+
+        if isinstance(component, GridComponent) and component.grid_source:
+            source_name = component.grid_source
+            if source_name in self.gridsources:
+                component.resolved_datasource = self.gridsources[source_name]()
+                if not component.endpoint:
+                    component.endpoint = url_for(
+                        f"{self.endpoint}.grid_rows_{source_name}"
+                    )
+                if not component.form_endpoint:
+                    component.form_endpoint = url_for(
+                        f"{self.endpoint}.grid_form_{source_name}"
+                    )
+                component.can_write = component.can_write and self.grid_can_write(
+                    source_name
+                )
+
+        for child in component.get_children():
+            self._resolve_gridsources(child)
+
     def _register_live_endpoints(self, blueprint, construct):
 
         for source_name, (method, interval) in self.livesources.items():
@@ -368,7 +544,15 @@ class ComponentPageBase(PageBase):
                         if inspect.isgenerator(result):
                             for item in result:
                                 yield f"event: update\ndata: {json.dumps(item)}\n\n"
-                            yield f"event: {SSE_DONE}\ndata: {json.dumps({'status': SSE_DONE})}\n\n"
+                            # `auto` tells the client this done was appended by
+                            # the library because the generator ran dry, not
+                            # yielded by the app to signal a finished job. The
+                            # client must not navigate on it: a finite generator
+                            # would otherwise reload its own page forever.
+                            yield (
+                                f"event: {SSE_DONE}\n"
+                                f"data: {json.dumps({'status': SSE_DONE, 'auto': True})}\n\n"
+                            )
                         else:
                             yield f"event: update\ndata: {json.dumps(result)}\n\n"
 
@@ -520,6 +704,7 @@ class ComponentPageBase(PageBase):
         root_component = self.definition()
         self._resolve_datasources(root_component)
         self._resolve_livesources(root_component)
+        self._resolve_gridsources(root_component)
         self._set_active_tabs(root_component)
         return self.render_component(root_component)
 
@@ -550,7 +735,7 @@ class ComponentPageBase(PageBase):
 
     def render_component(self, component: Component):
         return render_template(
-            f"themes/{self.construct.theme}/components/main.html",
+            "components/main.html",
             component=component,
             construct=self.construct,
         )
@@ -669,7 +854,7 @@ class FlaskConstructUI:
         discover_extensions=True,
         strict_slashes=None,
         check_trailing_slashes=False,
-        enforce_trailing_slash=False,
+        enforce_trailing_slash=True,
     ):
         self._pages = []
         self._menu = []
@@ -690,16 +875,14 @@ class FlaskConstructUI:
         self._auth = auth
         self._search = search
         self._notifications = notifications
-        # The only structural theme is `whitelabel`. When no theme is given we
-        # default to it wearing the `adminlte` design, which reproduces the look
-        # of the former `adminlte3` theme (the previous default) for apps that
-        # never set a theme. An app that *explicitly* selects `whitelabel`
-        # without a design gets the plain whitelabel look — so the design
-        # default only fills in for the no-theme case.
-        if theme is None:
-            theme = "whitelabel"
-            if design is None:
-                design = "adminlte"
+        # 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
+        # the look of the former `adminlte3` theme (the previous default). Pass
+        # a falsy design (e.g. `design=""`) for the plain whitelabel look.
+        theme = theme or "whitelabel"
+        if design is None:
+            design = "adminlte"
         self.theme = theme
         # `design` selects a built-in skin layered on top of the structural
         # theme's stylesheet (e.g. "adminlte" or "sandstone"). It does not
@@ -891,6 +1074,13 @@ class FlaskConstructUI:
             t=translate,
             icon=render_icon,
         )
+        if app.jinja_env.loader:
+            jinja_env.loader = jinja2.ChoiceLoader(
+                [
+                    app.jinja_env.loader,
+                    jinja2.PackageLoader("flask_construct_ui", "templates"),
+                ]
+            )
 
         self.app = app
         app.add_url_rule(
@@ -945,7 +1135,7 @@ class FlaskConstructUI:
                     q = request.args.get("q", "")
                     results = _search.search(q)
                     return render_template(
-                        f"themes/{g.construct_theme}/navbar/search_results.html",
+                        "navbar/search_results.html",
                         construct=_self,
                         results=results,
                         query=q,
@@ -958,7 +1148,7 @@ class FlaskConstructUI:
                     # Just the #fcu-notifications fragment; Unpoly's up-poll
                     # reloads it on a timer to keep the count + items fresh.
                     return render_template(
-                        f"themes/{g.construct_theme}/navbar/notifications.html",
+                        "navbar/notifications.html",
                         construct=_self,
                     )
 
@@ -1098,6 +1288,10 @@ class FlaskConstructUI:
                     )
                     + page.menu["link"]
                 )
+                # Menu links are assembled by hand rather than via url_for, so
+                # they need the same normalization the route patterns get —
+                # otherwise every sidebar entry 308-redirects to its own page.
+                menu["link"] = apply_trailing_slash(menu["link"], self)
                 if submenu is not None:
                     if submenu_icon is None:
                         self._add_to_submenu(submenu, menu)
@@ -1209,14 +1403,16 @@ class FlaskConstructUI:
     def search_url(self):
         if self._search is None:
             return None
-        return self.url.rstrip("/") + "/_construct/search"
+        return apply_trailing_slash(self.url.rstrip("/") + "/_construct/search", self)
 
     @property
     def notifications_url(self):
         """URL of the notifications fragment endpoint (for Unpoly polling)."""
         if self._notifications is None:
             return None
-        return self.url.rstrip("/") + "/_construct/notifications"
+        return apply_trailing_slash(
+            self.url.rstrip("/") + "/_construct/notifications", self
+        )
 
     @property
     def menu(self):
@@ -1247,7 +1443,7 @@ class FlaskConstructUI:
         """
         from .icons import resolve_icon_mode
 
-        return resolve_icon_mode(self.theme, self.design)
+        return resolve_icon_mode("whitelabel", self.design)
 
     @property
     def color_scheme(self):
@@ -1268,13 +1464,12 @@ class FlaskConstructUI:
     def design_stylesheet(self):
         """Static path of the active design stylesheet, or None.
 
-        Designs are shipped per structural theme under
-        ``static/themes/<theme>/designs/<design>.css``. Returns None when no
-        design is selected or the file does not exist on disk.
+        Designs are shipped under ``static/designs/<design>.css``. Returns None
+        when no design is selected or the file does not exist on disk.
         """
         if not self.design:
             return None
-        rel = path.join("themes", self.theme, "designs", f"{self.design}.css")
+        rel = path.join("designs", f"{self.design}.css")
         if not path.exists(path.join(self.static_folder, rel)):
             return None
         return rel.replace(path.sep, "/")