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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flask-construct-ui
-Version: 0.11.0
+Version: 0.11.2
 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
@@ -32,6 +32,8 @@ Requires-Dist: SQLAlchemy
 Requires-Dist: orgparse
 Provides-Extra: oidc
 Requires-Dist: flask-oidc; extra == "oidc"
+Provides-Extra: session
+Requires-Dist: flask-session[redis]; extra == "session"
 Dynamic: license-file
 
 # Flask-Construct-UI

{flask_construct_ui-0.11.0 → flask_construct_ui-0.11.2}/flask_construct_ui/__init__.py

@@ -54,6 +54,19 @@ from .auth import (
     require_groups as require_groups,
 )
 
+# Resuming an interrupted request after re-authentication. Public because an
+# app has links and forms the library never sees; see resume.py.
+from .resume import (
+    return_target as return_target,
+    stash_form_data as stash_form_data,
+    peek_form_data as peek_form_data,
+    take_form_data as take_form_data,
+    clear_form_data as clear_form_data,
+    resumed_value as resumed_value,
+    resumed_values as resumed_values,
+    has_resumable_form as has_resumable_form,
+)
+
 # Navbar features
 from .navbar import (
     NavbarFeature as NavbarFeature,

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

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import hashlib
+from functools import wraps
+from urllib.parse import quote, urlencode, urlparse
 
 from flask import (
     abort,
@@ -14,6 +16,9 @@ from flask import (
 )
 from markupsafe import escape
 
+from .navigation import is_safe_next
+from .resume import SAFE_METHODS, return_target, stash_form_data
+
 # --- Authentication & authorization ---------------------------------------
 # Construct routes are guarded fail-closed: once an ``AuthProvider`` is passed
 # to ``FlaskConstructUI(auth=...)`` every construct-owned route requires login
@@ -168,21 +173,37 @@ class AuthProvider:
 
     # -- response helpers ---------------------------------------------------
 
+    def return_target(self) -> str | None:
+        """Where to send the reader once they are logged in again, or None.
+
+        Delegates to :func:`flask_construct_ui.resume.return_target`: a GET is
+        its own target, anything else falls back to the page it was submitted
+        from. Override to apply a policy of your own — every redirect the
+        library builds for an interrupted request goes through here.
+        """
+        return return_target()
+
     def login_url(self):
         """Resolve the login URL, carrying ``next`` back to this request."""
         target = (
             current_app.config.get("CONSTRUCT_LOGIN_ENDPOINT") or self.login_endpoint
         )
-        nxt = request.full_path.rstrip("?")
         if not target:
             # No login endpoint configured: fall back to a bare 401.
             return None
+        nxt = self.return_target()
         try:
-            return url_for(target, next=nxt)
+            return url_for(target, next=nxt) if nxt else url_for(target)
         except Exception:
             # Not a known endpoint — treat it as a literal path.
+            if not nxt:
+                return target
             sep = "&" if "?" in target else "?"
-            return f"{target}{sep}next={nxt}"
+            # urlencode, not interpolation: a target carrying "&" or "#"
+            # (both legal in a path, and "?" appears in every full_path with
+            # a query) would otherwise truncate the parameter. "/" stays
+            # literal so the common case reads as a path.
+            return f"{target}{sep}{urlencode({'next': nxt}, safe='/')}"
 
     def on_unauthenticated(self):
         """Send the user to the login page (401 when none is configured).
@@ -200,7 +221,13 @@ class AuthProvider:
         :data:`LOGIN_HEADER`, which ``construct-core.js`` turns into a full
         page navigation. The small body is a no-JS-style fallback for the case
         where the response is rendered anyway.
+
+        A refused state-changing request is also the last moment its body
+        exists, so it is stashed first (see :mod:`.resume`) — otherwise the
+        reader logs back in, lands on the right form, and finds it empty.
         """
+        if request.method not in SAFE_METHODS:
+            stash_form_data()
         url = self.login_url()
         if url is None:
             abort(401)
@@ -286,17 +313,117 @@ class FlaskOIDCAuth(AuthProvider):
     the ``oidc_auth`` blueprint.
     """
 
+    #: Characters Flask-OIDC's own ``validate_return_url`` accepts in a
+    #: ``next``, and the most it accepts of them. Anything outside this — a
+    #: comma, a semicolon, a bracket, all legal in a query string and all
+    #: reachable from a construct list URL — is *silently* replaced with the
+    #: site root, on the way in to ``/oidc/login`` as much as on the way out
+    #: through ``/oidc/logout``. So a target is percent-encoded into that
+    #: alphabet before it is handed over (see :meth:`_oidc_return_url`).
+    OIDC_RETURN_URL_SAFE = ":/.-@%?!&+#_=*~'"
+    OIDC_RETURN_URL_MAX = 256
+
     def __init__(
         self,
         oidc,
         groups_claim="groups",
         login_endpoint="oidc_auth.login",
         logout_endpoint="oidc_auth.logout",
+        return_after_expiry=True,
     ):
         self.oidc = oidc
         self.groups_claim = groups_claim
         self.login_endpoint = login_endpoint
         self.logout_endpoint = logout_endpoint
+        if return_after_expiry:
+            self._keep_return_target(oidc)
+
+    # -- surviving an expired token -----------------------------------------
+
+    def _keep_return_target(self, oidc):
+        """Carry the requested page through Flask-OIDC's expired-token bounce.
+
+        Flask-OIDC answers a token it cannot refresh with a redirect to its
+        logout route carrying only ``reason=expired``; that route's ``next``
+        then defaults to the site root, so the page the reader asked for is
+        thrown away before the route guard (which *does* build a ``next``)
+        ever sees the request. ``user_loggedin`` is true while the dead token
+        still sits in the session, which is why the guard is not consulted at
+        all — and why neither hook ordering nor a construct-side check can fix
+        this from the outside.
+
+        Wrapping needs no import of Flask-OIDC: ``_before_request`` calls
+        ``self.check_token_expiry()``, which resolves on the instance first,
+        and the adapter is handed the instance. That matters because
+        ``flask-oidc`` is an optional extra.
+
+        Opt out with ``return_after_expiry=False`` — for an app that wants
+        Flask-OIDC's behavior verbatim, or already patches it itself.
+        """
+        original = getattr(oidc, "check_token_expiry", None)
+        if original is None:
+            return  # not a Flask-OIDC 2.x instance; nothing to wrap
+        if getattr(oidc, "_construct_return_target", False):
+            return  # already wrapped (two adapters over one instance)
+
+        @wraps(original)
+        def check_token_expiry():
+            response = original()
+            if response is None:
+                return None
+            target = self.expiry_return_target()
+            if not target:
+                return response
+            # The body is gone with the session either way, so save it here —
+            # this redirect is the last point the request still carries it.
+            # Filed under the *unencoded* target, because the GET that comes
+            # back to claim it is matched on ``request.path``, which Werkzeug
+            # hands over decoded.
+            if request.method not in SAFE_METHODS:
+                stash_form_data()
+            return redirect(
+                url_for(self.logout_endpoint, reason="expired", next=target)
+            )
+
+        oidc.check_token_expiry = check_token_expiry
+        oidc._construct_return_target = True
+
+    def _oidc_return_url(self, target: str | None) -> str | None:
+        """``target``, shaped so Flask-OIDC's own validator will keep it.
+
+        Percent-encoding into :attr:`OIDC_RETURN_URL_SAFE` is enough for the
+        character rule and changes nothing about where the URL points.
+        Length is not fixable that way, so an over-long target gives up its
+        query string rather than the page — the reader loses their filters and
+        page number, not the form they were filling in (the stash is filed by
+        path). ``%`` is left alone so an already-escaped path is not
+        double-encoded.
+        """
+        if not target:
+            return None
+        encoded = quote(target, safe=self.OIDC_RETURN_URL_SAFE)
+        if len(encoded) <= self.OIDC_RETURN_URL_MAX:
+            return encoded
+        path = quote(urlparse(target).path, safe=self.OIDC_RETURN_URL_SAFE)
+        return path if len(path) <= self.OIDC_RETURN_URL_MAX else None
+
+    def return_target(self) -> str | None:
+        return self._oidc_return_url(super().return_target())
+
+    def expiry_return_target(self) -> str | None:
+        """Where to send the reader after an expired session, or None.
+
+        A request on Flask-OIDC's own blueprint hands over its own ``next``
+        rather than itself: by the time we returned to ``/oidc/authorize`` its
+        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]:
+            nxt = request.args.get("next")
+            if not nxt or not is_safe_next(nxt):
+                return None
+            return self._oidc_return_url(nxt)
+        return self.return_target()
 
     def is_authenticated(self) -> bool:
         return bool(getattr(self.oidc, "user_loggedin", False))

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

@@ -14,6 +14,7 @@ from flask import (
     Response,
     current_app,
     g,
+    has_request_context,
     jsonify,
     render_template,
     request,
@@ -25,6 +26,15 @@ import jinja2
 from markupsafe import Markup
 
 from .auth import AUTH_STAMP_HEADER, auth_stamp
+from .resume import DEFAULT_MAX_BYTES as RESUME_MAX_BYTES
+from .resume import DEFAULT_SKIP_FIELDS as RESUME_SKIP_FIELDS
+from .resume import DEFAULT_TTL as RESUME_TTL
+from .resume import (
+    clear_on_successful_submit,
+    has_resumable_form,
+    resumed_value,
+    resumed_values,
+)
 from .components import (
     CalendarComponent,
     ChartComponent,
@@ -848,6 +858,7 @@ class FlaskConstructUI:
         theme=None,
         design=None,
         dark_mode=None,
+        stylesheets=None,
         auth=None,
         search=None,
         notifications=None,
@@ -881,6 +892,10 @@ class FlaskConstructUI:
         # 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"
+        # Remember whether the design was *filled in* rather than asked for.
+        # `effective_design` drops the implicit default once the app registers
+        # stylesheets of its own; an explicit choice is always honoured.
+        self._design_is_default = design is None
         if design is None:
             design = "adminlte"
         self.theme = theme
@@ -897,6 +912,12 @@ class FlaskConstructUI:
             )
         self.design = design
         self.dark_mode = dark_mode
+        # App-supplied stylesheets, linked last in <head> so they win the
+        # cascade over whitelabel.css and the active design. See
+        # `add_stylesheet` for the accepted entry forms.
+        self._stylesheets = []
+        for sheet in stylesheets or []:
+            self.add_stylesheet(sheet)
         self.static_url_path = static_url_path or "static"
         if static_folder is None:
             self.static_folder = path.join(path.dirname(__file__), "static")
@@ -935,6 +956,15 @@ class FlaskConstructUI:
         # provider's login_endpoint.
         app.config.setdefault("CONSTRUCT_AUTH_ENABLED", self._auth is not None)
         app.config.setdefault("CONSTRUCT_LOGIN_ENDPOINT", None)
+        # Resuming an interrupted request after re-authentication (see
+        # resume.py). The form stash rides in the Flask session, so it is
+        # bounded three ways: a byte cap (the cookie backend drops anything
+        # over 4 KB, taking the CSRF token with it), a lifetime, and a
+        # name-based skip list for values that must not be written there.
+        app.config.setdefault("CONSTRUCT_RESUME_FORMS", True)
+        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)
 
         @app.before_request
         def set_theme():
@@ -972,6 +1002,11 @@ class FlaskConstructUI:
             response.headers.setdefault(AUTH_STAMP_HEADER, auth_stamp(self._auth))
             return response
 
+        # A stash the library's own CRUD forms consume when they render it,
+        # but an app template using resumed_value() only reads — so retire it
+        # here once the form it belongs to has been submitted successfully.
+        app.after_request(clear_on_successful_submit)
+
         @app.before_request
         def csrf_protect():
             # Only guard state-changing requests against construct-owned
@@ -1064,6 +1099,11 @@ class FlaskConstructUI:
             t=translate,
             icon=render_icon,
             next_url=resolve_next,
+            # 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,
         )
         # Components render through their own standalone Jinja environment,
         # so the CSRF helpers, translator and icon renderer must be registered
