flask-construct-ui 0.9.5__tar.gz

flask_construct_ui-0.9.5/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

flask_construct_ui-0.9.5/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: flask-construct-ui
+Version: 0.9.5
+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
+Project-URL: Repository, https://gitlab.com/Resample2545/flask-construct-ui
+Project-URL: Issues, https://gitlab.com/Resample2545/flask-construct-ui/-/issues
+Keywords: flask,ui,crud,components,admin,web
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Flask
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask
+Requires-Dist: fluent-runtime>=0.4.0
+Requires-Dist: nh3
+Requires-Dist: pygal
+Requires-Dist: markdown-it-py
+Requires-Dist: SQLAlchemy
+Requires-Dist: orgparse
+Provides-Extra: security
+Requires-Dist: flask-security-too; extra == "security"
+Provides-Extra: oidc
+Requires-Dist: flask-oidc; extra == "oidc"
+Dynamic: license-file
+
+# Flask-Construct-UI
+
+A UI toolkit for Flask with CRUD and component features.
+
+## Installation
+
+```
+uv add "flask-construct-ui @ git+ssh://git@git.home.lan/OpenSource/flask-construct-ui.git"
+```
+
+## Usage
+
+```python
+from flask import Flask
+from flask_construct_ui import FlaskConstructUI
+
+app = Flask(__name__)
+construct = FlaskConstructUI(app)
+```
+
+
+
+

flask_construct_ui-0.9.5/README.md

@@ -0,0 +1,23 @@
+# Flask-Construct-UI
+
+A UI toolkit for Flask with CRUD and component features.
+
+## Installation
+
+```
+uv add "flask-construct-ui @ git+ssh://git@git.home.lan/OpenSource/flask-construct-ui.git"
+```
+
+## Usage
+
+```python
+from flask import Flask
+from flask_construct_ui import FlaskConstructUI
+
+app = Flask(__name__)
+construct = FlaskConstructUI(app)
+```
+
+
+
+

flask_construct_ui-0.9.5/flask_construct_ui/__init__.py

