tina4-python 3.13.36__tar.gz → 3.13.38__tar.gz

{tina4_python-3.13.36 → tina4_python-3.13.38}/.gitignore

@@ -6,6 +6,8 @@
 /src/templates/index.twig
 /secrets/
 /.env
+/.env.local
+.env.local
 /public/css/test.css
 /sessions/
 /tests/secrets/domain.cert

{tina4_python-3.13.36 → tina4_python-3.13.38}/PKG-INFO

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

{tina4_python-3.13.36 → tina4_python-3.13.38}/pyproject.toml

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

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/CLAUDE.md

@@ -1165,6 +1165,8 @@ queue.purge("completed")
 
 Tina4 includes zero-config SOAP 1.1 support with automatic WSDL generation.
 
+**Security:** SOAP requests containing a `<!DOCTYPE>` (DTD) are rejected with a `Client` fault before parsing — SOAP 1.1 forbids DTDs, and this closes the XML entity-expansion (billion-laughs) and external-entity (XXE) attack surface. An operation that raises returns a `Server` fault whose `<faultstring>` is the real cause **only** in debug mode (`TINA4_DEBUG`); in production it is a generic "Internal server error" and the real cause is written to the log — so a resolver exception never leaks internal state to a SOAP client.
+
 ```python
 from typing import List, Optional
 from tina4_python.wsdl import WSDL, wsdl_operation
@@ -1249,7 +1251,7 @@ result = gql.execute('{ users(limit: 3) { id name } }', variables={}, context={}
 # {"data": {"users": [...]}}
 ```
 
-Supports: queries, mutations, variables, fragments, aliases, `@skip`/`@include` directives, nested selections, list types, inline fragments. Resolver exceptions are captured as GraphQL errors.
+Supports: queries, mutations, variables, fragments, aliases, `@skip`/`@include` directives, nested selections, list types, inline fragments. Resolver exceptions are captured as GraphQL errors — the message is the real cause only in debug mode (`TINA4_DEBUG`); in production it is a generic "Internal server error" (the real cause is logged) so a resolver exception never leaks internal state. **Depth guard:** selection-set nesting is bounded by `TINA4_GRAPHQL_MAX_DEPTH` (default `50`; set `<= 0` to disable). An over-deep query or a circular fragment fails with a `"Query exceeds maximum depth of N"` error instead of overflowing the stack.
 
 | ORM Field | GraphQL Type |
 |-----------|-------------|