@@ -1088,6 +1128,14 @@ class FlaskConstructUI:
             "construct_static",
             self.construct_static_path,
         )
+
+        # `flask fcu ...`. The commands resolve pages when they run, not here,
+        # so this does not care that add_page may be called later. An app that
+        # has already defined its own `fcu` group keeps it.
+        if "fcu" not in app.cli.commands:
+            from .cli import make_cli
+
+            app.cli.add_command(make_cli(self))
         if not hasattr(app, "l10n"):
             # Only add if not already added by the app.
             app.l10n = Translator()
@@ -1345,6 +1393,55 @@ class FlaskConstructUI:
         if self.app is not None and self._owns_l10n:
             self._apply_l10n_paths()
 
+    def add_stylesheet(self, sheet):
+        """Register an application stylesheet to link in every full page render.
+
+        This is the supported way to get your own CSS into the ``<head>``:
+        overriding ``structure/base.html`` just to add a ``<link>`` means
+        restating the library's internal full/partial layout selection, which
+        breaks whenever those layout paths move.
+
+        ``sheet`` is either
+
+        * a **string** URL, emitted verbatim — a root-relative path
+          (``"/static/css/brand.css"``) or an absolute one
+          (``"https://fonts.example/…"``); or
+        * a **callable** taking no arguments and returning such a URL. It is
+          invoked per request, inside the request context, so it can use
+          ``url_for`` — which is what you want when the app mounts its static
+          files somewhere non-default::
+
+              fcu.add_stylesheet(lambda: url_for("static", filename="css/brand.css"))
+
+        Sheets are linked in registration order, after every library-owned
+        stylesheet (whitelabel.css, the active design, grid.css), so app rules
+        and ``--fcu-*`` overrides win the cascade without ``!important``.
+        Duplicates are ignored. Only the full-page layout has a ``<head>``;
+        Unpoly partial swaps reuse the links already in the document.
+        """
+        if not isinstance(sheet, str) and not callable(sheet):
+            raise TypeError(
+                "stylesheet must be a URL string or a callable returning one; "
+                f"got {type(sheet).__name__}"
+            )
+        if sheet not in self._stylesheets:
+            self._stylesheets.append(sheet)
+
+    @property
+    def stylesheets(self):
+        """Resolved hrefs of the app stylesheets, in registration order.
+
+        Callables registered via ``add_stylesheet`` are evaluated here, i.e. at
+        render time within the request context. Entries resolving to something
+        falsy are skipped, so a callable may return None to opt out per request.
+        """
+        hrefs = []
+        for sheet in self._stylesheets:
+            href = sheet() if callable(sheet) else sheet
+            if href:
+                hrefs.append(href)
+        return hrefs
+
     def t(self, msg_id, args=None):
         return self.app.l10n.t(msg_id, args)
 