@@ -0,0 +1,82 @@
+from .base import FlaskConstructUI as FlaskConstructUI
+from .base import PageBase as PageBase
+from .crud import CrudPageBase as CrudPageBase, RelatedCrudTab as RelatedCrudTab
+from .base import BaseIndexView as BaseIndexView
+from .base import expose as expose
+from .base import list_action as list_action
+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 SSE_DONE as SSE_DONE
+
+# Component-based pages and the component library. Exposed at the package root
+# so ComponentPageBase apps and companion/extension authors can build UI from
+# component trees without reaching into submodules. The `components` namespace
+# (e.g. ``components.Card(...)``) is the idiomatic accessor; the individual
+# classes are exported too for explicit imports and type hints.
+from .base import ComponentPageBase as ComponentPageBase
+from .components import (
+    components as components,
+    Component as Component,
+    Field as Field,
+    ChartType as ChartType,
+    find_component as find_component,
+    find_component_by_id as find_component_by_id,
+    LiveComponent as LiveComponent,
+    VerticalLayoutComponent as VerticalLayoutComponent,
+    HorizontalLayoutComponent as HorizontalLayoutComponent,
+    GridLayoutComponent as GridLayoutComponent,
+    CardComponent as CardComponent,
+    TabsComponent as TabsComponent,
+    FormComponent as FormComponent,
+    ChartComponent as ChartComponent,
+    TextComponent as TextComponent,
+    MarkupComponent as MarkupComponent,
+    RichTextComponent as RichTextComponent,
+    ButtonComponent as ButtonComponent,
+    TableComponent as TableComponent,
+    CalendarComponent as CalendarComponent,
+)
+
+# Authentication & authorization
+from .auth import (
+    AuthProvider as AuthProvider,
+    FlaskSecurityAuth as FlaskSecurityAuth,
+    FlaskOIDCAuth as FlaskOIDCAuth,
+    public as public,
+    require_groups as require_groups,
+)
+
+# Navbar features
+from .navbar import (
+    NavbarFeature as NavbarFeature,
+    GlobalSearch as GlobalSearch,
+    Notifications as Notifications,
+    Notice as Notice,
+    SearchResult as SearchResult,
+)
+
+# from .data_sqlalchemy import DataSQLAlchemy
+from .schema import dataschema as dataschema
+from .schema import schema as schema
+from .schema import SchemaField as SchemaField
+
+# Icon registry (for extension/companion libraries)
+from .icons import (
+    register_icons as register_icons,
+    render_icon as render_icon,
+    ICONS as ICONS,
+)
+
+# Headless sub-library helpers
+from .headless import (
+    sse_event as sse_event,
+    sse_response as sse_response,
+    live_attributes as live_attributes,
+    live_container as live_container,
+)
+
+# 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.9.5/flask_construct_ui/auth.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from flask import (
+    abort,
+    current_app,
+    g,
+    redirect,
+    render_template,
+    request,
+    url_for,
+)
+
+# --- Authentication & authorization ---------------------------------------
+# Construct routes are guarded fail-closed: once an ``AuthProvider`` is passed
+# to ``FlaskConstructUI(auth=...)`` every construct-owned route requires login
+# by default. Routes opt out with ``@public`` (or a page-wide
+# ``login_required = False``) and opt up with ``@require_groups(...)`` (or a
+# page-wide ``required_groups``). The enforcement point is a blueprint-scoped
+# ``before_request`` in ``base.py`` (see ``auth_protect``), which is why this
+# covers the dynamically-registered RCRUD nested routes too.
+#
+# The boundary is server-side, so it behaves identically with JavaScript on or
+# off: an unauthenticated request gets a plain 302 to the login endpoint (a
+# browser follows it without JS; Unpoly follows it too) and an authenticated
+# request lacking the required group gets a server-rendered themed 403 page.
+
+
+def public(f):
+    """Mark a view as not login-protected (reachable while unauthenticated)."""
+    f._construct_auth = {"public": True}
+    return f
+
+
+def require_groups(*groups, mode="any"):
+    """Require the current user to belong to the given group(s).
+
+    ``mode="any"`` (default) passes if the user is in at least one of
+    ``groups``; ``mode="all"`` requires membership in every one. Implies login.
+    """
+
+    def wrap(f):
+        f._construct_auth = {"groups": tuple(groups), "mode": mode}
+        return f
+
+    return wrap
+
+
+class AuthProvider:
+    """Adapter between Construct's route guard and a host auth stack.
+
+    Subclasses only need to answer two questions — ``is_authenticated`` and
+    ``current_groups``. The response helpers below are concrete and Unpoly-aware
+    and are rarely overridden. Ship-with adapters: :class:`FlaskSecurityAuth`,
+    :class:`FlaskOIDCAuth`. Write a custom one by subclassing this.
+    """
+
+    #: Flask endpoint name (or literal path) to send unauthenticated users to.
+    #: Overridden by the ``CONSTRUCT_LOGIN_ENDPOINT`` config when set.
+    login_endpoint = None
+
+    def is_authenticated(self) -> bool:
+        raise NotImplementedError
+
+    def current_groups(self) -> set[str]:
+        """Return the set of group/role names the current user belongs to."""
+        return set()
+
+    def has_groups(self, required, mode="any") -> bool:
+        have = self.current_groups()
+        if mode == "all":
+            return all(g in have for g in required)
+        return any(g in have for g in required)
+
+    def current_user_name(self) -> str | None:
+        """Display name for the logged-in user, or None if unavailable."""
+        return None
+
+    def current_user(self) -> dict | None:
+        """Normalized view of the logged-in user, or None if unauthenticated.
+
+        Returns a dict with at least ``name`` (display name) and ``groups``
+        (a ``set`` of group/role names) keys. Adapters override this to fold in
+        provider-specific claims (e.g. ``email``, ``sub``). Application code
+        should prefer this -- or the conveniences built on it,
+        ``PageBase.current_user`` and the ``current_user`` template global --
+        over reaching into a provider's native session, so it stays portable
+        across auth stacks.
+        """
+        if not self.is_authenticated():
+            return None
+        return {
+            "name": self.current_user_name(),
+            "groups": self.current_groups(),
+        }
+
+    def user_menu_items(self) -> list[dict]:
+        """Items for the user dropdown menu.
+
+        Each dict must have ``label`` and ``url`` keys; ``icon`` is optional
+        and may be a semantic icon name (see ``icons.ICONS``) or a raw glyph;
+        it is rendered in the active icon mode (Material Symbols by default,
+        Bootstrap Icons under the ``adminlte`` design).
+        """
+        return []
+
+    # -- response helpers ---------------------------------------------------
+
+    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
+        try:
+            return url_for(target, next=nxt)
+        except Exception:
+            # Not a known endpoint — treat it as a literal path.
+            sep = "&" if "?" in target else "?"
+            return f"{target}{sep}next={nxt}"
+
+    def on_unauthenticated(self):
+        """Default: 302 redirect to the login URL (401 if none configured)."""
+        url = self.login_url()
+        if url is None:
+            abort(401)
+        return redirect(url)
+
+    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
+
+
+class FlaskSecurityAuth(AuthProvider):
+    """Adapter for Flask-Security(-Too): ``current_user`` + role relationship."""
+
+    login_endpoint = "security.login"
+
+    def is_authenticated(self) -> bool:
+        from flask_security import current_user  # lazy: optional dependency
+
+        return bool(current_user.is_authenticated)
+
+    def current_groups(self) -> set[str]:
+        from flask_security import current_user
+
+        if not current_user.is_authenticated:
+            return set()
+        return {role.name for role in current_user.roles}
+
+    def current_user_name(self) -> str | None:
+        from flask_security import current_user
+
+        if not current_user.is_authenticated:
+            return None
+        return getattr(current_user, "username", None) or getattr(
+            current_user, "email", None
+        )
+
+    def current_user(self) -> dict | None:
+        from flask_security import current_user
+
+        if not current_user.is_authenticated:
+            return None
+        return {
+            "name": self.current_user_name(),
+            "groups": self.current_groups(),
+            "id": getattr(current_user, "id", None),
+            "username": getattr(current_user, "username", None),
+            "email": getattr(current_user, "email", None),
+        }
+
+    def user_menu_items(self) -> list[dict]:
+        try:
+            from flask import url_for
+
+            return [
+                {
+                    "label": "Sign out",
+                    "url": url_for("security.logout"),
+                    "icon": "logout",
+                }
+            ]
+        except Exception:
+            return []
+
+
+class FlaskOIDCAuth(AuthProvider):
+    """Adapter for Flask-OIDC: login state + group/role claims from the token.
+
+    ``oidc`` is the application's ``OpenIDConnect`` instance. ``groups_claim`` is
+    the claim carrying the user's groups/roles — on Flask-OIDC 2.x this is read
+    from the userinfo response (so the IdP must include it there, with
+    ``OIDC_USER_INFO_ENABLED`` on), on older builds from the decoded id-token.
+    Flask-OIDC's claim API differs across major versions, so claim access is
+    isolated in :meth:`current_groups` to make it easy to adapt. The default
+    ``login_endpoint`` matches Flask-OIDC 2.x, which registers its routes under
+    the ``oidc_auth`` blueprint.
+    """
+
+    def __init__(
+        self,
+        oidc,
+        groups_claim="groups",
+        login_endpoint="oidc_auth.login",
+        logout_endpoint="oidc_auth.logout",
+    ):
+        self.oidc = oidc
+        self.groups_claim = groups_claim
+        self.login_endpoint = login_endpoint
+        self.logout_endpoint = logout_endpoint
+
+    def is_authenticated(self) -> bool:
+        return bool(getattr(self.oidc, "user_loggedin", False))
+
+    def _claims(self) -> dict:
+        """Best-effort full claim set for the current user.
+
+        Flask-OIDC 2.x stores the userinfo response in the session under
+        ``oidc_auth_profile``; older builds keep the decoded id-token on
+        ``flask.g``. Returns ``{}`` when neither is present (or when called
+        outside a request context).
+        """
+        try:
+            from flask import session
+
+            profile = session.get("oidc_auth_profile")
+            if isinstance(profile, dict):
+                return profile
+            token = g.get("oidc_id_token", None)
+            if isinstance(token, dict):
+                return token
+        except RuntimeError:
+            pass
+        return {}
+
+    def current_groups(self) -> set[str]:
+        if not self.is_authenticated():
+            return set()
+        # Newer Flask-OIDC exposes claims via user_getfield; older builds keep
+        # the decoded id-token on flask.g. Prefer the accessor when present.
+        getter = getattr(self.oidc, "user_getfield", None)
+        if getter is not None:
+            return set(getter(self.groups_claim) or [])
+        token = g.get("oidc_id_token", None)
+        if isinstance(token, dict):
+            return set(token.get(self.groups_claim) or [])
+        return set()
+
+    def current_user_name(self) -> str | None:
+        if not self.is_authenticated():
+            return None
+        getter = getattr(self.oidc, "user_getfield", None)
+        if getter is not None:
+            return getter("name") or getter("email")
+        token = g.get("oidc_id_token", None)
+        if isinstance(token, dict):
+            return token.get("name") or token.get("email")
+        return None
+
+    def current_user(self) -> dict | None:
+        if not self.is_authenticated():
+            return None
+        # Start from the full claim set so callers get email/sub/custom claims
+        # without reaching into Flask-OIDC's session, then overlay the
+        # normalized name/groups so the shape matches other adapters.
+        user = dict(self._claims())
+        user["name"] = self.current_user_name()
+        user["groups"] = self.current_groups()
+        return user
+
+    def user_menu_items(self) -> list[dict]:
+        try:
+            from flask import url_for
+
+            return [
+                {
+                    "label": "Sign out",
+                    "url": url_for(self.logout_endpoint),
+                    "icon": "logout",
+                }
+            ]
+        except Exception:
+            return []