python-pq 0.6.3__tar.gz → 0.7.1__tar.gz

{python_pq-0.6.3 → python_pq-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-pq
-Version: 0.6.3
+Version: 0.7.1
 Summary: Postgres-backed job queue for Python
 Keywords: postgres,job-queue,task-queue,background-jobs,worker
 Author: ricwo

{python_pq-0.6.3 → python_pq-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-pq"
-version = "0.6.3"
+version = "0.7.1"
 description = "Postgres-backed job queue for Python"
 readme = "README.md"
 authors = [

{python_pq-0.6.3 → python_pq-0.7.1}/src/pq/__init__.py

@@ -5,7 +5,7 @@ from pq.models import Periodic, Task, TaskStatus
 from pq.priority import Priority
 from pq.worker import PostExecuteHook, PreExecuteHook, TaskTimeoutError
 
-__version__ = "0.6.3"
+__version__ = "0.7.1"
 
 __all__ = [
     "PQ",

{python_pq-0.6.3 → python_pq-0.7.1}/src/pq/client.py

@@ -9,7 +9,8 @@ from typing import Any, Self
 
 from croniter import croniter
 from croniter.croniter import CroniterBadCronError
-from sqlalchemy import create_engine, delete, func, select
+from loguru import logger
+from sqlalchemy import create_engine, delete, func, select, update
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.engine import Engine
 from sqlalchemy.orm import sessionmaker
@@ -507,9 +508,54 @@ class PQ:
             result = session.execute(stmt)
             return result.rowcount
 
+    def reap_stale_tasks(self, threshold: timedelta) -> int:
+        """Mark stale RUNNING tasks as FAILED.
+
+        When a worker dies mid-execution (e.g. pod restart, OOM on the worker
+        process), in-flight tasks stay RUNNING forever because no parent
+        process remains to update their status. This method detects those
+        orphaned rows and transitions them to FAILED.
+
+        Args:
+            threshold: A task is considered stale when
+                ``started_at + threshold < now()``. Should be at least
+                2x ``max_runtime`` to avoid reaping legitimately running
+                tasks, e.g. ``timedelta(seconds=max_runtime * 2)``.
+
+        Returns:
+            Number of tasks reaped.
+        """
+        now = datetime.now(UTC)
+        cutoff = now - threshold
+        with self.session() as session:
+            stmt = (
+                update(Task)
+                .where(
+                    Task.status == TaskStatus.RUNNING,
+                    Task.started_at < cutoff,
+                )
+                .values(
+                    status=TaskStatus.FAILED,
+                    completed_at=now,
+                    error=(
+                        f"Reaped: task still RUNNING after {threshold} "
+                        f"(cutoff={cutoff.isoformat()}). Worker likely died."
+                    ),
+                )
+                .returning(Task.id, Task.name, Task.started_at)
+            )
+            reaped = list(session.execute(stmt).all())
+            for task_id, name, started_at in reaped:
+                logger.warning(
+                    f"Reaped stale task '{name}' (id={task_id},"
+                    f" started_at={started_at})"
+                )
+            return len(reaped)
+
     def run_worker(
         self,
         *,
+        concurrency: int = 1,
         poll_interval: float = 1.0,
         max_runtime: float = 30 * 60,
         priorities: Set[Priority] | None = None,
@@ -519,6 +565,8 @@ class PQ:
         Each task executes in a forked child process for memory isolation.
 
         Args:
+            concurrency: Maximum number of tasks to process simultaneously.
+                Default: 1 (sequential processing).
             poll_interval: Seconds to sleep between polls when idle.
             max_runtime: Maximum execution time per task in seconds. Default: 30 min.
             priorities: If set, only process tasks with these priority levels.
@@ -528,6 +576,7 @@ class PQ:
 
         run_worker(
             self,
+            concurrency=concurrency,
             poll_interval=poll_interval,
             max_runtime=max_runtime,
             priorities=priorities,