tina4-python 3.13.104__tar.gz → 3.13.106__tar.gz

{tina4_python-3.13.104 → tina4_python-3.13.106}/PKG-INFO

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

{tina4_python-3.13.104 → tina4_python-3.13.106}/pyproject.toml

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

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.104"
+    return "3.13.106"
 
 
 __version__ = _resolve_version()
@@ -74,6 +74,11 @@ from tina4_python.core.router import (  # noqa: E402, F401
     noauth, secured, cached, middleware, template,
     Router, RouteGroup,
 )
+# websocket is not in that tuple. The tina4_python.websocket *subpackage* is
+# itself callable (see tina4_python/websocket/__init__.py) so
+# `from tina4_python import websocket` reaches core.router.websocket without
+# turning `import tina4_python.websocket as ws` into a function. A re-export
+# here would do the latter.
 from tina4_python.core.constants import (  # noqa: E402, F401
     HTTP_OK, HTTP_CREATED, HTTP_ACCEPTED, HTTP_NO_CONTENT,
     HTTP_MOVED, HTTP_REDIRECT, HTTP_NOT_MODIFIED,

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/cli/__init__.py

@@ -825,13 +825,8 @@ def _seed(args):
 
 def _routes(args):
     """List all registered routes."""
-    if Path("app.py").exists():
-        sys.path.insert(0, str(Path.cwd()))
-        import importlib
-        importlib.import_module("app")
-
-    from tina4_python.core.router import Router
-    routes = Router.get_routes()
+    from tina4_python.core import discover_routes
+    routes = discover_routes("src/routes")
     if not routes:
         print("No routes registered.")
         return

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/core/__init__.py

@@ -19,7 +19,7 @@ from tina4_python.core.router import (
 from tina4_python.core.middleware import CorsMiddleware, RateLimiter
 from tina4_python.core.cache import Cache
 from tina4_python.core.events import on, off, emit, emit_async, once, listeners, events, clear as clear_events
-from tina4_python.core.server import run, resolve_config, handle, start, stop
+from tina4_python.core.server import discover_routes, run, resolve_config, handle, start, stop
 
 __all__ = [
     "Request", "Response", "Router",
@@ -28,5 +28,5 @@ __all__ = [
     "CorsMiddleware", "RateLimiter",
     "Cache",
     "on", "off", "emit", "emit_async", "once", "listeners", "events", "clear_events",
-    "run", "resolve_config", "handle", "start", "stop",
+    "discover_routes", "run", "resolve_config", "handle", "start", "stop",
 ]

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/core/router.py

@@ -817,9 +817,23 @@ def noauth():
     def decorator(fn):
         fn._noauth = True
         # If route was already registered (decorator applied after @get/@post),
-        # update the route dict directly.
+        # update the route dict directly AND log the corrected state. The
+        # documented decorator order puts @noauth() ABOVE @get/@post, which
+        # means Python's bottom-up application runs @post first — so
+        # `_register_route` fires its "auth=required" line for a route that
+        # will be public a microsecond later. Without the corrective line
+        # below, the earlier log reads as definitive and misleads anyone
+        # reading startup output (issue #103: an AI reviewer drafted a false
+        # critical-security finding after reading the misleading line).
         if hasattr(fn, "_route_ref"):
-            fn._route_ref._route["auth_required"] = False
+            route = fn._route_ref._route
+            was_required = route.get("auth_required", False)
+            route["auth_required"] = False
+            if was_required:
+                Log.debug(
+                    f"Route auth updated: {route['method']} {route['path']} "
+                    f"(auth=public via @noauth)"
+                )
         return fn
     return decorator
 
@@ -828,10 +842,19 @@ def secured():
     """Require auth on a GET route (which is public by default)."""
     def decorator(fn):
         fn._secured = True
-        # If route was already registered (decorator applied after @get/@post),
-        # update the route dict directly.
+        # See @noauth() above: emit a corrective log line if we flip the flag
+        # on an already-registered route so a reader of the startup log sees
+        # the true final auth state after every decorator has applied
+        # (issue #103).
         if hasattr(fn, "_route_ref"):
-            fn._route_ref._route["auth_required"] = True
+            route = fn._route_ref._route
+            was_public = not route.get("auth_required", True)
+            route["auth_required"] = True
+            if was_public:
+                Log.debug(
+                    f"Route auth updated: {route['method']} {route['path']} "
+                    f"(auth=required via @secured)"
+                )
         # Same for a WebSocket route registered by @websocket() below this one.
         if hasattr(fn, "_ws_route_ref"):
             fn._ws_route_ref["auth_required"] = True

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/core/server.py

@@ -316,6 +316,79 @@ async def background_tick_loop(callback, interval: float, executor, shutdown):
 _discovered_mtimes: dict[str, float] = {}
 
 
+def _cascade_reload_dependents(reloaded: str, root_pkg: str, visited: set[str]) -> None:
+    """After re-importing ``reloaded``, re-import any other in-scope module that
+    still holds a stale ``from <reloaded> import Foo`` reference.
+
+    Fixes https://github.com/tina4stack/tina4-python/issues/102 (hot reload
+    does not re-register ORM field metadata). Root cause: ``_auto_discover``
+    reloads the CHANGED module (say ``src.orm.Todo``) by ``del sys.modules[.]``
+    + ``importlib.import_module(.)``, which builds a fresh class object. But a
+    route module that did ``from src.orm.Todo import Todo`` at ITS first import
+    captured a reference to the OLD class, and unless that module ALSO
+    re-executes, its ``Todo(...)`` call still uses the old class -- with the
+    old ``_fields`` -- so a newly added column is silently absent from
+    ``to_dict()`` output. The DATA is written to the DB correctly (the ORM
+    knows the field via the new class), and the API just lies about it.
+
+    Detection: for every in-scope module already in ``sys.modules``, walk its
+    namespace and look for any attribute whose ``__module__`` matches the
+    reloaded module's name. That's the fingerprint of a ``from X import Y``
+    binding into an unchanged file. Re-import that file so its ``from`` binds
+    to the fresh class. Recurse (a dependent may itself be depended on).
+
+    Bounded to the discovery scope (``root_pkg`` and its subpackages) so we
+    never delete a framework or third-party module. ``visited`` breaks cycles
+    and prevents re-doing a module we already refreshed in this cascade.
+    """
+    # Snapshot: mutating sys.modules during the walk would break iteration.
+    for other_name in list(sys.modules):
+        if other_name in visited:
+            continue
+        if other_name == reloaded:
+            continue
+        if other_name != root_pkg and not other_name.startswith(root_pkg + "."):
+            continue
+        other = sys.modules.get(other_name)
+        if other is None or not hasattr(other, "__dict__"):
+            continue
+        # Any attribute whose __module__ names the reloaded module is a
+        # ``from X import Y`` binding into this file -- it is stale.
+        try:
+            attrs = vars(other)
+        except Exception:
+            continue
+        stale = False
+        for attr_name, attr in attrs.items():
+            if attr_name.startswith("__"):
+                continue
+            if getattr(attr, "__module__", None) == reloaded:
+                stale = True
+                break
+        if not stale:
+            continue
+        try:
+            from tina4_python.core.router import Router
+            Router.remove_routes_for_module(other_name)
+            del sys.modules[other_name]
+            importlib.import_module(other_name)
+            # Record so the next mtime tick sees this reload as authoritative.
+            try:
+                other_path = getattr(sys.modules[other_name], "__file__", None)
+                if other_path:
+                    _discovered_mtimes[other_name] = Path(other_path).stat().st_mtime
+            except OSError:
+                pass
+            visited.add(other_name)
+            Log.info(f"Cascaded reload of dependent module: {other_name}")
+            # A module that imported from `reloaded` may itself be imported
+            # from by yet another module. Cascade the same detection on THIS
+            # module now that its class objects are fresh.
+            _cascade_reload_dependents(other_name, root_pkg, visited)
+        except Exception as exc:
+            Log.error(f"Cascade reload failed for {other_name}: {exc}")
+
+
 def _auto_discover(root_dir: str = "src"):
     """Auto-import all .py files in ``root_dir`` to trigger route decorators.
 
@@ -444,6 +517,14 @@ def _auto_discover(root_dir: str = "src"):
                         f"Reloaded changed module: {module_name}"
                         + (f" (dropped {dropped} stale route(s))" if dropped else "")
                     )
+                    # Cascade to any in-scope module that captured a
+                    # ``from <module_name> import Foo`` binding at ITS first
+                    # import -- that binding still points at the OLD class
+                    # object we just replaced, so the dependent silently uses
+                    # stale field metadata / stale globals until it too
+                    # re-executes. See _cascade_reload_dependents above and
+                    # issue #102.
+                    _cascade_reload_dependents(module_name, root_pkg, {module_name})
                 else:
                     # Out-of-scope module changed — record mtime so we don't
                     # keep re-evaluating it, but do not re-import it.
@@ -468,6 +549,13 @@ def _auto_discover(root_dir: str = "src"):
             pass
 
 
+def discover_routes(root_dir: str = "src/routes"):
+    """Discover application routes without booting the application server."""
+    _auto_discover(root_dir)
+    from tina4_python.core.router import Router
+    return Router.get_routes()
+
+
 def _record_broken_import(py_file: Path, error: Exception) -> None:
     """Write a .broken sentinel so /health and the dev dashboard surface
     auto-discover failures instead of burying them in the console."""

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/orm/model.py

@@ -1363,12 +1363,24 @@ class ORM(metaclass=ORMMeta):
     def clear_cache(cls) -> None:
         """Invalidate every cached query that touches this model's table.
 
-        Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that
-        reads this table is busted too (it carries this table's tag), while a
-        query that never touches this table is left intact. Called after every
-        ORM write (save/delete/force_delete/restore) so a read-after-write never
-        serves a stale/deleted row (CACHE-DEC-01)."""
+        Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+        this table is busted too because it carries this table's tag; a query
+        that never touches this table is left intact), then cascaded to the
+        DB layer on this model's bound connection so an out-of-band write /
+        deliberate refresh / race-with-another-process cannot leave stale rows
+        in db.fetch()'s persistent cache. Called after every ORM write
+        (save/delete/force_delete/restore) so a read-after-write never serves
+        a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+        DB-layer cascade -- previously the two cache layers disagreed
+        under TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true."""
         _query_cache.clear_tag(cls._get_table().lower())
+        try:
+            cls._get_db().cache_clear()
+        except Exception:
+            # A resolvable DB is not guaranteed at every clear_cache call
+            # site (module-import time in odd bootstraps, tests that mutate
+            # bindings); never let a cache-clear crash a save/delete.
+            pass
 
     @classmethod
     def clear_rel_cache(cls) -> None:

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/queue/__init__.py

@@ -182,7 +182,20 @@ class Queue:
                 processed += 1
 
     def size(self, status: str = "pending") -> int:
-        """Count jobs by status."""
+        """Count jobs by status.
+
+        ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+        but-attempted ones, because they live in the pending queue under the
+        auto-retry lifecycle (see failed()).
+        ``"reserved"`` counts jobs a consumer has popped but not yet
+        completed/failed (in-flight against the visibility timeout).
+        ``"completed"`` counts jobs the consumer has finished successfully.
+        ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+        the dead-letter store -- jobs whose attempts >= max_retries and that
+        have given up. Use dead_letters() to list them. Retryable-but-
+        attempted jobs are NOT counted by size("failed"); use failed() to
+        list them or size("pending") to include them in a total.
+        """
         return self._backend.size(status)
 
     def purge(self, status: str, max_retries: int = None) -> int:
@@ -194,14 +207,27 @@ class Queue:
         return self._backend.retry_failed(max_retries=max_retries if max_retries is not None else self.max_retries)
 
     def failed(self) -> list[dict]:
-        """Get jobs that failed but are still eligible for retry."""
+        """Get jobs that failed at least once but are still being retried
+        (0 < attempts < max_retries). These live in the pending queue under
+        the auto-retry lifecycle (fail() re-queues them with an incremented
+        attempts count and a retry_backoff delay) so pop() picks them up
+        again. They are NOT counted by size("failed") -- that alias counts
+        the dead-letter store, matching dead_letters(). To include retryable-
+        failed jobs in a total, use size("pending"). Terminal failures are
+        returned by dead_letters()."""
         return self._backend.failed()
 
     def dead_letters(self, max_retries: int = None) -> list[Job]:
-        """Get jobs that exceeded max retries.
+        """Get jobs that exceeded max_retries -- terminal failures.
+
+        Same set counted by size("failed") / size("dead") / size("dead_letter")
+        (three aliases for the dead-letter store). To LIST retryable-but-
+        attempted jobs (attempts > 0 AND attempts < max_retries) that are
+        still being auto-retried, use failed() -- those live in the pending
+        queue and are NOT dead letters.
 
         Returns ``Job`` objects with the failure reason on ``.error``,
-        not raw dicts — so callers can iterate uniformly with the rest
+        not raw dicts -- so callers can iterate uniformly with the rest
         of the queue API (``for job in queue.consume()``).
 
             for job in queue.dead_letters():
@@ -228,13 +254,22 @@ class Queue:
         ]
 
     def retry(self, job_id: str = None, delay_seconds: int = 0) -> bool:
-        """Retry a failed job by ID, or all dead-letter jobs if no ID given."""
+        """Retry a failed job by ID, or all dead-letter jobs if no ID given.
+
+        The no-arg branch materialises every retry_job() call before returning
+        so ALL dead letters are revived. Pre-3.13.105 (PY-12-04) this branch
+        used ``any(retry_job(j.id) for j in dead)`` -- Python's short-circuit
+        ``any`` stopped iterating as soon as the FIRST job revived, silently
+        leaving the rest in the dead-letter store.
+        """
         if job_id is None:
             dead = self.dead_letters()
             if not dead:
                 return False
-            # dead is now list[Job] — pull the id off each
-            return any(self._backend.retry_job(j.id, delay_seconds) for j in dead)
+            # Materialise: iterate EVERY dead letter, then reduce -- never a
+            # generator inside any().
+            results = [self._backend.retry_job(j.id, delay_seconds) for j in dead]
+            return any(results)
         return self._backend.retry_job(job_id, delay_seconds)
 
     def clear(self) -> int:

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/queue/lite_backend.py

@@ -547,9 +547,23 @@ class LiteBackend:
     def retry(self, job: Job, delay_seconds: int = 0):
         """Explicit re-queue requested by the caller (job.retry()).
 
-        Always re-enqueues regardless of the retry limit — this is a manual
-        override, distinct from the automatic fail() path.
+        Always re-enqueues regardless of the retry limit -- this is a manual
+        override, distinct from the automatic fail() path. Cleans up BOTH the
+        reservation record and any dead-letter file for this id, so a caller
+        who iterates dead_letters() and calls .retry() on each doesn't leave
+        the dead-letter directory carrying duplicates (PY-12-05, 3.13.105).
+        Aligns with retry_job(id) which had always unlinked the dead-letter
+        file -- two spellings of the same intent that previously diverged.
         """
         self._clear_reservation(job.id)
+        # Drop any dead-letter file for this id BEFORE the re-queue -- if this
+        # job came from dead_letters() it lives in _failed_dir() and would
+        # otherwise stay on disk while a fresh pending file appears in
+        # _queue_dir(), so the next dead_letters() call reports the job again
+        # and a consumer processes it twice.
+        try:
+            os.unlink(os.path.join(self._failed_dir(), f"{job.id}.queue-data"))
+        except FileNotFoundError:
+            pass
         job.attempts += 1
         self._requeue(job, delay_seconds=delay_seconds, error=None)

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/queue/mongo_backend.py

@@ -93,9 +93,26 @@ class MongoBackend:
             return 0
         return self._backend.size(self._topic)
 
-    def purge(self, status: str = "completed"):
-        if status == "pending":
-            self._backend.clear(self._topic)
+    def purge(self, status: str = "completed") -> int:
+        """Delete every doc in this queue whose status matches.
+
+        Pre-3.13.105 (PY-12-08) this returned None (not a count), swallowed
+        every status other than ``pending``, and even for ``pending`` called
+        ``clear()`` which delete_many({"topic": topic}) -- nuking ALL statuses
+        under that topic, not just pending. Now every status is honoured, the
+        dead-letter states route to the ``.dead_letter`` topic namespace, and
+        every path returns ``deleted_count`` so a caller can log/assert what
+        was purged.
+        """
+        self._backend._ensure_connected()
+        if status in ("dead", "dead_letter", "failed"):
+            dl_topic = f"{self._topic}.dead_letter"
+            result = self._backend._collection.delete_many({"topic": dl_topic})
+        else:
+            result = self._backend._collection.delete_many(
+                {"topic": self._topic, "status": status}
+            )
+        return result.deleted_count
 
     def retry_failed(self, max_retries: int = None) -> int:
         # Accept max_retries to match the LiteBackend contract (Queue passes it
@@ -154,16 +171,57 @@ class MongoBackend:
                 for d in docs]
 
     def retry_job(self, job_id: str, delay_seconds: int = 0) -> bool:
-        """Reset a failed job back to pending by ID."""
+        """Revive a specific dead-letter job by ID back to the pending queue.
+
+        Pre-3.13.105 this searched
+        ``{_id: job_id, topic: self._topic, status: "failed"}`` -- three
+        separate reasons that filter could never match a dead letter:
+
+          * ``dead_letter()`` writes a NEW doc with a fresh ``_id`` (the
+            original job id is preserved on the doc's ``data.id`` field), so
+            ``_id: job_id`` never hit.
+          * The dead-letter topic is ``f"{topic}.dead_letter"``, not
+            ``self._topic``.
+          * Dead letters carry ``status="dead"`` (the original doc under
+            ``self._topic`` is ``status="completed"`` after the ack).
+
+        The corrected flow looks the doc up in the dead-letter namespace by
+        the original id, deletes the dead-letter record, and re-enqueues the
+        original as pending -- upserting on the small chance the original
+        completed doc has been purged, so a retry after a housekeeping run
+        still works. Mirrors LiteBackend.retry_job() and matches
+        Queue.retry(id) callers' expectation that retry always revives if a
+        dead letter exists for the id.
+        """
         self._backend._ensure_connected()
-        available = _now() if delay_seconds == 0 else _future(delay_seconds)
-        result = self._backend._collection.update_one(
-            {"_id": job_id, "topic": self._topic, "status": "failed"},
+        dl_topic = f"{self._topic}.dead_letter"
+        dl_doc = self._backend._collection.find_one(
+            {"topic": dl_topic, "data.id": job_id}
+        )
+        if dl_doc is None:
+            return False
+        # Drop the dead-letter doc first so an interrupted retry never leaves
+        # both a dead-letter and a fresh pending doc for the same id.
+        self._backend._collection.delete_one({"_id": dl_doc["_id"]})
+        available = _now() if delay_seconds <= 0 else _future(delay_seconds)
+        # dead_letter() stored the ORIGINAL enqueue message under the doc's
+        # ``data`` field (see queue_backends/mongo_backend.py::dead_letter);
+        # its ``payload`` key is the enqueue payload the consumer needs.
+        original = dl_doc.get("data") if isinstance(dl_doc.get("data"), dict) else {}
+        payload = original.get("payload", original.get("data", {}))
+        priority = original.get("priority", dl_doc.get("priority", 0))
+        # Upsert: reset the original doc if it still exists, otherwise
+        # re-create it from the dead-letter payload so a purged/gone original
+        # is not silently a retry-no-op.
+        self._backend._collection.update_one(
+            {"_id": job_id, "topic": self._topic},
             {"$set": {"status": "pending", "error": None,
-                      "available_at": available},
+                      "available_at": available, "reserved_at": None,
+                      "priority": priority, "payload": payload},
              "$inc": {"attempts": 1}},
+            upsert=True,
         )
-        return result.modified_count == 1
+        return True
 
     def clear(self) -> int:
         # The only one of this adapter's six _collection users that forgot to

{tina4_python-3.13.104 → tina4_python-3.13.106}/tina4_python/websocket/__init__.py

@@ -22,6 +22,8 @@ import os
 import uuid
 import time
 from typing import Callable
+import sys as _sys
+from types import ModuleType as _ModuleType
 
 MAGIC_STRING = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 
@@ -961,3 +963,34 @@ __all__ = [
     "OP_TEXT", "OP_BINARY", "OP_CLOSE", "OP_PING", "OP_PONG",
     "CLOSE_NORMAL", "CLOSE_GOING_AWAY", "CLOSE_PROTOCOL_ERROR", "CLOSE_TOO_LARGE",
 ]
+
+
+# ── `@websocket("/path")` on the package name ───────────────────────────────
+# `tina4_python.websocket` is two things at once: this RFC 6455 subpackage,
+# and — to every reader of the docs — the route decorator beside @get/@post.
+# Python binds a submodule onto its parent as soon as the submodule loads, so
+#
+#     from tina4_python import websocket
+#     @websocket("/ws")            # TypeError: 'module' object is not callable
+#
+# died at decorate time and auto-discovery dropped every route from that line
+# onward.
+#
+# A re-export in tina4_python/__init__.py AFTER core.server has already loaded
+# this subpackage is stable (importlib setattr happens on first load only).
+# That still fails the other public surface: `import tina4_python.websocket as
+# ws` would then return the function, so `ws.WebSocketServer` breaks. Making
+# this module callable keeps both: the package name decorates, and the
+# subpackage stays a module. Forward *args/**kwargs so this spelling cannot
+# drift from core.router.websocket. Guard sys.modules — a loader that execs
+# this file without registering it must not KeyError.
+class _CallableWebSocketModule(_ModuleType):
+    def __call__(self, *args, **kwargs):
+        from tina4_python.core.router import websocket as _websocket_route
+
+        return _websocket_route(*args, **kwargs)
+
+
+_self = _sys.modules.get(__name__)
+if _self is not None:
+    _self.__class__ = _CallableWebSocketModule