tina4-python 3.13.81__tar.gz → 3.13.82__tar.gz

{tina4_python-3.13.81 → tina4_python-3.13.82}/.gitignore

@@ -74,15 +74,19 @@ build/
 example/.env
 example/data/*.db
 example/data/*.db-*
-example/store/data/*.db
-example/store/data/*.db-*
-example/store/data/broken/
-example/store/data/.broken/
-example/store/data/mailbox/
-example/store/data/sessions/
-example/store/.tina4/
-example/store/__pycache__/
-example/store/src/**/__pycache__/
+# The example app runs from example/, not example/store/ (which no longer
+# exists), so the old example/store/... rules below matched nothing and every
+# runtime artifact the example writes leaked into git status - 466 of them, plus
+# 6 that got committed. Anchored /logs/ missed example/logs/ for the same reason.
+example/data/broken/
+example/data/.broken/
+example/data/mailbox/
+example/data/queue/
+example/data/sessions/
+example/logs/
+example/.tina4/
+example/__pycache__/
+example/src/**/__pycache__/
 .claude/settings.local.json
 .claude/worktrees/
 /nonexistent_path/

{tina4_python-3.13.81 → tina4_python-3.13.82}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.81
+Version: 3.13.82
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -37,13 +37,13 @@ Description-Content-Type: text/markdown
 <h1 align="center">Tina4 Python</h1>
 
 <p align="center">
-  55 built-in features. Zero dependencies. One import, everything works.
+  98 built-in features. Zero dependencies. One import, everything works.
 </p>
 
 <p align="center">
   <a href="https://pypi.org/project/tina4-python/"><img src="https://img.shields.io/pypi/v/tina4-python?color=7b1fa2&label=PyPI" alt="PyPI"></a>
   <img src="https://img.shields.io/badge/tests-2%2C281%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/features-55-blue" alt="Features">
+  <img src="https://img.shields.io/badge/features-98-blue" alt="Features">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
   <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>
 </p>
@@ -726,7 +726,7 @@ Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 | Bottle | 4,355 | 0 | ~5 |
 | Django | 4,050 | 20+ | ~22 |
 
-Tina4 Python delivers competitive throughput with **zero dependencies and 55 features**. Frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
+Tina4 Python delivers competitive throughput with **zero dependencies and 98 features**. Frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
 
 **Across all 4 Tina4 implementations:**
 
@@ -742,7 +742,7 @@ Run benchmarks locally: `python benchmarks/benchmark.py --python`
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 97 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

{tina4_python-3.13.81 → tina4_python-3.13.82}/README.md

@@ -5,13 +5,13 @@
 <h1 align="center">Tina4 Python</h1>
 
 <p align="center">
-  55 built-in features. Zero dependencies. One import, everything works.
+  98 built-in features. Zero dependencies. One import, everything works.
 </p>
 
 <p align="center">
   <a href="https://pypi.org/project/tina4-python/"><img src="https://img.shields.io/pypi/v/tina4-python?color=7b1fa2&label=PyPI" alt="PyPI"></a>
   <img src="https://img.shields.io/badge/tests-2%2C281%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/features-55-blue" alt="Features">
+  <img src="https://img.shields.io/badge/features-98-blue" alt="Features">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
   <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>
 </p>
@@ -694,7 +694,7 @@ Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 | Bottle | 4,355 | 0 | ~5 |
 | Django | 4,050 | 20+ | ~22 |
 
-Tina4 Python delivers competitive throughput with **zero dependencies and 55 features**. Frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
+Tina4 Python delivers competitive throughput with **zero dependencies and 98 features**. Frameworks with higher req/s have a fraction of the functionality and require dozens of third-party packages.
 
 **Across all 4 Tina4 implementations:**
 
@@ -710,7 +710,7 @@ Run benchmarks locally: `python benchmarks/benchmark.py --python`
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 97 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

{tina4_python-3.13.81 → tina4_python-3.13.82}/pyproject.toml

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

{tina4_python-3.13.81 → tina4_python-3.13.82}/tina4_python/CLAUDE.md

@@ -291,7 +291,7 @@ Queue(topic="tasks").push({"action": "send_email"})
 6. **Connection strings**: v3 uses standard URL format: `driver://host:port/database` with separate `username` and `password` parameters. Example: `Database("firebird://localhost:3050//path/to/db", "SYSDBA", "masterkey")`. Environment variable: `TINA4_DATABASE_URL`.
 7. **Running the app**: use the `tina4` CLI — `tina4 serve`. The framework **refuses to boot via a plain `python app.py`** (it must be launched by the CLI; `TINA4_OVERRIDE_CLIENT=true` only for embedding). Port/name are CLI args.
 8. **SCSS**: Files in `src/scss/` are auto-compiled to `src/public/css/` on startup
