tina4-python 3.13.41__tar.gz → 3.13.43__tar.gz

{tina4_python-3.13.41 → tina4_python-3.13.43}/PKG-INFO

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

{tina4_python-3.13.41 → tina4_python-3.13.43}/pyproject.toml

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

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/CLAUDE.md

@@ -1657,6 +1657,37 @@ TINA4_SWAGGER_LICENSE=            # SPDX license name (e.g. MIT) for info.licens
 TINA4_SWAGGER_SERVERS=            # comma-separated server URLs for the OpenAPI servers[] block; falls back to SWAGGER_DEV_URL
 TINA4_SWAGGER_UI_CDN=             # base URL for the Swagger UI assets (default jsdelivr); point at a self-hosted mirror for air-gapped use
 SWAGGER_DEV_URL=http://localhost:7145  # single dev-server URL (used when TINA4_SWAGGER_SERVERS is unset)
+TINA4_SWAGGER_OPENAPI=3.0.3       # OpenAPI version: 3.0.3 (default) or 3.1 (-> emits 3.1.0)
+TINA4_SWAGGER_BEARER_FORMAT=JWT   # bearerFormat on the built-in bearerAuth scheme (e.g. opaque for sk_live_ keys)
+TINA4_SWAGGER_API_KEY_NAME=       # if set, emit an apiKeyAuth scheme with this header/query name (e.g. X-Api-Key)
+TINA4_SWAGGER_API_KEY_IN=header   # where the apiKey lives: header (default) | query | cookie
+TINA4_SWAGGER_DEFAULT_SCHEME=bearerAuth  # scheme secured routes use when no @security is set
+TINA4_SWAGGER_INCLUDE=            # comma-separated path prefixes to include (allow-list; only these documented)
+TINA4_SWAGGER_EXCLUDE=            # comma-separated path prefixes to drop (/swagger + /__dev are always excluded)
+```
+
+**Per-route security + reusable schemas (v3.13.42).** Configure named security
+schemes (configurable `bearerFormat`, an optional `apiKey` scheme, or register
+arbitrary schemes incl. `oauth2` with scopes via `Swagger.add_security_scheme(name, def)`),
+then declare them per route with `@security`:
+
+```python
+from tina4_python.swagger import security, request_schema, response_schema, Swagger
+
+@security("oauth2", scopes=["read:users"])   # scopes kept only for oauth2/openIdConnect
+@get("/api/v1/users")
+async def list_users(request, response): ...
+
+@security("public")                          # explicitly public (overrides write-secure-by-default)
+@post("/api/v1/webhook")
+async def webhook(request, response): ...
+
+# Reusable component schemas referenced by $ref (beyond ORM-model auto-schemas):
+Swagger.add_schema("CreateUser", {"type": "object", "properties": {"email": {"type": "string"}}})
+@request_schema("CreateUser")
+@response_schema("User", status=200)
+@post("/api/v1/users")
+async def create_user(request, response): ...
 ```
 
 The spec is OpenAPI 3.0.3. ORM models registered via AutoCrud become reusable

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/__init__.py

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

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/queue/__init__.py

@@ -61,7 +61,7 @@ def _resolve_backend(topic: str, backend: str | None, max_retries: int,
         # Consumer-group offsets manage redelivery — framework timeout N/A.
         return KafkaBackend(topic, max_retries)
     elif chosen in ("mongodb", "mongo"):
-        return MongoBackend(topic, max_retries, visibility_timeout)
+        return MongoBackend(topic, max_retries, visibility_timeout, retry_backoff)
     else:
         raise ValueError(f"Unknown queue backend: {chosen!r}. Use 'file', 'rabbitmq', 'kafka', or 'mongodb'.")
 
@@ -82,9 +82,12 @@ class Queue:
                  visibility_timeout: float | None = None):
         self.topic = topic
         self.max_retries = max_retries
-        # Seconds to wait before a failed job is re-attempted (file backend).
+        # Seconds to wait before a failed job is re-attempted.
         # Default 0 = retry on the very next pop()/consume() iteration.
         self.retry_backoff = retry_backoff
+        # Remember an explicit backend= so retargeting a topic (produce/consume)
+        # does not silently fall back to the TINA4_QUEUE_BACKEND env default.
+        self._backend_choice = backend
         # Reservation/visibility timeout (seconds). A popped job is reserved for
         # this long; if the consumer dies before complete()/fail() the next
         # pop() reclaims it (at-least-once delivery). Falls back to
@@ -96,6 +99,24 @@ class Queue:
         self._backend = _resolve_backend(topic, backend, max_retries, retry_backoff,
                                          self.visibility_timeout)
 
+    def _retarget(self, topic: str) -> None:
+        """Point this queue (and its backend) at ``topic`` in place.
+
+        produce()/consume()/process() call this so a topic argument actually
+        changes which topic is read or written. Without it the argument was
+        accepted but ignored on the read path — pop() always used the
+        construction-time topic, so ``consume("other")`` silently drained the
+        wrong queue. Reuses the explicit backend choice (``_backend_choice``)
+        so an explicit ``backend=`` is preserved across the switch.
+        """
+        if topic == self.topic:
+            return
+        self.topic = topic
+        self._backend = _resolve_backend(
+            topic, self._backend_choice, self.max_retries,
+            self.retry_backoff, self.visibility_timeout,
+        )
+
     def push(self, data: dict, priority: int = 0, delay_seconds: int = 0):
         """Add a job to the queue. Returns job ID."""
         return self._backend.push(data, priority, delay_seconds)
@@ -134,6 +155,8 @@ class Queue:
             batch_size: Number of jobs to pass to handler at once (default 1).
                         When > 1, handler receives a list of Jobs.
         """
+        if topic is not None:
+            self._retarget(topic)
         processed = 0
         while max_jobs is None or processed < max_jobs:
             if batch_size > 1:
@@ -235,15 +258,11 @@ class Queue:
             delay_seconds = max(0, offset)
 
         old_topic = self.topic
-        self.topic = topic
-        self._backend = _resolve_backend(topic, None, self.max_retries, self.retry_backoff,
-                                         self.visibility_timeout)
+        self._retarget(topic)
         try:
             return self.push(data, priority, delay_seconds)
         finally:
-            self.topic = old_topic
-            self._backend = _resolve_backend(old_topic, None, self.max_retries, self.retry_backoff,
-                                             self.visibility_timeout)
+            self._retarget(old_topic)
 
     def consume(self, topic: str = None, job_id: str = None, poll_interval: float = 1.0,
                 iterations: int = 0, batch_size: int = 1):
@@ -282,6 +301,10 @@ class Queue:
         import time
 
         topic = topic or self.topic
+        # Honor the topic argument: point the queue (and the backend that
+        # pop()/job.complete()/job.fail() route through) at it. Previously the
+        # argument was ignored and consume() drained the construction-time topic.
+        self._retarget(topic)
 
         if job_id is not None:
             # Consume a specific job by ID — single yield, no polling

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/queue/kafka_backend.py

@@ -54,16 +54,21 @@ class KafkaBackend:
     def purge(self, status: str = "completed"):
         pass  # Kafka does not support purging
 
-    def retry_failed(self) -> int:
-        jobs = self.failed()
+    def retry_failed(self, max_retries: int = None) -> int:
+        jobs = self.failed(max_retries)
         count = 0
         for job in jobs:
             if self.retry_job(job.get("id", "")):
                 count += 1
         return count
 
-    def failed(self) -> list[dict]:
-        """Consume dead_letter topic, republish, return jobs under max_retries."""
+    def failed(self, max_retries: int = None) -> list[dict]:
+        """Consume dead_letter topic, republish, return jobs under max_retries.
+
+        Accepts max_retries to match the LiteBackend contract — Queue.retry_failed()
+        passes it as a kwarg, so without this signature the call raised TypeError.
+        """
+        mr = max_retries if max_retries is not None else self._max_retries
         dl_topic = f"{self._topic}.dead_letter"
         results = []
         requeue = []
@@ -73,7 +78,7 @@ class KafkaBackend:
                 break
             payload = msg.get("payload", msg)
             attempts = msg.get("attempts", 0)
-            if attempts < self._max_retries:
+            if attempts < mr:
                 results.append({"id": msg.get("id"), "data": payload,
                                  "attempts": attempts, "error": msg.get("error")})
             requeue.append(msg)
@@ -81,8 +86,13 @@ class KafkaBackend:
             self._backend.enqueue(dl_topic, msg)
         return results
 
-    def dead_letters(self) -> list[dict]:
-        """Consume dead_letter topic, republish, return jobs at/over max_retries."""
+    def dead_letters(self, max_retries: int = None) -> list[dict]:
+        """Consume dead_letter topic, republish, return jobs at/over max_retries.
+
+        Accepts max_retries to match the LiteBackend contract — Queue.dead_letters()
+        passes it as a kwarg, so without this signature the call raised TypeError.
+        """
+        mr = max_retries if max_retries is not None else self._max_retries
         dl_topic = f"{self._topic}.dead_letter"
         results = []
         requeue = []
@@ -92,7 +102,7 @@ class KafkaBackend:
                 break
             payload = msg.get("payload", msg)
             attempts = msg.get("attempts", 0)
-            if attempts >= self._max_retries:
+            if attempts >= mr:
                 results.append({"id": msg.get("id"), "data": payload,
                                  "attempts": attempts, "error": msg.get("error")})
             requeue.append(msg)

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/queue/mongo_backend.py

@@ -23,11 +23,12 @@ def _future(seconds: int) -> str:
 class MongoBackend:
     """Backend adapter wrapping MongoBackend for the unified Queue API."""
 
-    def __init__(self, topic: str, max_retries: int, visibility_timeout: float = 300.0):
+    def __init__(self, topic: str, max_retries: int, visibility_timeout: float = 300.0,
+                 retry_backoff: float = 0):
         from tina4_python.queue_backends import MongoConnector as _MongoBackend
 
         url = os.environ.get("TINA4_QUEUE_URL", "")
-        config = {"visibility_timeout": visibility_timeout}
+        config = {"visibility_timeout": visibility_timeout, "retry_backoff": retry_backoff}
         if url:
             config["uri"] = url
         self._backend = _MongoBackend(**config)
@@ -70,12 +71,19 @@ class MongoBackend:
         if status == "pending":
             self._backend.clear(self._topic)
 
-    def retry_failed(self) -> int:
+    def retry_failed(self, max_retries: int = None) -> int:
+        # Accept max_retries to match the LiteBackend contract (Queue passes it
+        # as a kwarg) — without this signature, Queue.retry_failed() raised
+        # TypeError on MongoDB.
+        mr = max_retries if max_retries is not None else self._max_retries
         self._backend._ensure_connected()
         result = self._backend._collection.update_many(
             {"topic": self._topic, "status": "failed",
-             "attempts": {"$lt": self._max_retries}},
-            {"$set": {"status": "pending", "error": None}},
+             "attempts": {"$lt": mr}},
+            # Reset available_at so re-queued failed jobs are visible again
+            # (they were reserved with available_at in the future at dequeue).
+            {"$set": {"status": "pending", "error": None, "available_at": _now(),
+                      "reserved_at": None}},
         )
         return result.modified_count
 
@@ -90,8 +98,13 @@ class MongoBackend:
                  "attempts": d.get("attempts", 0), "error": d.get("error")}
                 for d in docs]
 
-    def dead_letters(self) -> list[dict]:
-        """Query the dead_letter collection in MongoDB."""
+    def dead_letters(self, max_retries: int = None) -> list[dict]:
+        """Query the dead_letter collection in MongoDB.
+
+        Accepts max_retries (unused — dead letters are terminal) to match the
+        LiteBackend contract; Queue.dead_letters() passes it as a kwarg, so
+        without this parameter the call raised TypeError on MongoDB.
+        """
         self._backend._ensure_connected()
         dl_topic = f"{self._topic}.dead_letter"
         docs = self._backend._collection.find({"topic": dl_topic})

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/queue/rabbitmq_backend.py

@@ -82,8 +82,8 @@ class RabbitMQBackend:
         if status == "pending":
             self._backend.clear(self._topic)
 
-    def retry_failed(self) -> int:
-        jobs = self.failed()
+    def retry_failed(self, max_retries: int = None) -> int:
+        jobs = self.failed(max_retries)
         count = 0
         for job in jobs:
             job_id = job.get("id", "")
@@ -91,8 +91,13 @@ class RabbitMQBackend:
                 count += 1
         return count
 
-    def failed(self) -> list[dict]:
-        """Drain the dead_letter queue, re-enqueue, and return jobs still under max_retries."""
+    def failed(self, max_retries: int = None) -> list[dict]:
+        """Drain the dead_letter queue, re-enqueue, and return jobs still under max_retries.
+
+        Accepts max_retries to match the LiteBackend contract — Queue.retry_failed()
+        passes it as a kwarg, so without this signature the call raised TypeError.
+        """
+        mr = max_retries if max_retries is not None else self._max_retries
         dl_topic = f"{self._topic}.dead_letter"
         results = []
         requeue = []
@@ -102,7 +107,7 @@ class RabbitMQBackend:
                 break
             payload = msg.get("payload", msg)
             attempts = msg.get("attempts", 0)
-            if attempts < self._max_retries:
+            if attempts < mr:
                 results.append({"id": msg.get("id"), "data": payload,
                                  "attempts": attempts, "error": msg.get("error")})
             requeue.append(msg)
@@ -110,8 +115,13 @@ class RabbitMQBackend:
             self._backend.enqueue(dl_topic, msg)
         return results
 
-    def dead_letters(self) -> list[dict]:
-        """Drain the dead_letter queue, re-enqueue, and return jobs at/over max_retries."""
+    def dead_letters(self, max_retries: int = None) -> list[dict]:
+        """Drain the dead_letter queue, re-enqueue, and return jobs at/over max_retries.
+
+        Accepts max_retries to match the LiteBackend contract — Queue.dead_letters()
+        passes it as a kwarg, so without this signature the call raised TypeError.
+        """
+        mr = max_retries if max_retries is not None else self._max_retries
         dl_topic = f"{self._topic}.dead_letter"
         results = []
         requeue = []
@@ -121,7 +131,7 @@ class RabbitMQBackend:
                 break
             payload = msg.get("payload", msg)
             attempts = msg.get("attempts", 0)
-            if attempts >= self._max_retries:
+            if attempts >= mr:
                 results.append({"id": msg.get("id"), "data": payload,
                                  "attempts": attempts, "error": msg.get("error")})
             requeue.append(msg)

{tina4_python-3.13.41 → tina4_python-3.13.43}/tina4_python/queue_backends/mongo_backend.py

@@ -56,6 +56,14 @@ class MongoConnector:
             ))
         except (TypeError, ValueError):
             self._visibility_timeout = 300.0
+        # Seconds to delay a requeued (rejected/retried) job before it is
+        # eligible again. Default 0 = available on the very next dequeue, so a
+        # fail()'d job retries immediately (matching the file backend) instead
+        # of waiting out the visibility window.
+        try:
+            self._retry_backoff = float(config.get("retry_backoff", 0))
+        except (TypeError, ValueError):
+            self._retry_backoff = 0.0
 
         self._pymongo = None
         self._client = None
@@ -143,6 +151,13 @@ class MongoConnector:
 
         result = doc.get("data", {})
         result["id"] = doc["_id"]
+        # Surface the LIVE document-level attempts/priority, not the push-time
+        # snapshot stored inside ``data``. reclaim_expired()/reject() increment
+        # the top-level ``attempts``; without this the consumer always saw the
+        # original 0, so fail()'s ``attempts >= max_retries`` check never tripped
+        # and a job could be retried forever instead of dead-lettering.
+        result["attempts"] = doc.get("attempts", result.get("attempts", 0))
+        result["priority"] = doc.get("priority", result.get("priority", 0))
         return result
 
     def reclaim_expired(self, topic: str, max_retries: int) -> int:
@@ -201,9 +216,16 @@ class MongoConnector:
         """Reject a message. Optionally requeue it."""
         self._ensure_connected()
         if requeue:
+            # Reset available_at so the requeued job is visible again right away
+            # (or after retry_backoff). dequeue() pushed available_at out to the
+            # reservation expiry; leaving it there stranded a fail()'d job for the
+            # full visibility window instead of retrying it on the next pop().
+            available = _future(self._retry_backoff) if self._retry_backoff > 0 else _now()
             self._collection.update_one(
                 {"_id": message_id, "topic": topic},
-                {"$set": {"status": "pending"}, "$inc": {"attempts": 1}},
+                {"$set": {"status": "pending", "available_at": available,
+                          "reserved_at": None},
+                 "$inc": {"attempts": 1}},
             )
         else:
             self._collection.update_one(