tina4-python 3.13.31__tar.gz → 3.13.33__tar.gz

{tina4_python-3.13.31 → tina4_python-3.13.33}/PKG-INFO

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

{tina4_python-3.13.31 → tina4_python-3.13.33}/pyproject.toml

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

{tina4_python-3.13.31 → tina4_python-3.13.33}/tina4_python/__init__.py

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

{tina4_python-3.13.31 → tina4_python-3.13.33}/tina4_python/cache/__init__.py

@@ -880,7 +880,10 @@ class ResponseCache:
                 self._hits += 1
                 # Move to end (most recently used)
                 self._store.move_to_end(cache_key)
-                return request, response(entry.body, entry.status_code)
+                remaining = max(0, int(round(entry.expires_at - time.monotonic())))
+                hit_response = response(entry.body, entry.status_code)
+                self._set_cache_headers(hit_response, "HIT", remaining)
+                return request, hit_response
 
             self._misses += 1
 
@@ -930,6 +933,11 @@ class ResponseCache:
             self._store[cache_key] = entry
             self._store.move_to_end(cache_key)
 
+        # The handler ran for this request → MISS. Advertise the TTL the
+        # entry was just stored with so clients can see how long the next
+        # HIT will live.
+        self._set_cache_headers(response, "MISS", cache_ttl)
+
         return request, response
 
     # ── Public API ───────────────────────────────────────────────
@@ -965,6 +973,31 @@ class ResponseCache:
 
     # ── Internal helpers ─────────────────────────────────────────
 
+    @staticmethod
+    def _set_cache_headers(response, status: str, ttl: int) -> None:
+        """Set ``X-Cache`` / ``X-Cache-TTL`` on the outgoing response.
+
+        ``status`` is ``"HIT"`` (served from cache) or ``"MISS"`` (handler
+        ran). ``ttl`` is the entry's remaining seconds on a HIT, or the
+        configured TTL on a MISS. We deliberately do NOT emit
+        ``Cache-Control`` — browser-cache directives are the app's call.
+
+        Works with the framework ``Response`` (``add_header``) and with any
+        object exposing a ``headers`` dict, so middleware stubs and other
+        response shapes keep working.
+        """
+        if response is None:
+            return
+        headers = {"X-Cache": status, "X-Cache-TTL": str(int(ttl))}
+        setter = getattr(response, "add_header", None) or getattr(response, "header", None)
+        if callable(setter):
+            for name, value in headers.items():
+                setter(name, value)
+            return
+        existing = getattr(response, "headers", None)
+        if isinstance(existing, dict):
+            existing.update(headers)
+
     @staticmethod
     def _get_route_ttl(request) -> int | None:
         """Check for a per-route cache TTL set via the @cached decorator."""

{tina4_python-3.13.31 → tina4_python-3.13.33}/tina4_python/database/connection.py

@@ -519,7 +519,7 @@ class Database:
         return adapter.execute_many(sql, params_list)
 
     def fetch(self, sql: str, params: list = None,
-              limit: int = 100, offset: int = 0) -> DatabaseResult:
+              limit: int = 100, offset: int = 0, no_cache: bool = False) -> DatabaseResult:
         """Fetch rows with pagination.
 
         v3.13.11 (issue #49 Gap 3): mirror :meth:`execute` and capture
@@ -527,25 +527,32 @@ class Database:
         ``db.get_error()`` returning ``None`` even though the adapter
         had stored the failure on its own ``last_error``. Callers had
         no way to read the cause via the public API.
+
+        ``no_cache=True`` bypasses the query cache for this one call — no
+        lookup and no store — and runs the query straight against the DB.
+        Works in either cache mode (request-scoped auto-cache or persistent
+        DB cache). The default (``False``) preserves today's behaviour.
         """
-        if self._cache_enabled:
+        if self._cache_enabled and not no_cache:
             key = self._cache_key(sql + f":L{limit}:S{offset}", params)
             cached = self._cache_get(key)
             if cached is not None:
                 with self._cache_lock:
                     self._cache_hits += 1
                 return cached