-12. **Background tasks**: Use `background(fn, interval)` from `tina4_python.core.server` — never use `threading.Thread` for periodic work. The `background()` function runs tasks cooperatively in the asyncio event loop with proper shutdown handling.
+12. **Background tasks**: Use `background(fn, interval)` from `tina4_python.core.server` — never use `threading.Thread` for periodic work. The `background()` function runs tasks cooperatively in the asyncio event loop with proper shutdown handling. It returns a `BackgroundTask` handle: call `handle.stop()` to end ONE task and deregister it (idempotent; returns `False` if already stopped). `background_task_count()` reports how many are registered and `stop_all_background_tasks()` clears them all — a stopped task is never left in the registry.
 
 
 ---
@@ -1912,7 +1912,7 @@ async def dashboard(request, response):
 
 ## v3 Features Summary
 
-- **55 built-in features**, zero third-party dependencies
+- **98 built-in features**, zero third-party dependencies
 - **2,899 tests** passing across all modules
 - **Production server auto-detect**: `tina4python serve --production` auto-installs uvicorn
 - **`tina4python generate`**: model, route, migration, middleware scaffolding

{tina4_python-3.13.81 → tina4_python-3.13.82}/tina4_python/__init__.py

@@ -89,6 +89,9 @@ from tina4_python.auth import Auth  # noqa: E402, F401
 # ── Queue ──
 from tina4_python.queue import Queue  # noqa: E402, F401
 
+# ── MQTT (IoT) ──
+from tina4_python.mqtt import Mqtt, MqttMessage, MqttError  # noqa: E402, F401
+
 # ── Template engine ──
 from tina4_python.frond import Frond  # noqa: E402, F401
 
