tina4-python 3.13.50__tar.gz → 3.13.52__tar.gz

{tina4_python-3.13.50 → tina4_python-3.13.52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.50
+Version: 3.13.52
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.50 → tina4_python-3.13.52}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.50"
+version = "3.13.52"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.50 → tina4_python-3.13.52}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.13.50"
+__version__ = "3.13.51"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.13.50 → tina4_python-3.13.52}/tina4_python/core/server.py

@@ -276,6 +276,12 @@ Router.add("GET", _HEALTH_PATH, _health_handler)
 if _HEALTH_PATH != "/health":
     Router.add("GET", "/health", _health_handler)
 
+# Frond live blocks: re-render a registered {% live %} fragment on demand.
+# Always on (production too) - the poll/sse client fetches this; auth re-applies
+# through the normal middleware chain on every refresh.
+from tina4_python.frond import live_endpoint as _live_endpoint
+Router.add("GET", "/__frond/live/{name}", _live_endpoint)
+
 
 def _render_error_page(status_code: int, path: str, request_id: str, error_message: str = "") -> str | None:
     """Render a styled error page using Frond engine.

{tina4_python-3.13.50 → tina4_python-3.13.52}/tina4_python/database/connection.py

@@ -110,6 +110,7 @@ except ImportError:
 from tina4_python.database.postgres import PostgreSQLAdapter
 register_driver("postgresql", PostgreSQLAdapter)
 register_driver("postgres", PostgreSQLAdapter)
+register_driver("pgsql", PostgreSQLAdapter)  # PDO / Laravel / Doctrine scheme name (issue #58)
 
 # Register MySQL (mysql-connector-python — optional)
 from tina4_python.database.mysql import MySQLAdapter

{tina4_python-3.13.50 → tina4_python-3.13.52}/tina4_python/dev_admin/__init__.py

@@ -320,8 +320,9 @@ def write_mcp_discovery_file() -> None:
     expected = {
         "mcpServers": {
             "tina4-live-docs": {
-                "url": f"http://localhost:{port}/__dev/api/mcp",
-                "description": "Live API docs for this Tina4 project (framework + user code)",
+                "type": "http",
+                "url": f"http://localhost:{port}/__dev/mcp",
+                "description": "Live API docs + dev tools for this Tina4 project (framework + user code)",
             }
         }
     }
@@ -485,11 +486,13 @@ def get_api_handlers() -> dict:
         # @mcp_tool decorator appear in both immediately.
         "/__dev/api/mcp/tools": ("GET", _api_mcp_tools),
         "/__dev/api/mcp/call": ("POST", _api_mcp_call),
-        # JSON-RPC + SSE surface for real MCP clients (Claude Desktop/Code).
-        # Same registry as the REST shim above; this is what makes /__dev/mcp
-        # actually reachable as an MCP server (previously defined but unmounted).
-        "/__dev/mcp": ("POST", _api_mcp_rpc),
-        "/__dev/mcp/message": ("POST", _api_mcp_rpc),
+        # MCP transport surface for real clients (Claude Code / Desktop).
+        # Same registry as the REST shim above. /__dev/mcp is the Streamable
+        # HTTP endpoint (POST message + DELETE session; "*" so one handler
+        # switches on the method); /message + /sse are the legacy HTTP+SSE
+        # transport, kept working for older SSE-only clients.
+        "/__dev/mcp": ("*", _api_mcp_endpoint),
+        "/__dev/mcp/message": ("POST", _api_mcp_message),
         "/__dev/mcp/sse": ("GET", _api_mcp_sse),
         # ── Scaffold REST shim ──
         # Wraps the tina4python CLI's `generate <kind> <name>` so the
@@ -2964,43 +2967,102 @@ async def _api_mcp_call(request, response):
         return response({"ok": False, "name": name, "error": str(exc)}, 500)
 
 
-# ─── MCP JSON-RPC + SSE endpoint ───────────────────────────────────
+# ─── MCP transport endpoint ────────────────────────────────────────
 #
-# The protocol surface real MCP clients (Claude Desktop/Code) speak —
-# JSON-RPC 2.0 over the HTTP+SSE transport. Mounted on the running dev
-# server so each `tina4 serve`d project exposes its OWN endpoint, giving
-# an AI agent live access scoped to that project. Shares the same
-# `_default_server` tool registry as the REST shim above, so every
-# @mcp_tool shows up on both surfaces.
-
-async def _api_mcp_rpc(request, response):
-    """POST — the JSON-RPC endpoint. Mounted at /__dev/mcp and
-    /__dev/mcp/message. Forwards to the default MCP server's
-    handle_message() and returns the JSON-RPC response; notifications
-    (no id) yield an empty 204.
-    """
+# The protocol surface real MCP clients (Claude Code / Claude Desktop)
+# speak. Mounted on the running dev server so each `tina4 serve`d project
+# exposes its OWN endpoint, giving an AI agent live access scoped to that
+# project. Shares the same `_default_server` tool registry as the REST
+# shim above, so every @mcp_tool shows up on all surfaces.
+#
+# Two transports live here:
+#   * Streamable HTTP (current) — POST /__dev/mcp with the JSON-RPC message;
+#     the response comes back inline as application/json, and initialize
+#     issues an Mcp-Session-Id header the client echoes on later requests.
+#     GET is 405 (this server initiates no messages) and DELETE ends a
+#     session.
+#   * Legacy HTTP+SSE (2024-11-05) — GET /__dev/mcp/sse opens a persistent
+#     stream that first names the POST endpoint, then delivers each JSON-RPC
+#     response as an SSE `message` event; POST /__dev/mcp/message feeds it.
+#     Kept working for older SSE-only clients.
+
+
+def _mcp_session_header(request) -> str:
+    """Read the Mcp-Session-Id request header (empty string when absent)."""
+    headers = getattr(request, "headers", None) or {}
+    return headers.get("mcp-session-id", "") or ""
+
+
+def _mcp_apply(response, outcome):
+    """Apply a dispatch_http/dispatch_sse_message result dict (status,
+    headers, body) onto the dev-admin response."""
     import json as _json
+    for name, value in outcome["headers"].items():
+        response.header(name, value)
+    body = outcome["body"]
+    if not body:
+        return response("", outcome["status"])
+    return response(_json.loads(body), outcome["status"])
+
+
+async def _api_mcp_endpoint(request, response):
+    """The Streamable HTTP endpoint at /__dev/mcp (method wildcard).
+
+    POST   — a JSON-RPC message; response is inline application/json.
+    GET    — 405, this server pushes no unsolicited messages (use the
+             legacy /sse stream if you need server-initiated framing).
+    DELETE — terminate the session named by Mcp-Session-Id.
+    """
     from tina4_python.mcp import _get_default_server
     if not _mcp_request_allowed(request):
         return response({"error": "MCP disabled"}, 404)
     server = _get_default_server()
-    body = request.body
-    raw = body if isinstance(body, (dict, str)) else str(body)
-    result = server.handle_message(raw)
-    if not result:
+    method = (getattr(request, "method", "") or "GET").upper()
+
+    if method == "POST":
+        outcome = server.dispatch_http(request.body, _mcp_session_header(request))
+        return _mcp_apply(response, outcome)
+
+    if method == "DELETE":
+        server.close_session(_mcp_session_header(request))
         return response("", 204)
-    return response(_json.loads(result))
+
+    # GET (and anything else): no server-initiated stream on this endpoint.
+    response.header("Allow", "POST, DELETE")
+    return response({"error": "method not allowed"}, 405)
+
+
+async def _api_mcp_message(request, response):
+    """POST /__dev/mcp/message — legacy HTTP+SSE message sink.
+
+    Delivers the JSON-RPC response on the matching open SSE stream (202
+    here); with no open stream it degrades to an inline Streamable HTTP
+    response, so the path also serves a plain POST client.
+    """
+    from tina4_python.mcp import _get_default_server
+    if not _mcp_request_allowed(request):
+        return response({"error": "MCP disabled"}, 404)
+    server = _get_default_server()
+    params = getattr(request, "params", None) or {}
+    session_id = params.get("sessionId") or _mcp_session_header(request)
+    outcome = server.dispatch_sse_message(request.body, session_id)
+    return _mcp_apply(response, outcome)
 
 
 async def _api_mcp_sse(request, response):
-    """GET — SSE handshake. Emits the `endpoint` event telling the client
-    where to POST JSON-RPC messages, per the MCP HTTP+SSE transport.
+    """GET /__dev/mcp/sse — legacy HTTP+SSE stream.
+
+    Opens a persistent SSE connection: first the `endpoint` event naming the
+    POST target (session-tagged), then each JSON-RPC response as it arrives.
     """
+    from tina4_python.mcp import _get_default_server
     if not _mcp_request_allowed(request):
         return response({"error": "MCP disabled"}, 404)
-    base = request.path.rsplit("/sse", 1)[0]
-    sse = f"event: endpoint\ndata: {base}/message\n\n"
-    return response(sse, 200, "text/event-stream")
+    server = _get_default_server()
+    session_id = server.open_session()
+    base = getattr(request, "path", "/__dev/mcp/sse").rsplit("/sse", 1)[0]
+    endpoint_url = f"{base}/message?sessionId={session_id}"
+    return response.stream(server.sse_stream(session_id, endpoint_url))
 
 
 # ─── Scaffold REST shim ────────────────────────────────────────────

{tina4_python-3.13.50 → tina4_python-3.13.52}/tina4_python/frond/FROND.md

@@ -383,6 +383,85 @@ Macros don't inherit parent context — pass everything explicitly via parameter
 
 ---
 
+## Live Blocks
+
+A live block renders on the server, then keeps itself fresh. The first paint ships with the
+page, so there is no loading flash. After that, the block re-fetches its own HTML and swaps
+it in place. You write server-side Frond and the block stays current, with no hand-written
+JavaScript.
+
+```twig
+{% live "cart" poll 5 %}
+    <strong>{{ count }}</strong> items - {{ total | number_format(2) }}
+{% endlive %}
+```
+
+That block paints once with the page, then re-renders every 5 seconds. `frond.js` (already
+loaded from `/js/frond.js`) finds the marker, calls `GET /__frond/live/cart`, and morphs the
+returned HTML into place. A focused input and its caret survive the swap.
+
+### Transports
+
+Pick how the block refreshes:
+
+```twig
+{% live "cart" poll 5 %}...{% endlive %}          {# re-fetch every 5 seconds #}
+{% live "feed" sse %}...{% endlive %}             {# Server-Sent Events stream #}
+{% live "chat" ws "/ws/chat" %}...{% endlive %}   {# WebSocket on /ws/chat #}
+```
+
+`poll N` pulls every `N` seconds. `sse` and `ws` push: the server decides when to send. All
+three render the same server-side body. Only the delivery changes.
+
+### The data source
+
+A live block needs data on every refresh, not just the first paint. Register a provider by
+name with `@live_source`. It runs on each refresh with the live request, so the block
+re-renders against fresh data and re-applies auth every time. An unauthenticated caller never
+sees another user's numbers.
+
+```python
+from tina4_python.frond import live_source
+
+@live_source("cart")
+def cart_data(request):
+    user = request.session.get("user_id")
+    return {"count": cart_count(user), "total": cart_total(user)}
+```
+
+The provider feeds the always-on endpoint `GET /__frond/live/{name}`. There is no route to
+write. The block name is the route.
+
+### Pushing updates
+
+A `ws` block can update the moment data changes, without waiting for the next poll. Call
+`push_live(name, data)`. It re-renders the block and broadcasts the new HTML to every client
+connected on the block's WebSocket path.
+
+```python
+from tina4_python.frond import push_live
+
+# after an order lands:
+push_live("cart", {"count": 3, "total": 59.97})
+```
+
+### Same-origin only
+
+A block can point at your own route with `src` instead of the auto endpoint:
+
+```twig
+{% live "cart" poll 5 src "/fragments/cart" %}...{% endlive %}
+```
+
+`src` must be a same-origin path. An absolute URL is rejected at render time, so a live block
+never fetches from a host you did not write. Nested live blocks are rejected too.
+
+The marker element is byte-identical across Python, PHP, Ruby, and Node, so the shared
+`frond.js` drives every backend the same way. Write the block once. It renders anywhere
+Tina4 runs.
+
+---
+
 ## Comments
 
 ```twig

tina4_python-3.13.52/tina4_python/frond/__init__.py

@@ -0,0 +1,85 @@
+# Tina4 Frond — Zero-dependency template engine.
+"""
+Twig-like template engine built from scratch.
+
+    from tina4_python.frond import Frond
+
+    engine = Frond(template_dir="src/templates")
+    output = engine.render("page.html", {"name": "World"})
+"""
+import inspect
+
+from tina4_python.frond.engine import Frond
+
+
+async def live_endpoint(name, request, response):
+    """GET /__frond/live/{name} - re-render a registered {% live %} fragment.
+
+    Resolves the @live_source provider for <name>, runs it with the LIVE request
+    so auth and session scoping re-apply on every refresh (a live "my cart"
+    cannot leak another user's data), renders the registered fragment, and
+    returns the HTML. 404 when the name is unknown or its fragment has not been
+    registered yet (the page carrying the block has not rendered).
+    """
+    provider = Frond._class_live_sources.get(name)
+    if name not in Frond._class_live_fragments and provider is None:
+        return response("live block not found: " + str(name), 404)
+    context = {}
+    if provider is not None:
+        result = provider(request)
+        if inspect.isawaitable(result):
+            result = await result
+        context = result or {}
+    html = Frond.render_live(name, context)
+    if html is None:
+        return response("live fragment not registered yet: " + str(name), 404)
+    return response(html)
+
+
+async def push_live(name, data=None):
+    """Re-render the '<name>' live fragment and push it to connected clients.
+
+    Renders via Frond.render_live(name, data) and broadcasts a {type, name, html}
+    envelope over WebSocket: to the ws path the block declared (data-ws), or to a
+    room named <name> if the block declared none. Apps call this after a state
+    change (a new chat message, an order update). Returns the rendered HTML, or
+    None when the fragment is not registered (its page has not rendered).
+    """
+    html = Frond.render_live(name, data or {})
+    if html is None:
+        return None
+    import json
+    envelope = json.dumps({"type": "live", "name": name, "html": html})
+    try:
+        from tina4_python.core.server import _ws_manager
+        ws_path = Frond._class_live_ws_paths.get(name)
+        if ws_path:
+            await _ws_manager.broadcast(envelope, path=ws_path)
+        else:
+            await _ws_manager.broadcast_to_room(name, envelope)
+    except Exception as exc:
+        try:
+            from tina4_python.debug import Log
+            Log.error("push_live(" + str(name) + ") broadcast failed: " + str(exc))
+        except Exception:
+            pass
+    return html
+
+
+def live_source(name: str):
+    """Register a data provider for a {% live %} block.
+
+    The decorated function receives the request and returns the context dict
+    used to re-render the fragment on refresh:
+
+        @live_source("notifications")
+        async def notifications(request):
+            return {"items": Notification.where("user_id = ?", [request.session["uid"]])}
+    """
+    def _wrap(fn):
+        Frond._class_live_sources[name] = fn
+        return fn
+    return _wrap
+
+
+__all__ = ["Frond", "live_source", "live_endpoint", "push_live"]

{tina4_python-3.13.50 → tina4_python-3.13.52}/tina4_python/frond/engine.py

@@ -117,6 +117,15 @@ _FILTER_CMP_RE = re.compile(r"(\w+)\s*(!=|==|>=|<=|>|<)\s*(.+)")
 _FOR_RE = re.compile(r"for\s+(\w+)(?:\s*,\s*(\w+))?\s+in\s+(.+)")
 _SET_RE = re.compile(r"set\s+(\w+)\s*=\s*(.+)", re.DOTALL)
 _INCLUDE_RE = re.compile(r'include\s+["\'](.+?)["\'](?:\s+with\s+(.+))?')
+_LIVE_RE = re.compile(r'live\s+["\'](?P<name>[^"\']+)["\'](?P<rest>.*)$', re.DOTALL)
+_LIVE_WS_RE = re.compile(r'ws\s+["\']([^"\']+)["\']')
+_LIVE_SRC_RE = re.compile(r'src\s+["\']([^"\']+)["\']')
+
+
+def _live_attr(value) -> str:
+    """Escape a value for use inside an HTML attribute on a live marker."""
+    return (str(value).replace("&", "&amp;").replace('"', "&quot;")
+            .replace("<", "&lt;").replace(">", "&gt;"))
 _MACRO_RE = re.compile(r"macro\s+(\w+)\s*\(([^)]*)\)")
 _FROM_IMPORT_RE = re.compile(r'from\s+["\'](.+?)["\']\s+import\s+(.+)')
 _IMPORT_AS_RE = re.compile(r'import\s+["\'](.+?)["\']\s+as\s+(\w+)')
@@ -1309,6 +1318,11 @@ class Frond:
     _class_globals: dict = {}
     _class_filters: dict = {}
     _class_tests: dict = {}
+    # Live blocks: name -> body template source (registered when a {% live %}
+    # block renders); name -> data provider (registered via @live_source).
+    _class_live_fragments: dict = {}
+    _class_live_sources: dict = {}
+    _class_live_ws_paths: dict = {}
 
     @classmethod
     def clear_registry(cls):
@@ -1320,6 +1334,9 @@ class Frond:
         cls._class_globals.clear()
         cls._class_filters.clear()
         cls._class_tests.clear()
+        cls._class_live_fragments.clear()
+        cls._class_live_sources.clear()
+        cls._class_live_ws_paths.clear()
 
     def __init__(self, template_dir: str = "src/templates"):
         self.template_dir = Path(template_dir)
@@ -1766,6 +1783,11 @@ class Frond:
                     output.append(result)
                     i = skip
 
+                elif tag == "live":
+                    result, skip = self._handle_live(tokens, i, context)
+                    output.append(result)
+                    i = skip
+
                 elif tag in ("block", "endblock", "extends"):
                     i += 1  # Already handled
 
@@ -2396,6 +2418,93 @@ class Frond:
         self._fragment_cache[cache_key] = (rendered, time.time() + ttl)
         return rendered, i
 
+    def _handle_live(self, tokens: list, start: int, context: dict) -> tuple[str, int]:
+        """Handle {% live "name" poll N | sse | ws "path" [src "url"] %}...{% endlive %}.
+
+        Server-rendered live region. The body renders once for first paint, is
+        registered under <name> so the /__frond/live/<name> endpoint (or a
+        @live_source provider) can re-render it, and is wrapped in a marker
+        element that frond.js wires to the chosen transport (poll / sse / ws).
+        """
+        content, _, _ = _strip_tag(tokens[start][1])
+        m = _LIVE_RE.match(content)
+        if not m:
+            raise ValueError('live: expected {% live "name" poll N | sse | ws "path" %}')
+        name = m.group("name")
+        rest = (m.group("rest") or "").strip()
+        parts = rest.split()
+        mode = parts[0] if parts else ""
+
+        src = None
+        sm = _LIVE_SRC_RE.search(rest)
+        if sm:
+            src = sm.group(1)
+        if src and (src.startswith("http://") or src.startswith("https://") or src.startswith("//")):
+            raise ValueError("live: src must be a same-origin path, not an absolute URL")
+
+        interval = None
+        ws_path = None
+        if mode == "poll":
+            if len(parts) < 2 or not parts[1].isdigit():
+                raise ValueError('live: poll requires seconds, e.g. {% live "x" poll 5 %}')
+            interval = int(parts[1])
+        elif mode == "sse":
+            pass
+        elif mode == "ws":
+            wm = _LIVE_WS_RE.search(rest)
+            if not wm:
+                raise ValueError('live: ws requires a path, e.g. {% live "x" ws "/ws/x" %}')
+            ws_path = wm.group(1)
+        else:
+            raise ValueError(f'live: unknown transport "{mode}" (use poll N, sse, or ws "path")')
+
+        # Collect body tokens up to {% endlive %}. Nested live is unsupported.
+        body_tokens = []
+        i = start + 1
+        while i < len(tokens):
+            if tokens[i][0] == BLOCK:
+                tag_content, _, _ = _strip_tag(tokens[i][1])
+                tag = tag_content.split()[0] if tag_content.split() else ""
+                if tag == "live":
+                    raise ValueError("live: nested live blocks are not supported")
+                if tag == "endlive":
+                    i += 1
+                    break
+                body_tokens.append(tokens[i])
+            else:
+                body_tokens.append(tokens[i])
+            i += 1
+
+        # Register the body source so the auto endpoint can re-render it.
+        Frond._class_live_fragments[name] = "".join(raw for (_t, raw) in body_tokens)
+
+        endpoint = src or ("/__frond/live/" + name)
+        attrs = [f'data-frond-live="{_live_attr(name)}"', f'id="live-{_live_attr(name)}"']
+        if mode == "poll":
+            attrs += ['data-mode="poll"', f'data-interval="{interval}"',
+                      f'data-src="{_live_attr(endpoint)}"']
+        elif mode == "sse":
+            attrs += ['data-mode="sse"', f'data-src="{_live_attr(endpoint)}"']
+        elif mode == "ws":
+            Frond._class_live_ws_paths[name] = ws_path
+            attrs += ['data-mode="ws"', f'data-ws="{_live_attr(ws_path)}"']
+
+        first_paint = self._render_tokens(list(body_tokens), context)
+        return f'<div {" ".join(attrs)}>{first_paint}</div>', i
+
+    @classmethod
+    def render_live(cls, name: str, data: dict = None):
+        """Re-render a registered {% live %} fragment by name.
+
+        Returns the rendered HTML fragment, or None if no fragment is registered
+        under that name yet (the page carrying the block has not rendered). The
+        /__frond/live/<name> endpoint calls this after resolving the provider data.
+        """
+        source = cls._class_live_fragments.get(name)
+        if source is None:
+            return None
+        return cls().render_string(source, data or {})
+
     def _handle_spaceless(self, tokens: list, start: int, context: dict) -> tuple[str, int]:
         """Handle {% spaceless %}...{% endspaceless %}.