tina4-python 3.13.32__tar.gz → 3.13.34__tar.gz

{tina4_python-3.13.32 → tina4_python-3.13.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.13.32
+Version: 3.13.34
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
@@ -74,6 +74,8 @@ cd my-app && tina4 serve
 
 Open http://localhost:7146 — your app is running.
 
+> **Two CLIs:** `tina4` is the cross-language Rust CLI — it scaffolds projects, runs the dev server, and watches files. `tina4python` is the Python package's own CLI for project tasks (`migrate`, `seed`, `generate`, `test`). This guide uses `tina4` to scaffold and run, and `tina4python` for those tasks.
+
 <details>
 <summary><strong>Without the Tina4 CLI (Docker / CI only)</strong></summary>
 
@@ -162,7 +164,7 @@ pip install tina4-python[dev-reload]  # Hot-patching via jurigged
 ### 1. Create a project
 
 ```bash
-tina4python init my-app
+tina4 init python my-app
 cd my-app
 ```
 
@@ -694,13 +696,13 @@ Frond.clear_cache()
 ## Environment
 
 ```bash
-SECRET=your-jwt-secret
+TINA4_SECRET=your-jwt-secret
 TINA4_DATABASE_URL=sqlite:///data/app.db
 TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
 TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
 TINA4_LOCALE=en                      # en, fr, af, zh, ja, es
-TINA4_SESSION_BACKEND=SessionFileHandler
-SWAGGER_TITLE=My API
+TINA4_SESSION_BACKEND=file           # file (default), redis, valkey, mongodb, database
+TINA4_SWAGGER_TITLE=My API
 ```
 
 ## AI Tool Integration

{tina4_python-3.13.32 → tina4_python-3.13.34}/README.md

@@ -42,6 +42,8 @@ cd my-app && tina4 serve
 
 Open http://localhost:7146 — your app is running.
 
+> **Two CLIs:** `tina4` is the cross-language Rust CLI — it scaffolds projects, runs the dev server, and watches files. `tina4python` is the Python package's own CLI for project tasks (`migrate`, `seed`, `generate`, `test`). This guide uses `tina4` to scaffold and run, and `tina4python` for those tasks.
+
 <details>
 <summary><strong>Without the Tina4 CLI (Docker / CI only)</strong></summary>
 
@@ -130,7 +132,7 @@ pip install tina4-python[dev-reload]  # Hot-patching via jurigged
 ### 1. Create a project
 
 ```bash
-tina4python init my-app
+tina4 init python my-app
 cd my-app
 ```
 
@@ -662,13 +664,13 @@ Frond.clear_cache()
 ## Environment
 
 ```bash
-SECRET=your-jwt-secret
+TINA4_SECRET=your-jwt-secret
 TINA4_DATABASE_URL=sqlite:///data/app.db
 TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
 TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
 TINA4_LOCALE=en                      # en, fr, af, zh, ja, es
-TINA4_SESSION_BACKEND=SessionFileHandler
-SWAGGER_TITLE=My API
+TINA4_SESSION_BACKEND=file           # file (default), redis, valkey, mongodb, database
+TINA4_SWAGGER_TITLE=My API
 ```
 
 ## AI Tool Integration

{tina4_python-3.13.32 → tina4_python-3.13.34}/pyproject.toml

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

{tina4_python-3.13.32 → tina4_python-3.13.34}/tina4_python/__init__.py

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

{tina4_python-3.13.32 → tina4_python-3.13.34}/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.32 → tina4_python-3.13.34}/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.32 → tina4_python-3.13.34}/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)