@@ -1604,7 +1606,7 @@ Key `.env` settings:
 
 ```bash
 # Authentication
-TINA4_SECRET=your-jwt-secret      # JWT signing (warns + uses a blank, insecure secret if unset)
+TINA4_SECRET=your-jwt-secret      # JWT signing. In DEV (TINA4_DEBUG truthy, not CI/prod) a blank value auto-generates a per-machine secret saved to gitignored .env.local; in CI/prod a blank value warns actionably (set it with `openssl rand -hex 32`)
 TINA4_API_KEY=your-api-key        # Static bearer token for API auth (API_KEY fallback supported)
 TINA4_TOKEN_LIMIT=60              # Token lifetime in minutes (default: 60)
 
@@ -1853,7 +1855,7 @@ async def dashboard(request, response):
 - **2,899 tests** passing across all modules
 - **Production server auto-detect**: `tina4python serve --production` auto-installs uvicorn
 - **`tina4python generate`**: model, route, migration, middleware scaffolding
-- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical reads within a request and flushes on writes; persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL` so instances share one cache with global write-invalidation; `cache_stats()` reports `mode` (request/persistent/off) and `backend`, `cache_clear()`
+- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **off by default — opt-in via `TINA4_AUTO_CACHING=true`** (TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical reads within a request and flushes on writes; it ships OFF because a request-scoped cache can return pre-write state in a read-after-write (`SELECT MAX(id)` before an `INSERT` → duplicate keys), so opt in per read-heavy endpoint. Persistent cross-request cache also opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL` so instances share one cache with global write-invalidation; `cache_stats()` reports `mode` (request/persistent/off) and `backend`, `cache_clear()`
 - **Sessions**: 4 backends (file, Redis/Valkey, MongoDB, database)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: unified backend set — memory (default), file, redis, valkey, memcached, mongodb, database — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/HtmlElement.py

@@ -17,6 +17,25 @@ Usage:
 import html as _html
 
 
+class Raw(str):
+    """Marker for trusted, pre-sanitised HTML that must render UNESCAPED.
+
+    String/scalar children of an HTMLElement are HTML-escaped by default to
+    prevent stored/reflected XSS. Wrap a value in Raw() to opt out of escaping
+    when (and only when) you have already sanitised it yourself.
+
+        HTMLElement("div")("<b>x</b>")        # &lt;b&gt;x&lt;/b&gt;  (escaped)
+        HTMLElement("div")(Raw("<b>x</b>"))   # <b>x</b>              (raw)
+
+    Alias: SafeString.
+    """
+    pass
+
+
+# Alias — some callers/frameworks prefer the SafeString name (matches Frond).
+SafeString = Raw
+
+
 class HTMLElement:
     """A single HTML element that renders itself and its children to a string."""
 
@@ -65,8 +84,13 @@ class HTMLElement:
 
         for child in self.children:
             if isinstance(child, HTMLElement):
+                # Nested elements render themselves (already escape their own children)
+                parts.append(str(child))
+            elif isinstance(child, Raw):
+                # Explicitly trusted markup — emit unescaped
                 parts.append(str(child))
             else:
+                # Plain string/scalar child — escape to defeat XSS
                 parts.append(_html.escape(str(child), quote=True))
 
         parts.append(f"</{self.tag}>")

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/__init__.py

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

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/auth/__init__.py

@@ -49,24 +49,145 @@ class _DualMethod:
         return functools.partial(self._func, obj)
 
 
+def _is_ci() -> bool:
+    """True when running under a CI system.
+
+    Honours the de-facto ``CI`` env var that GitHub Actions, GitLab CI,
+    CircleCI, Travis, etc. all set to a truthy value. We never generate or
+    persist a dev secret in CI — a CI run with a blank secret must surface
+    the actionable warning, not silently mint one.
+    """
+    from tina4_python.dotenv import is_truthy
+    return is_truthy(os.environ.get("CI"))
+
+
+def _is_dev() -> bool:
+    """True when the framework is in development mode (TINA4_DEBUG truthy)."""
+    from tina4_python.dotenv import is_truthy
+    return is_truthy(os.environ.get("TINA4_DEBUG"))
+
+
+def _is_production() -> bool:
+    """True when running in production (TINA4_ENV=production)."""
+    return os.environ.get("TINA4_ENV", "development") == "production"
+
+
+# Actionable message shown when TINA4_SECRET is blank in CI/prod — tells the
+# operator exactly what to set and how. Kept as a constant so the bootstrap
+# and the lazy resolver emit the identical guidance.
+_BLANK_SECRET_WARNING = (
+    "Auth: TINA4_SECRET is not set — JWT signing is insecure. "
+    "Set TINA4_SECRET to a random value (e.g. `openssl rand -hex 32`) "
+    "in your environment or .env before serving traffic."
+)
+
+
+def ensure_dev_secret(cwd: str = None) -> str | None:
+    """Generate a per-machine development JWT secret once, at server boot.
+
+    Fail-safe default for local dev: a blank ``TINA4_SECRET`` used to log a
+    loud warning on every boot even though the developer was never told what
+    to set. Instead, in DEV (and only in dev), we mint a cryptographically
+    random secret, persist it to a gitignored ``.env.local`` so it survives
+    restarts, and set it in the process env for this run.
+
+    Generation happens ONLY when ALL of these hold:
+      * ``TINA4_SECRET`` is currently blank, AND
+      * we are in DEV (``TINA4_DEBUG`` truthy), AND
+      * we are NOT in CI (``CI`` env var not truthy), AND
+      * we are NOT in production (``TINA4_ENV`` != "production").
+
+    SECURITY: never generate or persist a secret in CI or production, and
+    only ever write to ``.env.local`` (gitignored) — never ``.env``. The
+    signing secret must never become a guessable built-in default.
+
+    In CI/prod with a blank secret, this emits the actionable warning instead
+    of generating anything.
+
+    Args:
+        cwd: Directory in which to create/append ``.env.local`` (defaults to
+            the current working directory). Used by tests to point at a temp
+            dir without chdir'ing the whole process.
+
+    Returns:
+        The generated secret string when one was minted, else ``None``.
+    """
+    if os.environ.get("TINA4_SECRET"):
+        return None  # already configured — nothing to do
+
+    if not _is_dev() or _is_ci() or _is_production():
+        # CI / prod / non-dev with a blank secret: warn actionably, never mint.
+        _warn_blank_secret()
+        return None
+
+    # Dev, not CI, not prod, blank secret → mint a per-machine dev secret.
+    new_secret = secrets.token_hex(32)
+    os.environ["TINA4_SECRET"] = new_secret  # available for THIS run immediately
+
+    from pathlib import Path
+    base = Path(cwd) if cwd else Path.cwd()
+    env_local = base / ".env.local"
+    try:
+        # Append (create if missing). A trailing newline keeps the file
+        # parseable if it already held entries without a final newline.
+        prefix = ""
+        if env_local.exists():
+            existing = env_local.read_text(encoding="utf-8")
+            if existing and not existing.endswith("\n"):
+                prefix = "\n"
+        with env_local.open("a", encoding="utf-8") as fh:
+            fh.write(f"{prefix}TINA4_SECRET={new_secret}\n")
+        _log_info(
+            "Auth: generated a development secret, saved to .env.local (gitignored)"
+        )
+    except Exception as exc:
+        # Never crash boot over a file write — keep the in-memory secret for
+        # this run and warn that it won't persist.
+        _log_warning(
+            "Auth: generated a development secret but could not write "
+            f".env.local ({exc}); using it for this run only"
+        )
+    return new_secret
+
+
+def _log_info(message: str) -> None:
+    try:
+        from tina4_python.debug import Log
+        Log.info(message)
+    except Exception:
+        import sys
+        print(message, file=sys.stderr)
+
+
+def _log_warning(message: str) -> None:
+    try:
+        from tina4_python.debug import Log
+        Log.warning(message)
+    except Exception:
+        import sys
+        print(message, file=sys.stderr)
+
+
+def _warn_blank_secret() -> None:
+    _log_warning(_BLANK_SECRET_WARNING)
+
+
 def _resolve_secret(secret: str = None) -> str:
     """Resolve the JWT signing secret.
 
     Reads ``TINA4_SECRET`` from the environment. When neither an explicit
-    secret nor ``TINA4_SECRET`` is set, warns loudly and returns a blank
-    secret — parity with the PHP/Node frameworks. Tina4 never silently signs
-    with a guessable built-in default, which would make tokens forgeable.
+    secret nor ``TINA4_SECRET`` is set, warns loudly with an actionable
+    message and returns a blank secret — parity with the PHP/Node frameworks.
+    Tina4 never silently signs with a guessable built-in default, which would
+    make tokens forgeable. (In dev, ``ensure_dev_secret()`` runs at boot and
+    mints + persists a secret so this blank path is hit only in CI/prod or
+    when auth is used before boot.)
     """
     if secret:
         return secret
     env_secret = os.environ.get("TINA4_SECRET", "")
     if not env_secret:
-        try:
-            from tina4_python.debug import Log
-            Log.warning("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)")
-        except Exception:
-            import sys
-            print("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)", file=sys.stderr)
+        _warn_blank_secret()
         return ""
     return env_secret
 
@@ -403,4 +524,5 @@ class AuthMiddleware:
 __all__ = [
     "Auth", "AuthMiddleware", "get_token", "valid_token", "get_payload",
     "refresh_token", "authenticate_request", "validate_api_key",
+    "ensure_dev_secret",
 ]

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/cli/__init__.py

@@ -71,7 +71,7 @@ def _parse_fields(fields_str: str) -> list[tuple[str, str]]:
 def _parse_flags(args: list[str]) -> tuple[dict, list[str]]:
     """Parse --key value and --flag from args. Returns (flags, positional)."""
     # Boolean-only flags that never take a value argument
-    boolean_flags = {"no-browser", "no-reload", "production", "managed", "all", "clear"}
+    boolean_flags = {"no-browser", "no-reload", "production", "managed", "all", "clear", "json"}
 
     flags = {}
     positional = []
@@ -145,6 +145,7 @@ def main():
         "ai": _ai,
         "generate": _generate,
         "console": _console,
+        "metrics": _metrics,
         "help": _help,
     }
 
@@ -222,6 +223,7 @@ Commands:
   build                         Build distributable package
   ai [--all]                    Install AI coding assistant context
   console                       Start interactive REPL with framework loaded
+  metrics [--top N] [--json] [--fail-on warn|error] [--path DIR]  Rank top code-quality offenders
 
 Generators:
   generate model <Name> [--fields "name:string,price:float"]
@@ -291,6 +293,93 @@ def _console(args=None):
     code.interact(banner=banner, local=local_vars)
 
 
+# ── Metrics ───────────────────────────────────────────────────────────
+
+def _metrics(args):
+    """Report top code-quality offenders (complexity, size, maintainability, tests).
+
+    tina4python metrics                       # human report, scans src/ (or framework)
+    tina4python metrics --top 10              # only the worst 10
+    tina4python metrics --path tina4_python   # scan a specific directory
+    tina4python metrics --json                # machine-readable for CI
+    tina4python metrics --fail-on warn        # exit 1 if any warn/error offender
+    tina4python metrics --fail-on error       # exit 1 only on error-severity
+    """
+    import json
+    from tina4_python.dev_admin import metrics as _m
+
+    flags, _ = _parse_flags(args)
+
+    top = int(flags["top"]) if "top" in flags and str(flags["top"]).isdigit() else 20
+    as_json = "json" in flags
+    path = flags.get("path", "src")
+    fail_on = flags.get("fail-on")
+    if fail_on not in (None, "warn", "error"):
+        print(f"  invalid --fail-on '{fail_on}' (use warn or error)")
+        sys.exit(2)
+
+    result = _m.offenders(path, top=top)
+    summary = result["summary"]
+    found = result["offenders"]
+
+    if "error" in summary:
+        print(f"  metrics error: {summary['error']}")
+        sys.exit(2)
+
+    # Decide exit code from the FULL offender set, not just the printed top-N.
+    # full_analysis is cached, so this reuses the same analysis.
+    all_offenders = _m.offenders(path, top=summary["total_offenders"] or 1)["offenders"]
+    severities = {o["severity"] for o in all_offenders}
+    exit_code = 0
+    if fail_on == "warn" and ({"warn", "error"} & severities):
+        exit_code = 1
+    elif fail_on == "error" and ("error" in severities):
+        exit_code = 1
+
+    if as_json:
+        print(json.dumps({"summary": summary, "offenders": found}, indent=2))
+        sys.exit(exit_code)
+
+    # ── Human report ──────────────────────────────────────────────────
+    use_color = sys.stdout.isatty()
+
+    def _c(text, code):
+        return f"\033[{code}m{text}\033[0m" if use_color else text
+
+    sev_color = {"error": "31", "warn": "33", "info": "2"}  # red / yellow / dim
+
+    print()
+    print(f"  Tina4 Metrics — {summary['scan_mode']} scan ({summary['scan_root']})")
+    print(f"  files: {summary['files_analyzed']}   "
+          f"functions: {summary['total_functions']}   "
+          f"avg complexity: {summary['avg_complexity']}   "
+          f"avg maintainability: {summary['avg_maintainability']}")
+    print(f"  offenders: {summary['total_offenders']} total"
+          + (f" (showing top {len(found)})" if found else ""))
+    print()
+
+    if not found:
+        print("  " + _c("✓ no offenders — clean", "32"))
+        print()
+        sys.exit(exit_code)
+
+    # Compute a column width for the file:line cell so the table lines up.
+    locs = [f"{o['file']}:{o['line']}" for o in found]
+    loc_w = max(len("FILE:LINE"), max(len(s) for s in locs))
+    kind_w = max(len("KIND"), max(len(o["kind"]) for o in found))
+
+    header = f"  {'#':>3}  {'SEVERITY':<8}  {'KIND':<{kind_w}}  {'FILE:LINE':<{loc_w}}  DETAIL"
+    print(_c(header, "1"))
+    print("  " + "-" * (len(header) - 2))
+    for i, o in enumerate(found, 1):
+        sev = o["severity"]
+        sev_cell = _c(f"{sev:<8}", sev_color[sev])
+        print(f"  {i:>3}  {sev_cell}  {o['kind']:<{kind_w}}  "
+              f"{locs[i - 1]:<{loc_w}}  {o['detail']}")
+    print()
+    sys.exit(exit_code)
+
+
 # ── Init ──────────────────────────────────────────────────────────────
 
 def _init(args):
@@ -363,7 +452,7 @@ def _init(args):
     gitignore = target / ".gitignore"
     if not gitignore.exists():
         gitignore.write_text(
-            ".env\n__pycache__/\n*.pyc\n.venv/\ndata/\nlogs/\n"
+            ".env\n.env.local\n__pycache__/\n*.pyc\n.venv/\ndata/\nlogs/\n"
             "sessions/\nsecrets/\n*.db\n",
             encoding="utf-8",
         )

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/core/events.py

@@ -68,30 +68,72 @@ def off(event: str, listener: callable = None):
         ]
 
 
-def emit(event: str, *args, **kwargs) -> list:
+def _log_listener_error(event: str, error: Exception) -> None:
+    """Log a listener failure without ever raising. Visible, never silent."""
+    try:
+        from tina4_python.debug import Log
+        Log.warning(
+            f"Event listener for '{event}' raised "
+            f"{type(error).__name__}: {error}"
+        )
+    except Exception:
+        # The logger itself must never break the event bus. Fall back to
+        # stderr so the failure is still surfaced, never swallowed.
+        import sys
+        print(
+            f"[tina4.events] listener for '{event}' raised "
+            f"{type(error).__name__}: {error}",
+            file=sys.stderr,
+            flush=True,
+        )
+
+
+def emit(event: str, *args, strict: bool = False, **kwargs) -> list:
     """Fire an event synchronously. Returns list of listener results.
 
         results = emit("user.created", user_data)
+
+    Each listener is isolated: if one raises, the error is LOGGED
+    (``Log.warning`` with the event name + error) and the remaining
+    listeners still run. A failed listener contributes a ``None`` slot to
+    the results list, so N listeners always yield N results in priority
+    order. Pass ``strict=True`` to RE-RAISE on the first listener error
+    instead of isolating it. Errors are never silently swallowed.
     """
     results = []
     for _, listener in _listeners.get(event, []):
-        result = listener(*args, **kwargs)
-        results.append(result)
+        try:
+            results.append(listener(*args, **kwargs))
+        except Exception as error:
+            if strict:
+                raise
+            _log_listener_error(event, error)
+            results.append(None)
     return results
 
 
-async def emit_async(event: str, *args, **kwargs) -> list:
+async def emit_async(event: str, *args, strict: bool = False, **kwargs) -> list:
     """Fire an event, awaiting async listeners. Returns list of results.
 
         results = await emit_async("order.placed", order)
+
+    Mirrors :func:`emit` — each awaited listener is isolated: one
+    rejection does not abort the others. On a listener error the failure
+    is LOGGED and a ``None`` slot is appended; ``strict=True`` re-raises
+    on the first error.
     """
     results = []
     for _, listener in _listeners.get(event, []):
-        if asyncio.iscoroutinefunction(listener):
-            result = await listener(*args, **kwargs)
-        else:
-            result = listener(*args, **kwargs)
-        results.append(result)
+        try:
+            if asyncio.iscoroutinefunction(listener):
+                results.append(await listener(*args, **kwargs))
+            else:
+                results.append(listener(*args, **kwargs))
+        except Exception as error:
+            if strict:
+                raise
+            _log_listener_error(event, error)
+            results.append(None)
     return results
 
 

{tina4_python-3.13.36 → tina4_python-3.13.38}/tina4_python/core/middleware.py

@@ -30,8 +30,18 @@ class Middleware:
     """Standardized middleware orchestrator.
 
     Registers middleware classes globally and runs their ``before_*`` /
-    ``after_*`` static methods in alphabetical order. Mirrors the PHP,
-    Ruby and Node.js orchestrators.
+    ``after_*`` static methods. Mirrors the PHP, Ruby and Node.js
+    orchestrators.
+
+    Ordering rule (v3.13.38) — deterministic, never alphabetical:
+
+    * Across middleware classes: REGISTRATION order — the order they were
+      attached via ``Middleware.use`` / ``@middleware`` / ``Router.group``.
+    * Within a single class: DEFINITION order — ``before_*`` / ``after_*``
+      methods run in the order they appear in the class body (Python
+      preserves this in ``__dict__``), NOT ``dir()`` alphabetical order.
+
+    ``before_*`` always runs before the route handler, ``after_*`` after.
     """
 
     _global_middleware: list = []
@@ -81,13 +91,27 @@ class Middleware:
 
     @staticmethod
     def _discover_methods(mw_class, prefix: str) -> list:
-        """Return sorted list of public static method names with ``prefix``."""
-        names = [
-            name
-            for name in dir(mw_class)
-            if name.startswith(prefix) and callable(getattr(mw_class, name, None))
-        ]
-        return sorted(names)
+        """Return prefixed method names in DEFINITION order (not alphabetical).
+
+        Walks the MRO from the base classes up to the most-derived so a
+        subclass's own methods run after the methods it inherits, and uses
+        each class's ``__dict__`` (insertion-ordered in Python 3.7+) to
+        preserve the order methods were written in the source. A subclass
+        override keeps the position of its first definition.
+        """
+        seen = set()
+        names = []
+        klass = mw_class if isinstance(mw_class, type) else type(mw_class)
+        for base in reversed(klass.__mro__):
+            for name in base.__dict__:
+                if (
+                    name.startswith(prefix)
+                    and name not in seen
+                    and callable(getattr(mw_class, name, None))
+                ):
+                    seen.add(name)
+                    names.append(name)
+        return names
 
 
 class CorsMiddleware: