tina4-python 3.12.3__tar.gz → 3.12.4__tar.gz

{tina4_python-3.12.3 → tina4_python-3.12.4}/PKG-INFO

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

{tina4_python-3.12.3 → tina4_python-3.12.4}/pyproject.toml

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

{tina4_python-3.12.3 → tina4_python-3.12.4}/tina4_python/__init__.py

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

{tina4_python-3.12.3 → tina4_python-3.12.4}/tina4_python/core/server.py

@@ -150,8 +150,14 @@ async def _health_handler(request: Request, response: Response) -> Response:
     return response.status(code).json(health)
 
 
-# Register health check
-Router.add("GET", "/health", _health_handler)
+# Register health check.
+# TINA4_HEALTH_PATH overrides the URL path. We also keep /health registered
+# under the env path; if the env path differs we register both so existing
+# probes don't break. Default "/__health" matches PHP/Ruby/Node parity.
+_HEALTH_PATH = os.environ.get("TINA4_HEALTH_PATH", "/__health")
+Router.add("GET", _HEALTH_PATH, _health_handler)
+if _HEALTH_PATH != "/health":
+    Router.add("GET", "/health", _health_handler)
 
 
 def _render_error_page(status_code: int, path: str, request_id: str, error_message: str = "") -> str | None:
@@ -1289,6 +1295,17 @@ async def handle(request: Request) -> Response:
     from tina4_python.dotenv import is_truthy
     _is_dev = is_truthy(os.environ.get("TINA4_DEBUG", ""))
 
+    # Trailing-slash redirect — when TINA4_TRAILING_SLASH_REDIRECT=true and a
+    # request arrives at `/foo/`, return 301 to `/foo`. Skip the root `/` so
+    # the homepage still works. Cross-framework parity v3.12.4.
+    if (
+        is_truthy(os.environ.get("TINA4_TRAILING_SLASH_REDIRECT", ""))
+        and len(request.path) > 1
+        and request.path.endswith("/")
+    ):
+        canonical = request.path.rstrip("/") or "/"
+        return response.status(301).header("location", canonical)
+
     # Dev admin — also catches /ai/api/chat (SPA's ollama proxy) and the
     # bare /ai /vision /embed /image /rag service-health probes that
     # drive the "SERVICES ●●●●●" dots in the dev-admin UI.
@@ -1629,11 +1646,14 @@ def resolve_config(cli_host: str | None = None, cli_port: int | None = None) ->
     default_host = "0.0.0.0"
     default_port = 7146
 
-    # Host: CLI flag > HOST env > default
+    # Host: CLI flag > TINA4_HOST env > HOST env > default.
+    # TINA4_HOST takes precedence over the legacy plain HOST so a stray
+    # OS-level HOST (common on shared CI runners) can't silently override
+    # the framework's bind address. See cross-framework v3.12.4 plan.
     if cli_host is not None:
         host = cli_host
     else:
-        host = os.environ.get("HOST", default_host)
+        host = os.environ.get("TINA4_HOST") or os.environ.get("HOST", default_host)
 
     # Port: CLI flag > PORT env > default
     if cli_port is not None:
@@ -1731,7 +1751,7 @@ def _check_legacy_env_vars() -> None:
         new = _LEGACY_ENV_VARS[old]
         msg.append(f"    {old:<28}  →  {new}")
     msg.extend(["",
-                "Run `tina4 env-migrate` to rewrite your .env automatically,",
+                "Run `tina4 env --migrate` to rewrite your .env automatically,",
                 "or rename manually. See https://tina4.com/release/3.12.0",
                 "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                 "─" * 72, ""])
@@ -1869,8 +1889,12 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
     _no_ai_port = os.environ.get("TINA4_NO_AI_PORT", "").lower() in ("true", "1", "yes")
     _ai_port = (port + 1000) if (is_debug and not _no_ai_port) else None
 
-    # Banner — printed directly to stdout, not through the logger
-    _print_banner(host, port, server_name, ai_port=_ai_port)
+    # Banner — printed directly to stdout, not through the logger.
+    # TINA4_SUPPRESS=true silences the startup banner (useful in CI / Docker
+    # logs where the ASCII art is just noise). Cross-framework parity v3.12.4.
+    from tina4_python.dotenv import is_truthy as _is_truthy
+    if not _is_truthy(os.environ.get("TINA4_SUPPRESS", "")):
+        _print_banner(host, port, server_name, ai_port=_ai_port)
 
     display = "localhost" if host in ("0.0.0.0", "::") else host
     Log.info(f"Server started http://{display}:{port} ({server_name})")

{tina4_python-3.12.3 → tina4_python-3.12.4}/tina4_python/database/connection.py

@@ -144,7 +144,15 @@ class Database:
         # Priority: constructor params > env vars > empty
         self.username = username or os.environ.get("TINA4_DATABASE_USERNAME", "")
         self.password = password or os.environ.get("TINA4_DATABASE_PASSWORD", "")
-        self.pool_size = pool  # 0 = single connection, N>0 = N pooled connections
+        # Pool size — caller's explicit value wins; otherwise honour
+        # TINA4_DB_POOL so deployments can flip pooling on without code
+        # changes. 0 = single connection, N>0 = N pooled connections.
+        if pool == 0:
+            try:
+                pool = int(os.environ.get("TINA4_DB_POOL", "0"))
+            except (TypeError, ValueError):
+                pool = 0
+        self.pool_size = pool
         self._connect_kwargs = kwargs  # Extra kwargs passed through to adapter.connect()
         self.last_error = None  # Last execute() error message
         self._last_id = None   # Last insert ID from execute/insert

tina4_python-3.12.4/tina4_python/debug/__init__.py

@@ -0,0 +1,406 @@
+# Tina4 Debug — Structured logging with rotation.
+"""
+Zero-dependency structured logger.
+
+    from tina4_python.debug import Log
+
+    Log.info("Request completed", method="GET", path="/api/users", duration_ms=45)
+    Log.error("Database failed", error="connection refused")
+
+Production: JSON lines → logs/tina4.log (with rotation)
+Development: Human-readable → stdout + logs/tina4.log
+
+Environment variables (all optional — defaults match v2 behaviour):
+    TINA4_LOG_FILE          Log filename. Empty string = stdout only.
+    TINA4_LOG_DIR           Directory for log files (default: "logs"). Joined
+                            with TINA4_LOG_FILE unless that is absolute.
+    TINA4_LOG_FORMAT        "text" (default) or "json".
+    TINA4_LOG_OUTPUT        "stdout" (default), "file", or "both".
+    TINA4_LOG_ROTATE_SIZE   Bytes per file before rotation. Default 10 MB.
+                            Set to 0 to disable rotation.
+    TINA4_LOG_ROTATE_KEEP   Number of rotated files to keep (default: 5).
+    TINA4_LOG_CRITICAL      When truthy, Log.critical(...) is accepted and
+                            mapped to error level. Default: false.
+    TINA4_LOG_MAX_SIZE      [legacy] Megabytes per file. Used only when
+                            TINA4_LOG_ROTATE_SIZE is unset (back-compat).
+    TINA4_LOG_KEEP          [legacy] Alias for TINA4_LOG_ROTATE_KEEP.
+"""
+import os
+import re
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+
+# Request ID context (set per-request by middleware)
+_request_id_var = threading.local()
+
+# Regex to strip ANSI escape codes
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def set_request_id(request_id: str):
+    """Set the current request ID (called by middleware)."""
+    _request_id_var.id = request_id
+
+
+def get_request_id() -> str | None:
+    """Get the current request ID."""
+    return getattr(_request_id_var, "id", None)
+
+
+def _strip_ansi(text: str) -> str:
+    """Remove ANSI escape codes from text."""
+    return _ANSI_RE.sub("", text)
+
+
+def _is_truthy(val) -> bool:
+    return str(val or "").strip().lower() in ("true", "1", "yes", "on")
+
+
+class _LogWriter:
+    """File writer with numbered rotation support — used as the default
+    fallback when TINA4_LOG_FILE is unset (legacy "logs/tina4.log" path).
+
+    Rotation scheme:
+        tina4.log → tina4.log.1 → tina4.log.2 → ... → tina4.log.{keep}
+    """
+
+    def __init__(self, log_dir: str = "logs", filename: str = "tina4.log",
+                 max_size_mb: int = 10, keep: int = 5):
+        self.log_dir = Path(log_dir)
+        self.filename = filename
+        self.max_size = max_size_mb * 1024 * 1024
+        self.keep = keep
+        self._lock = threading.Lock()
+        self._ensure_dir()
+
+    def _ensure_dir(self):
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def _log_path(self) -> Path:
+        return self.log_dir / self.filename
+
+    def _rotate_if_needed(self):
+        log_path = self._log_path()
+
+        if not log_path.exists():
+            return
+
+        try:
+            if log_path.stat().st_size < self.max_size:
+                return
+        except OSError:
+            return
+
+        # Delete the oldest rotated file if it exists
+        oldest = self.log_dir / f"{self.filename}.{self.keep}"
+        if oldest.exists():
+            try:
+                oldest.unlink()
+            except OSError:
+                pass
+
+        # Shift existing rotated files: .{n} → .{n+1}
+        for n in range(self.keep - 1, 0, -1):
+            src = self.log_dir / f"{self.filename}.{n}"
+            dst = self.log_dir / f"{self.filename}.{n + 1}"
+            if src.exists():
+                try:
+                    src.rename(dst)
+                except OSError:
+                    pass
+
+        # Rename current log to .1
+        try:
+            log_path.rename(self.log_dir / f"{self.filename}.1")
+        except OSError:
+            pass
+
+    def write(self, line: str):
+        """Write a line to the log file, stripping ANSI codes. Rotates if needed."""
+        clean_line = _strip_ansi(line)
+        with self._lock:
+            self._rotate_if_needed()
+            log_path = self._log_path()
+            try:
+                with open(log_path, "a", encoding="utf-8") as f:
+                    f.write(clean_line + "\n")
+            except OSError:
+                pass  # Can't write logs — don't crash the app
+
+
+class _StdlibFileWriter:
+    """Adapter around stdlib logging.handlers.RotatingFileHandler / FileHandler.
+
+    Used when TINA4_LOG_FILE is set explicitly. Keeps the same .write(line)
+    interface as _LogWriter so the Log class doesn't care which backend
+    produced the file output.
+    """
+
+    def __init__(self, path: Path, max_bytes: int, backup_count: int):
+        # Resolve dir up-front so callers can fail fast on a bad path.
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.path = path
+        if max_bytes > 0:
+            self._handler = RotatingFileHandler(
+                str(path),
+                maxBytes=max_bytes,
+                backupCount=backup_count,
+                encoding="utf-8",
+            )
+        else:
+            # 0 disables rotation — use a plain FileHandler so the file just
+            # grows. Matches the documented contract for TINA4_LOG_ROTATE_SIZE=0.
+            self._handler = logging.FileHandler(str(path), encoding="utf-8")
+        # Bare formatter — Log already builds the full line itself.
+        self._handler.setFormatter(logging.Formatter("%(message)s"))
+        self._lock = threading.Lock()
+
+    def write(self, line: str):
+        clean = _strip_ansi(line)
+        record = logging.LogRecord(
+            name="tina4",
+            level=logging.INFO,
+            pathname="",
+            lineno=0,
+            msg=clean,
+            args=(),
+            exc_info=None,
+        )
+        with self._lock:
+            try:
+                self._handler.emit(record)
+                self._handler.flush()
+            except OSError:
+                pass
+
+    def close(self):
+        try:
+            self._handler.close()
+        except Exception:
+            pass
+
+
+class Log:
+    """Structured logger with request ID tracking and log rotation."""
+
+    _writer: _LogWriter | _StdlibFileWriter | None = None
+    _error_writer: _LogWriter | None = None
+    _level: str = "info"
+    _is_production: bool = False
+    _initialized: bool = False
+    # Output toggles — driven by TINA4_LOG_OUTPUT.
+    _stdout_enabled: bool = True
+    _file_enabled: bool = True
+    # Format — "text" or "json". Independent of _is_production so users
+    # can opt into JSON in dev too (TINA4_LOG_FORMAT=json). Stored under
+    # _format_mode so it doesn't clash with the legacy _format() method
+    # name kept below for backward compatibility.
+    _format_mode: str = "text"
+    # Whether Log.critical() is accepted (TINA4_LOG_CRITICAL).
+    _critical_enabled: bool = False
+
+    LEVELS = {"debug": 0, "info": 1, "warning": 2, "error": 3}
+
+    @classmethod
+    def configure(cls, log_dir: str = "logs", level: str = "info",
+                  production: bool = False):
+        """Configure the logger. Called once at startup.
+
+        Reads the new TINA4_LOG_* env vars (rotation size/keep, format,
+        output, file, dir, critical) so individual deployments can tune
+        the logger without code changes. Defaults preserve existing
+        behaviour: file output to logs/tina4.log + stdout, text format,
+        10 MB rotation, keep 5.
+        """
+        cls._level = level.lower()
+        cls._is_production = production
+
+        # ── Output channels ──────────────────────────────────────
+        output = os.environ.get("TINA4_LOG_OUTPUT", "stdout").lower().strip()
+        if output == "file":
+            cls._stdout_enabled = False
+            cls._file_enabled = True
+        elif output == "both":
+            cls._stdout_enabled = True
+            cls._file_enabled = True
+        else:
+            # "stdout" (default) — but we still keep file output on for
+            # parity with v2 behaviour where logs/tina4.log is always
+            # written. Operators who want stdout-only can flip the new
+            # explicit "stdout-only" by setting TINA4_LOG_FILE="" AND
+            # TINA4_LOG_OUTPUT=stdout — handled below where the file
+            # path resolves to empty.
+            cls._stdout_enabled = True
+            cls._file_enabled = True
+
+        # ── Format ───────────────────────────────────────────────
+        fmt = os.environ.get("TINA4_LOG_FORMAT", "text").lower().strip()
+        cls._format_mode = "json" if fmt == "json" else "text"
+
+        # ── Critical level toggle ────────────────────────────────
+        cls._critical_enabled = _is_truthy(os.environ.get("TINA4_LOG_CRITICAL"))
+
+        # ── Rotation config ──────────────────────────────────────
+        # New-style: TINA4_LOG_ROTATE_SIZE in BYTES (0 = disabled).
+        # Legacy: TINA4_LOG_MAX_SIZE in MEGABYTES.
+        rotate_size_env = os.environ.get("TINA4_LOG_ROTATE_SIZE")
+        if rotate_size_env is not None:
+            try:
+                rotate_bytes = int(rotate_size_env)
+            except ValueError:
+                rotate_bytes = 10 * 1024 * 1024
+        else:
+            try:
+                rotate_bytes = int(os.environ.get("TINA4_LOG_MAX_SIZE", "10")) * 1024 * 1024
+            except ValueError:
+                rotate_bytes = 10 * 1024 * 1024
+
+        keep_env = os.environ.get("TINA4_LOG_ROTATE_KEEP", os.environ.get("TINA4_LOG_KEEP", "5"))
+        try:
+            keep = int(keep_env)
+        except ValueError:
+            keep = 5
+
+        # ── File path resolution ─────────────────────────────────
+        log_file = os.environ.get("TINA4_LOG_FILE", "")
+        log_dir_env = os.environ.get("TINA4_LOG_DIR", log_dir)
+
+        # Close any previous writer so reconfigure during tests doesn't
+        # leak file handles.
+        if isinstance(cls._writer, _StdlibFileWriter):
+            cls._writer.close()
+        cls._writer = None
+
+        if log_file:
+            # Explicit log file path. Honour absolute paths verbatim;
+            # otherwise join with TINA4_LOG_DIR per spec.
+            if os.path.isabs(log_file):
+                resolved = Path(log_file)
+            else:
+                resolved = Path(log_dir_env) / log_file
+            cls._writer = _StdlibFileWriter(resolved, rotate_bytes, keep)
+        elif cls._file_enabled:
+            # Default behaviour: keep the existing logs/tina4.log writer
+            # so v2 deployments don't need to change a thing.
+            mb = max(1, rotate_bytes // (1024 * 1024)) if rotate_bytes > 0 else 10
+            cls._writer = _LogWriter(log_dir_env, "tina4.log", mb, keep)
+
+        # Error mirror — only when no explicit TINA4_LOG_FILE is set.
+        # When the operator points at a custom file they almost certainly
+        # don't want a second sibling error.log appearing alongside it.
+        if not log_file and cls._file_enabled:
+            mb = max(1, rotate_bytes // (1024 * 1024)) if rotate_bytes > 0 else 10
+            cls._error_writer = _LogWriter(log_dir_env, "error.log", mb, keep)
+        else:
+            cls._error_writer = None
+
+        cls._initialized = True
+
+    @classmethod
+    def _should_log(cls, level: str) -> bool:
+        return cls.LEVELS.get(level, 0) >= cls.LEVELS.get(cls._level, 0)
+
+    # ANSI color codes for dev mode (matching PHP reference)
+    COLORS = {
+        "debug": "\033[36m",     # Cyan
+        "info": "\033[32m",      # Green
+        "warning": "\033[33m",   # Yellow
+        "error": "\033[31m",     # Red
+    }
+    RESET = "\033[0m"
+
+    @classmethod
+    def _timestamp(cls) -> str:
+        """ISO 8601 UTC timestamp with milliseconds: YYYY-MM-DDTHH:MM:SS.mmmZ"""
+        now = datetime.now(timezone.utc)
+        return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+    @classmethod
+    def _format_line(cls, level: str, message: str, **kwargs) -> str:
+        timestamp = cls._timestamp()
+        request_id = get_request_id()
+
+        # JSON format wins whenever the explicit env opt-in is set,
+        # regardless of production flag (so dev devs can ship JSON to
+        # `jq` if they prefer).
+        if cls._format_mode == "json" or cls._is_production:
+            entry = {
+                "timestamp": timestamp,
+                "level": level.upper(),
+                "message": message,
+            }
+            if request_id:
+                entry["request_id"] = request_id
+            if kwargs:
+                entry["context"] = {k: v for k, v in kwargs.items()}
+            return json.dumps(entry, default=str)
+
+        # Human-readable for development
+        level_str = level.upper().ljust(7)
+        parts = [timestamp, f"[{level_str}]"]
+        if request_id:
+            parts.append(f"[{request_id}]")
+        parts.append(message)
+        if kwargs:
+            parts.append(json.dumps(kwargs, default=str))
+        return " ".join(parts)
+
+    # Kept under the old name so any external code calling Log._format
+    # (e.g. tests) still works.
+    @classmethod
+    def _format(cls, level: str, message: str, **kwargs) -> str:
+        return cls._format_line(level, message, **kwargs)
+
+    @classmethod
+    def _log(cls, level: str, message: str, **kwargs):
+        # File always gets ALL levels (no filtering for file output)
+        line = cls._format_line(level, message, **kwargs)
+
+        # Console output respects TINA4_LOG_LEVEL and the stdout toggle
+        if cls._stdout_enabled and not cls._is_production and cls._should_log(level):
+            color = cls.COLORS.get(level, "")
+            print(f"{color}{line}{cls.RESET}")
+
+        # Always write ALL levels to the main file (raw log, no filtering)
+        if cls._writer:
+            cls._writer.write(line)
+
+        # Mirror WARNING and ERROR into the dedicated error log so
+        # `tail -f logs/error.log` gives just the stuff worth looking
+        # at, without wading through DEBUG / INFO noise. Parity with
+        # tina4-php's Log class.
+        if cls._error_writer and cls.LEVELS.get(level, 0) >= cls.LEVELS["warning"]:
+            cls._error_writer.write(line)
+
+    @classmethod
+    def debug(cls, message: str, **kwargs):
+        cls._log("debug", message, **kwargs)
+
+    @classmethod
+    def info(cls, message: str, **kwargs):
+        cls._log("info", message, **kwargs)
+
+    @classmethod
+    def warning(cls, message: str, **kwargs):
+        cls._log("warning", message, **kwargs)
+
+    @classmethod
+    def error(cls, message: str, **kwargs):
+        cls._log("error", message, **kwargs)
+
+    @classmethod
+    def critical(cls, message: str, **kwargs):
+        """Critical-level log — accepted only when TINA4_LOG_CRITICAL=true.
+
+        Maps to error so existing log consumers (alerting, error.log)
+        keep working. When the toggle is off the call is a no-op so
+        deployments that have standardised on debug/info/warning/error
+        don't get surprise log lines.
+        """
+        if cls._critical_enabled:
+            cls._log("error", message, **kwargs)

{tina4_python-3.12.3 → tina4_python-3.12.4}/tina4_python/dotenv/__init__.py

@@ -17,7 +17,7 @@ import os
 from pathlib import Path
 
 
-def load_env(file_path: str = ".env", override: bool = False) -> dict:
+def load_env(file_path: str = None, override: bool = False) -> dict:
     """Load environment variables from a .env file.
 
     Supports:
@@ -31,12 +31,16 @@ def load_env(file_path: str = ".env", override: bool = False) -> dict:
         multi-word unquoted values
 
     Args:
-        file_path: Path to .env file (default: ".env")
+        file_path: Path to .env file. When None, falls back to the
+            TINA4_ENV_FILE env var, then ".env". This lets ops point at
+            an alternate file (e.g. ".env.staging") without code changes.
         override: If True, overwrite existing env vars (default: False)
 
     Returns:
         Dict of loaded key-value pairs
     """
+    if file_path is None:
+        file_path = os.environ.get("TINA4_ENV_FILE", ".env")
     env_file = Path(file_path)
     loaded = {}
 

{tina4_python-3.12.3 → tina4_python-3.12.4}/tina4_python/frond/engine.py

@@ -10,6 +10,7 @@ import html
 import hashlib
 import json
 import secrets
+import time
 from functools import lru_cache
 from pathlib import Path
 from datetime import datetime
@@ -1270,10 +1271,20 @@ class Frond:
         # Fragment cache (key → (html, expires_at))
         self._fragment_cache: dict[str, tuple[str, float]] = {}
         # Token pre-compilation cache
-        self._compiled: dict[str, tuple[list, float]] = {}  # {template_name: (tokens, mtime)}
+        self._compiled: dict[str, tuple[list, float]] = {}  # {template_name: (tokens, expires_at)}
         self._compiled_strings: dict[str, list] = {}  # {md5_hash: tokens}
         # Filter chain cache: expr → (var_name, [(filter_name, [args])])
         self._filter_chain_cache: dict[str, tuple[str, list]] = {}
+        # Compile-cache TTL — TINA4_TEMPLATE_CACHE_TTL in seconds.
+        # 0 (default) means "no expiry" so the existing permanent-cache
+        # behaviour is preserved. Anything >0 forces re-tokenisation
+        # after that many seconds, which is handy for long-running
+        # workers that want to pick up template edits without a full
+        # restart but without paying the dev-mode "always re-read" tax.
+        try:
+            self._cache_ttl: int = int(os.environ.get("TINA4_TEMPLATE_CACHE_TTL", "0"))
+        except (TypeError, ValueError):
+            self._cache_ttl = 0
 
         # Built-in global functions
         self._globals["form_token"] = _form_token
@@ -1363,18 +1374,22 @@ class Frond:
         debug_mode = os.environ.get("TINA4_DEBUG", "").lower() == "true"
 
         if not debug_mode:
-            # Production: permanent cache, no filesystem checks
+            # Production: cached. If TINA4_TEMPLATE_CACHE_TTL > 0 we honour
+            # the expiry; otherwise the cache is permanent (legacy behaviour).
             cached = self._compiled.get(template)
             if cached is not None:
-                return self._execute_cached(cached[0], context, template)
+                tokens_cached, expires_at = cached
+                if self._cache_ttl <= 0 or time.time() < expires_at:
+                    return self._execute_cached(tokens_cached, context, template)
 
-        # Dev mode: skip cache entirely — always re-read and re-tokenize.
+        # Dev mode (or expired entry): re-read and re-tokenize.
         # mtime-based invalidation doesn't catch changes to included/extended
         # templates (parent or partial changes don't update the caller's mtime).
         source = path.read_text(encoding="utf-8")
         tokens = _tokenize(source)
         if not debug_mode:
-            self._compiled[template] = (tokens, 0)
+            expires_at = (time.time() + self._cache_ttl) if self._cache_ttl > 0 else 0
+            self._compiled[template] = (tokens, expires_at)
         return self._execute_with_source(source, tokens, context, template)
 
     def render_string(self, source: str, data: dict = None) -> str:

{tina4_python-3.12.3 → tina4_python-3.12.4}/tina4_python/graphql/__init__.py

@@ -23,6 +23,7 @@ Supported:
     - Error capture (resolver exceptions become GraphQL errors)
 """
 import json
+import os
 import re
 from typing import Any
 
@@ -464,10 +465,45 @@ def _make_orm_delete_resolver(orm_class, pk_field):
 # ── Executor ──────────────────────────────────────────────────
 
 class GraphQL:
-    """GraphQL engine — parse, validate, execute."""
+    """GraphQL engine — parse, validate, execute.
+
+    Env vars (cross-framework parity v3.12.4):
+        TINA4_GRAPHQL_AUTO_SCHEMA  When truthy (default), discovered ORM
+                                   subclasses passed via auto_register()
+                                   are wired into the schema. Set to false
+                                   to opt out and build the schema manually.
+        TINA4_GRAPHQL_ENDPOINT     Default URL path for the HTTP endpoint
+                                   (default: "/graphql"). Read by .endpoint.
+    """
 
     def __init__(self):
         self.schema = Schema()
+        # Default endpoint URL — env-overridable so deployments can mount
+        # GraphQL at e.g. /api/graphql without changing app code.
+        self.endpoint: str = os.environ.get("TINA4_GRAPHQL_ENDPOINT", "/graphql")
+        # Auto-schema toggle. The flag is stored on the instance so the
+        # outer app can introspect it (e.g. dev_admin shows "auto-schema:
+        # off" in the GraphQL panel) and so test fixtures can flip it
+        # without monkey-patching env.
+        self.auto_schema: bool = str(
+            os.environ.get("TINA4_GRAPHQL_AUTO_SCHEMA", "true")
+        ).strip().lower() in ("true", "1", "yes", "on")
+
+    def auto_register(self, *orm_classes) -> int:
+        """Wire each ORM class into the schema via from_orm().
+
+        No-op when TINA4_GRAPHQL_AUTO_SCHEMA is falsy. Returns the number
+        of classes actually registered. Callers (dev_admin, app bootstrap)
+        use this instead of looping themselves so the env-var gate is
+        honoured in one place.
+        """
+        if not self.auto_schema:
+            return 0
+        count = 0
+        for cls in orm_classes:
+            self.schema.from_orm(cls)
+            count += 1
+        return count
 
     def execute(self, query: str, variables: dict = None, context: dict = None) -> dict:
         """Execute a GraphQL query string. Returns {"data": ..., "errors": [...]}."""