@@ -101,7 +104,12 @@ from tina4_python.cache import (  # noqa: E402, F401
 from tina4_python.container import Container  # noqa: E402, F401
 
 # ── Server ──
-from tina4_python.core.server import run, background  # noqa: E402, F401
+from tina4_python.core.server import (  # noqa: E402, F401
+    run,
+    background,
+    background_task_count,
+    stop_all_background_tasks,
+)
 
 # ── HTTP Client ──
 from tina4_python.api import Api  # noqa: E402, F401

{tina4_python-3.13.81 → tina4_python-3.13.82}/tina4_python/cli/__init__.py

@@ -13,9 +13,15 @@ CLI commands for development workflow.
     tina4python test              # Run tests
     tina4python generate          # Generate scaffolding
     tina4python ai                # Detect AI tools and install context
+
+Three further commands — doctor, setup, deploy — are owned by the `tina4` client
+and reached by DELEGATION (see DELEGATED / _delegate_to_client below), so
+`tina4python doctor` behaves exactly like `tina4 doctor` without cloning the
+client's implementation into four languages.
 """
 import os
 import re
+import shutil
 import signal
 import subprocess
 import sys
@@ -187,6 +193,83 @@ def _kill_process_on_port(port: int) -> bool:
     return False
 
 
+# ── Delegation to the `tina4` client ─────────────────────────────────
+#
+# `doctor`, `setup` and `deploy` are owned by the Rust `tina4` client, not by any
+# framework. `doctor` probes ALL FOUR runtimes plus package managers, ports and
+# global AI-skills currency; `setup` installs language runtimes (Homebrew /
+# Chocolatey, with UAC elevation on Windows) and scaffolds a project from
+# nothing; `deploy` writes deployment boilerplate baked into the client binary.
+# Cloning any of them into four languages would duplicate hundreds of lines per
+# language for zero new capability — and four copies would immediately drift.
+#
+# So the framework CLI DELEGATES: it resolves `tina4` on PATH, runs it with the
+# same argv, and exits with the client's exit code. All four frameworks reach the
+# SAME implementation, which is a stronger parity guarantee than four ports.
+#
+# Delegation is ALLOW-LISTED, never blind. The client forwards ITS unknown
+# commands to the framework CLI, so a framework that forwarded its unknowns back
+# would ping-pong an unknown command between two processes forever. The closed
+# DELEGATED set contains only commands the client dispatches natively, so no
+# loop is possible by construction, and a real typo still gets "Unknown command".
+
+CLIENT_BINARY = "tina4"
+
+# Internal process marker (same class as the client's own TINA4_SETUP_ELEVATED):
+# set on the child so a client that resolves back to a framework CLI is caught
+# instead of spawning forever. NOT user configuration — deliberately absent from
+# the CLI's known_vars().
+DELEGATION_GUARD_ENV = "TINA4_CLI_DELEGATED"
+
+# Exit codes. 127 is the conventional "command not found" and covers both ways
+# the client can be unreachable (absent from PATH, or the loop guard tripping).
+EXIT_CLIENT_UNAVAILABLE = 127
+EXIT_UNKNOWN_COMMAND = 1
+
+CLIENT_INSTALL_HINT = (
+    "  Install it:  curl -fsSL https://tina4.com/install.sh | sh\n"
+    "  Windows:     irm https://tina4.com/install.ps1 | iex"
+)
+
+
+def _find_client() -> str | None:
+    """Absolute path of the `tina4` client on PATH, or None if it isn't there."""
+    return shutil.which(CLIENT_BINARY)
+
+
+def _delegate_to_client(command: str, args: list) -> int:
+    """Run `tina4 <command> <args...>`, returning the client's exit code.
+
+    Returns EXIT_CLIENT_UNAVAILABLE (127) with an actionable message when the
+    client is not on PATH, or when the re-entry guard shows the resolved `tina4`
+    came back to a framework CLI (a delegation loop).
+    """
+    if os.environ.get(DELEGATION_GUARD_ENV) == command:
+        print(
+            f"  Refusing to delegate '{command}' again — the 'tina4' on your PATH\n"
+            f"  resolved back to a framework CLI instead of the tina4 client.\n\n"
+            f"  Check which 'tina4' comes first on your PATH and put the client first.",
+            file=sys.stderr,
+        )
+        return EXIT_CLIENT_UNAVAILABLE
+
+    client = _find_client()
+    if client is None:
+        print(
+            f"  '{command}' is provided by the tina4 client, which is not on your PATH.\n\n"
+            f"{CLIENT_INSTALL_HINT}\n\n"
+            f"  Then run:    {CLIENT_BINARY} {command}",
+            file=sys.stderr,
+        )
+        return EXIT_CLIENT_UNAVAILABLE
+
+    # stdio is inherited, so the client's interactive prompts (setup) and colour
+    # output work exactly as if it had been invoked directly.
+    env = dict(os.environ)
+    env[DELEGATION_GUARD_ENV] = command
+    return subprocess.run([client, command, *args], env=env).returncode
+
+
 # ── Main entry point ─────────────────────────────────────────────────
 
 def main():
@@ -205,9 +288,14 @@ def main():
     spec = COMMANDS.get(command)
     if spec:
         spec["handler"](cmd_args)
+    elif command in DELEGATED:
+        sys.exit(_delegate_to_client(command, cmd_args))
     else:
+        # A genuinely unknown command is an ERROR: exit non-zero so a typo in a
+        # script or CI step fails loudly instead of reporting success.
         print(f"Unknown command: {command}")
         _help([])
+        sys.exit(EXIT_UNKNOWN_COMMAND)
 
 
 def _env_migrate(args):
@@ -259,21 +347,26 @@ def _env_migrate(args):
 def _help(args=None):
     """Print the human-readable command reference.
 
-    Generated from the COMMANDS and GENERATORS registries — the SAME single
-    source of truth that drives dispatch (`main`) and the `commands --json`
-    manifest — so the help text can never drift from what the CLI actually does.
+    Generated from the COMMANDS, DELEGATED and GENERATORS registries — the SAME
+    single source of truth that drives dispatch (`main`) and the
+    `commands --json` manifest — so the help text can never drift from what the
+    CLI actually does.
     """
     command_rows = [
         (f"{name} {spec.get('usage', '')}".rstrip(), spec["summary"])
         for name, spec in COMMANDS.items()
     ]
+    delegated_rows = [
+        (f"{name} {spec.get('usage', '')}".rstrip(), spec["summary"])
+        for name, spec in DELEGATED.items()
+    ]
     generator_rows = [
         (f"generate {name} {spec.get('usage', '')}".rstrip(), spec["summary"])
         for name, spec in GENERATORS.items()
     ]
     # Align summaries in a column; a left cell longer than the cap overflows
     # cleanly (2-space gap) rather than pushing every other summary out.
-    pad = min(46, max(len(left) for left, _ in command_rows + generator_rows))
+    pad = min(46, max(len(left) for left, _ in command_rows + delegated_rows + generator_rows))
 
     def row(left, summary):
         gap = pad if len(left) <= pad else len(left)
@@ -281,6 +374,10 @@ def _help(args=None):
 
     lines = ["", "Tina4 Python — CLI", "", "Usage: tina4python <command> [options]", "", "Commands:"]
     lines += [row(left, summary) for left, summary in command_rows]
+    lines += ["", f"Delegated to the {CLIENT_BINARY} client (same behaviour in every framework):"]
+    lines += [row(left, summary) for left, summary in delegated_rows]
+    lines += [f"  (these run the {CLIENT_BINARY} client — install: "
+              f"curl -fsSL https://tina4.com/install.sh | sh)"]
     lines += ["", "Generators:"]
     lines += [row(left, summary) for left, summary in generator_rows]
     lines += [
@@ -2943,15 +3040,20 @@ def _queue(args):
 def _commands_manifest() -> dict:
     """Build the machine-readable manifest of the CLI's command surface.
 
-    Pure data: reads the module-level COMMANDS registry and the framework
-    version — no bootstrap, no database, no migrations, no app imports. This is
-    exactly what `commands --json` serializes and what the tina4 Rust client
-    consumes to discover which commands this framework supports.
+    Pure data: reads the module-level COMMANDS and DELEGATED registries and the
+    framework version — no bootstrap, no database, no migrations, no app imports.
+    This is exactly what `commands --json` serializes and what the tina4 Rust
+    client consumes to discover which commands this framework supports.
+
+    Commands the framework hands to the `tina4` client carry `"delegated": true`,
+    so the manifest describes the WHOLE surface the CLI accepts while still
+    saying who implements each one. The client needs no change for this: its help
+    renderer already drops manifest names that clash with its own natives.
 
     Shape::
 
         {"framework": "python", "version": "<x.y.z>",
-         "commands": [{"name", "summary", "args"?, "subcommands"?}, ...]}
+         "commands": [{"name", "summary", "args"?, "subcommands"?, "delegated"?}, ...]}
     """
     from tina4_python import __version__
     commands = []
@@ -2962,6 +3064,11 @@ def _commands_manifest() -> dict:
         if spec.get("subcommands"):
             entry["subcommands"] = list(spec["subcommands"])
         commands.append(entry)
+    for command_name, spec in DELEGATED.items():
+        entry = {"name": command_name, "summary": spec["summary"], "delegated": True}
+        if spec.get("args"):
+            entry["args"] = list(spec["args"])
+        commands.append(entry)
     return {"framework": "python", "version": __version__, "commands": commands}
 
 
@@ -2988,7 +3095,8 @@ def _commands(args=None):
     print(f"\nTina4 {manifest['framework']} — {manifest['version']}\n")
     width = max(len(command["name"]) for command in manifest["commands"])
     for command in manifest["commands"]:
-        print(f"  {command['name']:<{width}}  {command['summary']}")
+        marker = f" ({CLIENT_BINARY} client)" if command.get("delegated") else ""
+        print(f"  {command['name']:<{width}}  {command['summary']}{marker}")
         if command.get("subcommands"):
             print(f"  {'':<{width}}    {', '.join(command['subcommands'])}")
     print()
@@ -3046,5 +3154,18 @@ COMMANDS = {
     "help":             {"handler": _help,             "summary": "Show this help"},
 }
 
+# Commands the `tina4` client OWNS and this CLI reaches by delegation — see the
+# "Delegation to the `tina4` client" section above for why these are not ported.
+# There are no handlers here: `main()` runs `tina4 <name> <args...>` and exits
+# with its code. Keep this set closed and identical in all four frameworks — it
+# must contain ONLY commands the client dispatches natively, or delegation could
+# bounce back and loop. Summaries are the client's own wording, verbatim.
+DELEGATED = {
+    "doctor": {"summary": "Check installed languages and tools"},
+    "setup":  {"summary": "Guided, menu-driven setup: install everything + scaffold a ready-to-run project"},
+    "deploy": {"usage": "<docker|systemd|nginx|cpanel> [--force]", "args": ["target"],
+               "summary": "Generate deployment scaffolding (Dockerfile, systemd unit, nginx block, cPanel)"},
+}
+
 
 __all__ = ["main"]

{tina4_python-3.13.81 → tina4_python-3.13.82}/tina4_python/core/server.py

@@ -11,6 +11,7 @@ import signal
 import asyncio
 import contextvars
 import importlib
+import threading
 import uuid
 from email.utils import formatdate, parsedate_to_datetime
 from pathlib import Path
@@ -34,10 +35,63 @@ _ai_port_ctx: contextvars.ContextVar[bool] = contextvars.ContextVar("_ai_port_ct
 _start_time: float = 0
 
 # ── Background tasks registry ────────────────────────────────────────────
-_background_tasks: list[dict] = []
+_background_tasks: list["BackgroundTask"] = []
+# The registry is read from the event loop and written from user code (which may
+# be on another thread), and stop() is a search-then-delete — not atomic under
+# the GIL. One lock guards every mutation.
+_background_lock = threading.Lock()
 
 
-def background(callback, interval: float = 1.0):
+class BackgroundTask:
+    """Handle for one registered background task.
+
+    Returned by :func:`background`. Call :meth:`stop` to end the task AND remove
+    it from the registry — a stopped task is never left behind, so
+    :func:`background_task_count` always reports what is actually running.
+
+    Mirrors Node's ``background()`` handle (``handle.stop()``) and Ruby's
+    ``Tina4::Background.stop_task(task)``.
+    """
+
+    __slots__ = ("callback", "interval", "stopped", "_runner")
+
+    def __init__(self, callback, interval: float):
+        self.callback = callback
+        self.interval = float(interval)
+        self.stopped = False
+        # The asyncio.Task ticking this callback, once the server loop has
+        # started it. None while the task is registered but not yet running.
+        self._runner = None
+
+    def stop(self) -> bool:
+        """Stop this task and deregister it.
+
+        Works whether or not the server is running: before start it simply
+        leaves the registry, and once ticking it also cancels its runner.
+
+        Idempotent — a second call is a safe no-op.
+
+        Returns:
+            True if this call removed the task, False if it was already gone.
+        """
+        removed = False
+        with _background_lock:
+            # Identity, not equality: only THIS handle goes, never a sibling
+            # that happens to hold the same callback and interval.
+            for index, registered in enumerate(_background_tasks):
+                if registered is self:
+                    del _background_tasks[index]
+                    removed = True
+                    break
+
+        self.stopped = True
+        runner, self._runner = self._runner, None
+        if runner is not None and not runner.done():
+            runner.cancel()
+        return removed
+
+
+def background(callback, interval: float = 1.0) -> BackgroundTask:
     """Register a background task that runs periodically in the server event loop.
 
     Matches PHP's $app->background(fn, interval) pattern.
@@ -45,8 +99,59 @@ def background(callback, interval: float = 1.0):
     Args:
         callback: Function to call (sync or async, no arguments).
         interval: Seconds between invocations (default: 1.0).
+
+    Returns:
+        A BackgroundTask handle — call ``.stop()`` to end and deregister it.
     """
-    _background_tasks.append({"callback": callback, "interval": interval})
+    task = BackgroundTask(callback, interval)
+    with _background_lock:
+        _background_tasks.append(task)
+    return task
+
+
+def background_task_count() -> int:
+    """Number of REGISTERED background tasks (stopped ones are already gone)."""
+    with _background_lock:
+        return len(_background_tasks)
+
+
+def stop_all_background_tasks() -> int:
+    """Stop and deregister every background task. Returns how many were stopped.
+
+    Each task deregisters itself, so there is no blanket ``clear()``: clearing
+    would also drop a task registered while this was running, leaving it ticking
+    but invisible in the registry.
+    """
+    with _background_lock:
+        snapshot = list(_background_tasks)
+    return sum(1 for task in snapshot if task.stop())
+
+
+def _start_background_tasks(executor, shutdown) -> list:
+    """Start an asyncio runner for every registered task. Called once by _serve.
+
+    Each runner is bound to its handle so ``BackgroundTask.stop()`` can cancel a
+    task that is already ticking, not merely deregister one that never started.
+    """
+    with _background_lock:
+        # Never iterate the live list — a concurrent stop() mutates it.
+        snapshot = list(_background_tasks)
+
+    runners = []
+    for task in snapshot:
+        if task.stopped:
+            continue  # stopped between registration and server start
+        runner = asyncio.create_task(
+            background_tick_loop(task.callback, task.interval, executor, shutdown)
+        )
+        task._runner = runner
+        # A stop() that landed while the runner was being created must still win,
+        # or the task would tick on with nothing holding a reference to cancel it.
+        if task.stopped:
+            runner.cancel()
+            continue
+        runners.append(runner)
+    return runners
 
 
 async def background_tick_loop(callback, interval: float, executor, shutdown):
@@ -2812,16 +2917,10 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
         # other of workers.
         import concurrent.futures
         _executor = concurrent.futures.ThreadPoolExecutor(
-            max_workers=max(len(_background_tasks), 2),
+            max_workers=max(background_task_count(), 2),
             thread_name_prefix="tina4_bg",
         )
-        bg_tasks = []
-        for task_def in _background_tasks:
-            bg_tasks.append(asyncio.create_task(
-                background_tick_loop(
-                    task_def["callback"], task_def["interval"], _executor, shutdown,
-                )
-            ))
+        bg_tasks = _start_background_tasks(_executor, shutdown)
 
         await shutdown.wait()