-            adapter = self._get_adapter()
-            try:
-                result = adapter.fetch(sql, params, limit, offset)
-                self.last_error = None
-            except Exception:
-                self.last_error = getattr(adapter, "last_error", None) or self.last_error
-                raise
+            result = self._fetch_direct(sql, params, limit, offset)
             self._cache_set(key, result)
             with self._cache_lock:
                 self._cache_misses += 1
             return result
+        return self._fetch_direct(sql, params, limit, offset)
+
+    def _fetch_direct(self, sql: str, params: list, limit: int, offset: int) -> DatabaseResult:
+        """Run a fetch straight against the adapter — no cache lookup or store.
+
+        Shared by the cached and ``no_cache`` paths so error capture stays
+        identical regardless of caching.
+        """
         adapter = self._get_adapter()
         try:
             result = adapter.fetch(sql, params, limit, offset)
@@ -556,7 +563,7 @@ class Database:
             raise
 
     def fetch_all(self, sql: str, params: list = None,
-                  limit: int = 0, offset: int = 0) -> list[dict]:
+                  limit: int = 0, offset: int = 0, no_cache: bool = False) -> list[dict]:
         """Fetch ALL rows and return the records list directly.
 
         Symmetric with ``fetch_one``. For the common case where you just
@@ -572,26 +579,32 @@ class Database:
         name says ``fetch_all``, so it returns all matching rows. Pre-v3.13.12
         silently truncated to 100. Pass an explicit ``limit=N`` to cap.
 
-        Returns ``[]`` (not ``None``) when no rows match.
+        ``no_cache=True`` bypasses the query cache for this one call (see
+        :meth:`fetch`). Returns ``[]`` (not ``None``) when no rows match.
         """
-        return self.fetch(sql, params, limit, offset).records
+        return self.fetch(sql, params, limit, offset, no_cache=no_cache).records
 
-    def fetch_one(self, sql: str, params: list = None) -> dict | None:
-        if self._cache_enabled:
+    def fetch_one(self, sql: str, params: list = None, no_cache: bool = False) -> dict | None:
+        """Fetch a single row as a dict, or ``None`` when no row matches.
+
+        ``no_cache=True`` bypasses the query cache for this one call — no
+        lookup and no store — and runs the query straight against the DB
+        (see :meth:`fetch`). The default (``False``) preserves today's
+        behaviour.
+        """
+        if self._cache_enabled and not no_cache:
             key = self._cache_key(sql + ":ONE", params)
             cached = self._cache_get(key)
             if cached is not None:
                 with self._cache_lock:
                     self._cache_hits += 1
                 return cached
-            adapter = self._get_adapter()
-            result = adapter.fetch_one(sql, params)
+            result = self._get_adapter().fetch_one(sql, params)
             self._cache_set(key, result)
             with self._cache_lock:
                 self._cache_misses += 1
             return result
-        adapter = self._get_adapter()
-        return adapter.fetch_one(sql, params)
+        return self._get_adapter().fetch_one(sql, params)
 
     def insert(self, table: str, data: dict | list) -> DatabaseResult:
         if self._cache_enabled:

{tina4_python-3.13.31 → tina4_python-3.13.33}/tina4_python/queue/__init__.py

@@ -34,13 +34,13 @@ from tina4_python.queue.kafka_backend import KafkaBackend
 from tina4_python.queue.mongo_backend import MongoBackend
 
 
-def _resolve_backend(topic: str, backend: str | None, max_retries: int):
+def _resolve_backend(topic: str, backend: str | None, max_retries: int, retry_backoff: int = 0):
     """Resolve which backend adapter to use."""
     chosen = backend or os.environ.get("TINA4_QUEUE_BACKEND", "file")
     chosen = chosen.lower().strip()
 
     if chosen in ("file", "default", "lite"):
-        return LiteBackend(topic, max_retries)
+        return LiteBackend(topic, max_retries, retry_backoff)
     elif chosen == "rabbitmq":
         return RabbitMQBackend(topic, max_retries)
     elif chosen == "kafka":
@@ -63,10 +63,13 @@ class Queue:
     """
 
     def __init__(self, topic: str = "default", max_retries: int = 3,
-                 backend: str | None = None):
+                 backend: str | None = None, retry_backoff: int = 0):
         self.topic = topic
         self.max_retries = max_retries
-        self._backend = _resolve_backend(topic, backend, max_retries)
+        # Seconds to wait before a failed job is re-attempted (file backend).
+        # Default 0 = retry on the very next pop()/consume() iteration.
+        self.retry_backoff = retry_backoff
+        self._backend = _resolve_backend(topic, backend, max_retries, retry_backoff)
 
     def push(self, data: dict, priority: int = 0, delay_seconds: int = 0):
         """Add a job to the queue. Returns job ID."""
@@ -208,12 +211,12 @@ class Queue:
 
         old_topic = self.topic
         self.topic = topic
-        self._backend = _resolve_backend(topic, None, self.max_retries)
+        self._backend = _resolve_backend(topic, None, self.max_retries, self.retry_backoff)
         try:
             return self.push(data, priority, delay_seconds)
         finally:
             self.topic = old_topic
-            self._backend = _resolve_backend(old_topic, None, self.max_retries)
+            self._backend = _resolve_backend(old_topic, None, self.max_retries, self.retry_backoff)
 
     def consume(self, topic: str = None, job_id: str = None, poll_interval: float = 1.0,
                 iterations: int = 0, batch_size: int = 1):
@@ -309,6 +312,7 @@ class Queue:
                             data=job_data["data"],
                             priority=job_data.get("priority", 0),
                             attempts=job_data.get("attempts", 0),
+                            error=job_data.get("error"),
                         )
                 except (json.JSONDecodeError, FileNotFoundError):
                     continue

{tina4_python-3.13.31 → tina4_python-3.13.33}/tina4_python/queue/job.py

@@ -20,11 +20,20 @@ class Job:
         return self.payload
 
     def complete(self):
-        """Mark job as completed."""
+        """Mark job as completed. Terminal — the job is done and removed."""
         self.queue._backend.complete(self)
 
     def fail(self, error: str = ""):
-        """Mark job as failed. Will be retried if attempts < max_retries."""
+        """Record a failed attempt.
+
+        Increments ``attempts``. If the job still has retries left
+        (``attempts < max_retries``) it is automatically re-enqueued to the
+        pending queue, so the next ``pop()``/``consume()`` picks it up again
+        (after the queue's ``retry_backoff`` delay, if any). Once it has been
+        attempted ``max_retries`` times it is moved to the dead-letter store,
+        where ``queue.dead_letters()`` returns it. No manual ``retry_failed()``
+        is required.
+        """
         self.queue._backend.fail(self, error)
 
     def reject(self, reason: str = ""):

{tina4_python-3.13.31 → tina4_python-3.13.33}/tina4_python/queue/lite_backend.py

@@ -30,9 +30,13 @@ class LiteBackend:
     Each job is stored as a separate .queue-data JSON file.
     """
 
-    def __init__(self, topic: str, max_retries: int):
+    def __init__(self, topic: str, max_retries: int, retry_backoff: int = 0):
         self._topic = topic
         self._max_retries = max_retries
+        # Seconds to delay a job's next attempt when it is automatically
+        # re-enqueued by fail(). 0 (the default) means retry immediately —
+        # the next pop()/consume() iteration picks it up straight away.
+        self._retry_backoff = retry_backoff
         self._base_path = os.environ.get("TINA4_QUEUE_PATH", "data/queue")
         self._lock = threading.Lock()
         self._seq = 0
@@ -74,29 +78,54 @@ class LiteBackend:
             json.dump(job, f, indent=2, default=str)
         return job_id
 
+    def _available_candidates(self, now: str) -> list:
+        """Return (filename, job_data) for every pending, non-delayed job,
+        ordered by the dequeue policy: highest priority first, ties broken
+        oldest-first by created_at.
+
+        The file *name* is no longer the ordering key — the stored
+        ``priority`` and ``created_at`` fields are. This makes pop()/consume()
+        honour priority instead of being pure FIFO.
+        """
+        queue_dir = self._queue_dir()
+        try:
+            filenames = os.listdir(queue_dir)
+        except FileNotFoundError:
+            return []
+
+        candidates = []
+        for filename in filenames:
+            if not filename.endswith(".queue-data"):
+                continue
+            filepath = os.path.join(queue_dir, filename)
+            try:
+                with open(filepath) as f:
+                    job_data = json.load(f)
+            except (json.JSONDecodeError, FileNotFoundError):
+                continue
+            if job_data.get("status") != "pending":
+                continue
+            if job_data.get("available_at", "") > now:
+                continue  # still delayed
+            candidates.append((filename, job_data))
+
+        # priority DESC, then created_at ASC (oldest first). created_at is an
+        # ISO-8601 string so lexicographic order == chronological order.
+        candidates.sort(
+            key=lambda item: (
+                -int(item[1].get("priority", 0) or 0),
+                item[1].get("created_at", "") or "",
+            )
+        )
+        return candidates
+
     def pop(self, queue_ref) -> Job | None:
         now = _now()
         queue_dir = self._queue_dir()
 
         with self._lock:
-            try:
-                files = sorted(f for f in os.listdir(queue_dir) if f.endswith(".queue-data"))
-            except FileNotFoundError:
-                return None
-
-            for filename in files:
+            for filename, job_data in self._available_candidates(now):
                 filepath = os.path.join(queue_dir, filename)
-                try:
-                    with open(filepath) as f:
-                        job_data = json.load(f)
-                except (json.JSONDecodeError, FileNotFoundError):
-                    continue
-
-                if job_data.get("status") != "pending":
-                    continue
-                if job_data.get("available_at", "") > now:
-                    continue
-
                 # Claim the job by deleting the file
                 try:
                     os.unlink(filepath)
@@ -110,37 +139,25 @@ class LiteBackend:
                     data=job_data["data"],
                     priority=job_data.get("priority", 0),
                     attempts=job_data.get("attempts", 0),
+                    error=job_data.get("error"),
                 )
 
         return None
 
     def pop_batch(self, count: int, queue_ref) -> list:
-        """Pop up to count jobs in one operation. Returns partial batch if fewer available."""
+        """Pop up to count jobs in one operation, highest priority first.
+
+        Returns a partial batch if fewer than ``count`` are available.
+        """
         now = _now()
         queue_dir = self._queue_dir()
         results = []
 
         with self._lock:
-            try:
-                files = sorted(f for f in os.listdir(queue_dir) if f.endswith(".queue-data"))
-            except FileNotFoundError:
-                return []
-
-            for filename in files:
+            for filename, job_data in self._available_candidates(now):
                 if len(results) >= count:
                     break
                 filepath = os.path.join(queue_dir, filename)
-                try:
-                    with open(filepath) as f:
-                        job_data = json.load(f)
-                except (json.JSONDecodeError, FileNotFoundError):
-                    continue
-
-                if job_data.get("status") != "pending":
-                    continue
-                if job_data.get("available_at", "") > now:
-                    continue
-
                 try:
                     os.unlink(filepath)
                 except FileNotFoundError:
@@ -153,45 +170,57 @@ class LiteBackend:
                     data=job_data["data"],
                     priority=job_data.get("priority", 0),
                     attempts=job_data.get("attempts", 0),
+                    error=job_data.get("error"),
                 ))
 
         return results
 
+    # Status aliases that live in the failed/ directory (dead-lettered jobs)
+    # rather than as pending files in the queue directory.
+    _DEAD_STATES = ("failed", "dead", "dead_letter")
+
     def size(self, status: str = "pending") -> int:
-        queue_dir = self._queue_dir()
+        scan_dir = self._failed_dir() if status in self._DEAD_STATES else self._queue_dir()
         count = 0
         try:
-            for filename in os.listdir(queue_dir):
+            for filename in os.listdir(scan_dir):
                 if not filename.endswith(".queue-data"):
                     continue
-                filepath = os.path.join(queue_dir, filename)
+                filepath = os.path.join(scan_dir, filename)
                 try:
                     with open(filepath) as f:
                         job_data = json.load(f)
-                    if job_data.get("status") == status:
-                        count += 1
                 except (json.JSONDecodeError, FileNotFoundError):
                     continue
+                if status in self._DEAD_STATES:
+                    # Every file in failed/ is a dead-letter; count them all
+                    # regardless of the exact stored status string.
+                    count += 1
+                elif job_data.get("status") == status:
+                    count += 1
         except FileNotFoundError:
             pass
         return count
 
     def purge(self, status: str = "completed") -> int:
-        queue_dir = self._queue_dir()
+        scan_dir = self._failed_dir() if status in self._DEAD_STATES else self._queue_dir()
         count = 0
         try:
-            for filename in os.listdir(queue_dir):
+            for filename in os.listdir(scan_dir):
                 if not filename.endswith(".queue-data"):
                     continue
-                filepath = os.path.join(queue_dir, filename)
+                filepath = os.path.join(scan_dir, filename)
                 try:
                     with open(filepath) as f:
                         job_data = json.load(f)
-                    if job_data.get("status") == status:
-                        os.unlink(filepath)
-                        count += 1
                 except (json.JSONDecodeError, FileNotFoundError):
                     continue
+                if status in self._DEAD_STATES or job_data.get("status") == status:
+                    try:
+                        os.unlink(filepath)
+                        count += 1
+                    except FileNotFoundError:
+                        continue
         except FileNotFoundError:
             pass
         return count
@@ -212,6 +241,7 @@ class LiteBackend:
                     if job_data.get("attempts", 0) < limit:
                         job_data["status"] = "pending"
                         job_data["available_at"] = _now()
+                        job_data["created_at"] = _now()
                         prefix = self._next_prefix()
                         new_path = os.path.join(queue_dir, f"{prefix}_{job_data['id']}.queue-data")
                         with open(new_path, "w") as f:
@@ -225,20 +255,28 @@ class LiteBackend:
         return count
 
     def failed(self) -> list[dict]:
-        failed_dir = self._failed_dir()
+        """Jobs that have failed at least once but are still being retried.
+
+        Under the auto-retry lifecycle a failed-but-retryable job lives in the
+        pending queue (not the dead-letter dir), so this scans the queue dir
+        for pending jobs with ``attempts > 0`` that have not yet exhausted
+        their retries. Dead-lettered jobs are returned by dead_letters().
+        """
+        queue_dir = self._queue_dir()
         results = []
         try:
-            for filename in sorted(os.listdir(failed_dir)):
+            for filename in sorted(os.listdir(queue_dir)):
                 if not filename.endswith(".queue-data"):
                     continue
-                filepath = os.path.join(failed_dir, filename)
+                filepath = os.path.join(queue_dir, filename)
                 try:
                     with open(filepath) as f:
                         job_data = json.load(f)
-                    if job_data.get("attempts", 0) < self._max_retries:
-                        results.append(job_data)
                 except (json.JSONDecodeError, FileNotFoundError):
                     continue
+                attempts = job_data.get("attempts", 0)
+                if attempts > 0 and attempts < self._max_retries:
+                    results.append(job_data)
         except FileNotFoundError:
             pass
         return results
@@ -264,17 +302,22 @@ class LiteBackend:
         return results
 
     def retry_job(self, job_id: str, delay_seconds: int = 0) -> bool:
+        """Revive a specific dead-letter job by id back to the pending queue.
+
+        This is a manual override (Queue.retry(job_id)) — it always revives a
+        dead-letter regardless of attempt count, mirroring job.retry(). Returns
+        False only if no dead-letter with that id exists.
+        """
         failed_dir = self._failed_dir()
         queue_dir = self._queue_dir()
         filepath = os.path.join(failed_dir, f"{job_id}.queue-data")
         try:
             with open(filepath) as f:
                 job_data = json.load(f)
-            if job_data.get("attempts", 0) >= self._max_retries:
-                return False
             job_data["status"] = "pending"
             job_data["error"] = None
             job_data["attempts"] = job_data.get("attempts", 0) + 1
+            job_data["created_at"] = _now()
             if delay_seconds > 0:
                 job_data["available_at"] = _future(delay_seconds)
             else:
@@ -305,41 +348,75 @@ class LiteBackend:
         return count
 
     def complete(self, job: Job):
-        # Job file was already deleted on pop — nothing to do
+        # Job file was already deleted on pop — nothing to do. complete() is
+        # terminal: the job is done and gone.
         pass
 
-    def fail(self, job: Job, error: str = ""):
-        job.attempts += 1
+    def _requeue(self, job: Job, delay_seconds: int = 0, error: str | None = None):
+        """Write the job back to the pending queue (queue dir).
+
+        Re-enqueued jobs get a fresh ``created_at`` so within a priority tier
+        they sort behind jobs that have not yet been attempted. ``attempts``
+        already reflects the latest failure count.
+        """
+        available = _now() if delay_seconds <= 0 else _future(delay_seconds)
         job_data = {
             "id": job.id,
             "topic": job.topic,
             "data": job.payload,
-            "status": "failed",
+            "status": "pending",
             "priority": job.priority,
             "attempts": job.attempts,
             "error": error,
-            "failed_at": _now(),
+            "available_at": available,
+            "created_at": _now(),
         }
-        failed_dir = self._failed_dir()
-        os.makedirs(failed_dir, exist_ok=True)
-        filepath = os.path.join(failed_dir, f"{job.id}.queue-data")
+        prefix = self._next_prefix()
+        filepath = os.path.join(self._queue_dir(), f"{prefix}_{job.id}.queue-data")
         with open(filepath, "w") as f:
             json.dump(job_data, f, indent=2, default=str)
 
-    def retry(self, job: Job, delay_seconds: int = 0):
-        job.attempts += 1
-        available = _now() if delay_seconds == 0 else _future(delay_seconds)
+    def _dead_letter(self, job: Job, error: str = ""):
+        """Move the job to the dead-letter (failed) directory. Terminal until
+        a manual retry_failed()/retry() revives it."""
         job_data = {
             "id": job.id,
             "topic": job.topic,
             "data": job.payload,
-            "status": "pending",
+            "status": "dead",
             "priority": job.priority,
             "attempts": job.attempts,
-            "available_at": available,
-            "created_at": _now(),
+            "error": error,
+            "failed_at": _now(),
         }
-        prefix = self._next_prefix()
-        filepath = os.path.join(self._queue_dir(), f"{prefix}_{job.id}.queue-data")
+        failed_dir = self._failed_dir()
+        os.makedirs(failed_dir, exist_ok=True)
+        filepath = os.path.join(failed_dir, f"{job.id}.queue-data")
         with open(filepath, "w") as f:
             json.dump(job_data, f, indent=2, default=str)
+
+    def fail(self, job: Job, error: str = ""):
+        """Record a failed attempt.
+
+        Increments ``attempts``. If the job still has retries left
+        (``attempts < max_retries``) it is automatically re-enqueued to the
+        pending queue — so the next pop()/consume() iteration picks it up
+        again — after an optional ``retry_backoff`` delay. Once it has been
+        attempted ``max_retries`` times (``attempts >= max_retries``) it is
+        moved to the dead-letter store, where dead_letters() returns it.
+        """
+        job.attempts += 1
+        job.error = error
+        if job.attempts < self._max_retries:
+            self._requeue(job, delay_seconds=self._retry_backoff, error=error)
+        else:
+            self._dead_letter(job, error)
+
+    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.
+        """
+        job.attempts += 1
+        self._requeue(job, delay_seconds=delay_seconds, error=None)