@@ -1420,13 +1517,25 @@ class FlaskConstructUI:
 
     @property
     def titleFromLink(self):
+        """Title of the menu entry matching the current route, or "".
+
+        Compared against ``request.path`` with trailing slashes normalised, the
+        same way the sidebar decides which link is current. (This used to read
+        a ``self.page`` attribute that has never existed on the extension, so
+        it raised on every call — harmless while nothing used it, and the cause
+        of an empty ``<title>`` once ``page_title`` started depending on it.)
+        """
+        if not has_request_context():
+            return ""
+        here = request.path.rstrip("/")
         for item in self.menu:
-            if item["type"] == "submenu":
-                for subitem in item["subitems"]:
-                    if "link" in subitem and subitem["link"] == self.page:
+            if item.get("type") == "submenu":
+                for subitem in item.get("subitems", []):
+                    link = subitem.get("link")
+                    if link and link.rstrip("/") == here:
                         return subitem["title"]
-
-            if "link" in item and item["link"] == self.page:
+            link = item.get("link")
+            if link and link.rstrip("/") == here:
                 return item["title"]
         return ""
 
@@ -1434,16 +1543,101 @@ class FlaskConstructUI:
     def l10n_dir(self):
         return path.join(path.dirname(__file__), "l10n")
 
+    @property
+    def effective_design(self):
+        """The design actually in force, which may differ from ``self.design``.
+
+        The one difference is the *implicit* ``adminlte`` default that fills in
+        for ``design=None``. An app that registers its own stylesheets is
+        skinning whitelabel itself, and a default skin underneath would fight
+        it: ``adminlte`` hard-codes a dark sidebar and light menu text that
+        ignore the ``--fcu-*`` tokens, so an app design setting its own sidebar
+        colour inherits unreadable menu text. Registering a stylesheet
+        therefore drops the default.
+
+        An *explicitly* requested design is always honoured — including
+        ``design="adminlte"`` — so layering app CSS on top of a library skin
+        stays possible. This reads ``_stylesheets`` (what was registered), not
+        ``stylesheets`` (what resolved this request), so a callable returning
+        None cannot make the default skin flicker back in.
+        """
+        if self._design_is_default and self._stylesheets:
+            return ""
+        return self.design
+
     @property
     def icon_mode(self):
         """Active icon-rendering mode ("bootstrap" or "material").
 
         Resolved from the theme, with any design override applied. Consumed by
-        the ``icon()`` template global (see ``icons.render_icon``).
+        the ``icon()`` template global (see ``icons.render_icon``). Keyed on
+        ``effective_design``: a design that is not applied must not impose its
+        icon library either, or the UI gets Bootstrap Icons with no AdminLTE
+        skin behind them.
         """
         from .icons import resolve_icon_mode
 
-        return resolve_icon_mode("whitelabel", self.design)
+        return resolve_icon_mode("whitelabel", self.effective_design)
+
+    @property
+    def language(self):
+        """BCP-47 code for the ``<html lang>`` attribute.
+
+        The negotiated request language (see ``language.set_language_from_browser``),
+        falling back to English outside a request or before negotiation has run.
+        Hard-coding ``lang="en"`` while serving translated content misdeclares
+        the page to screen readers, which pick their voice and pronunciation
+        rules from it (WCAG 3.1.1).
+        """
+        return g.get("language", None) or "en"
+
+    @property
+    def page_title(self):
+        """Default contents of ``<title>``: the current page plus the app name.
+
+        A distinct title per page is how a screen reader user confirms where a
+        navigation landed (WCAG 2.4.2). This is the fallback used by
+        ``base_full.html``; templates with more context (the CRUD list, create
+        and edit views) override ``{% block title %}`` instead, since they know
+        the record and action and this property does not.
+
+        The page name comes from the menu entry matching the current route, so
+        any menu-linked page gets a useful title with no view-layer changes.
+
+        Falls back to the app title on any resolution error: Jinja swallows an
+        exception raised in a property and renders nothing, and an empty
+        ``<title>`` is itself a Level A failure (2.4.2).
+        """
+        try:
+            name = (self.titleFromLink or "").strip()
+        except Exception:  # pragma: no cover - defensive
+            return self.title
+        if not name or name == self.title:
+            return self.title
+        return self.compose_title(self.t(name))
+
+    @property
+    def page_heading(self):
+        """Default ``<h1>`` text: the current page's name, else the app title.
+
+        Component pages compose their own content, so the library cannot know
+        which of their headings is the page heading — but every page needs
+        exactly one ``<h1>`` (2.4.6 / 1.3.1). The layouts render this one
+        visually hidden; a template that shows its own heading overrides
+        ``{% block page_heading %}`` instead (the CRUD views all do).
+        """
+        try:
+            name = (self.titleFromLink or "").strip()
+        except Exception:  # pragma: no cover - defensive
+            name = ""
+        return self.t(name) if name else self.title
+
+    def compose_title(self, name):
+        """Join a page-specific name to the app title for ``<title>``."""
+        name = (name or "").strip()
+        if not name or name == self.title:
+            return self.title
+        return f"{name} – {self.title}"
 
     @property
     def color_scheme(self):
@@ -1465,11 +1659,13 @@ class FlaskConstructUI:
         """Static path of the active design stylesheet, or None.
 
         Designs are shipped under ``static/designs/<design>.css``. Returns None
-        when no design is selected or the file does not exist on disk.
+        when no design is in force (see ``effective_design``) or the file does
+        not exist on disk.
         """
-        if not self.design:
+        design = self.effective_design
+        if not design:
             return None
-        rel = path.join("designs", f"{self.design}.css")
+        rel = path.join("designs", f"{design}.css")
         if not path.exists(path.join(self.static_folder, rel)):
             return None
         return rel.replace(path.sep, "/")