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

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

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

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

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

{python_pq-0.7.1 → python_pq-0.7.2}/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.7.1"
+__version__ = "0.7.2"
 
 __all__ = [
     "PQ",

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

@@ -1,6 +1,7 @@
 """PQ client - main interface for task queue."""
 
 import importlib.resources
+import math
 from collections.abc import Callable, Set
 from contextlib import contextmanager
 from datetime import UTC, datetime, timedelta
@@ -10,6 +11,7 @@ from typing import Any, Self
 from croniter import croniter
 from croniter.croniter import CroniterBadCronError
 from loguru import logger
+import sqlalchemy as sa
 from sqlalchemy import create_engine, delete, func, select, update
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.engine import Engine
@@ -21,6 +23,45 @@ from pq.registry import get_function_path
 from pq.serialization import serialize
 
 
+def _validate_max_runtime(max_runtime_seconds: float | None) -> None:
+    """Reject obviously-degenerate per-task ``max_runtime_seconds`` values.
+
+    ``None`` means "use the worker's configured default" and is the
+    common case — nothing to validate. ``0``, negative, NaN, and
+    infinity are all rejected because the downstream enforcement is
+    undefined for those:
+
+    - ``signal.alarm(int(max_runtime_seconds) + 1)`` would fire at 1 s for
+      ``0``, at 0 s (which disables the alarm entirely) for any
+      negative integer ≥ -1, and raise ``ValueError`` from inside
+      the worker for NaN / infinity.
+    - ``max_runtime_seconds * 2`` in the stale-reaper SQL would be ≤ 0 or
+      NaN, making the per-row threshold a no-op or NULL (the global
+      default would apply) — silent surprise vs. the call site's
+      intent.
+    - Periodic ``lock_duration`` already guards with a 3600 s
+      fallback for ``≤ 0`` (``worker.py``), but that fallback exists
+      for the worker-level default, not as a contract for callers.
+
+    None of these are useful behaviours to expose. Failing fast at
+    enqueue/upsert/schedule time keeps the bug at the call site,
+    where it's trivially fixable, instead of producing a confusing
+    runtime surprise hours later.
+    """
+    if max_runtime_seconds is None:
+        return
+    if math.isnan(max_runtime_seconds) or math.isinf(max_runtime_seconds):
+        raise ValueError(
+            f"max_runtime_seconds must be a finite positive number (got {max_runtime_seconds!r}); "
+            f"pass None to use the worker's configured default."
+        )
+    if max_runtime_seconds <= 0:
+        raise ValueError(
+            f"max_runtime_seconds must be > 0 (got {max_runtime_seconds!r}); pass None to "
+            f"use the worker's configured default."
+        )
+
+
 class PQ:
     """Postgres-backed task queue client."""
 
@@ -125,6 +166,7 @@ class PQ:
         run_at: datetime | None = None,
         priority: Priority = Priority.NORMAL,
         client_id: str | None = None,
+        max_runtime_seconds: float | None = None,
         **kwargs: Any,
     ) -> int:
         """Enqueue a one-off task.
@@ -135,15 +177,24 @@ class PQ:
             run_at: When to run the task. Defaults to now.
             priority: Task priority. Higher = higher priority. Defaults to NORMAL.
             client_id: Optional client-provided identifier. Must be unique if provided.
+            max_runtime_seconds: Per-task wall-clock cap in seconds. When ``None`` (the
+                common case), the worker that picks up this task uses its
+                configured default. When set, this specific task gets the
+                supplied ceiling AND the stale-reaper threshold scales with
+                it (``max_runtime_seconds * 2`` if larger than the reaper's global
+                default). Use this for occasionally-long tasks in a fleet
+                whose worker default is sized for typical short work.
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
             Task ID.
 
         Raises:
-            ValueError: If task is a lambda, closure, or cannot be imported.
+            ValueError: If task is a lambda, closure, or cannot be imported,
+                or if ``max_runtime_seconds`` is not None and ``<= 0``.
             IntegrityError: If client_id already exists.
         """
+        _validate_max_runtime(max_runtime_seconds)
         name = get_function_path(task)
         payload = serialize(args, kwargs)
 
@@ -156,6 +207,7 @@ class PQ:
             run_at=run_at,
             priority=priority,
             client_id=client_id,
+            max_runtime_seconds=max_runtime_seconds,
         )
 
         with self.session() as session:
@@ -170,6 +222,7 @@ class PQ:
         run_at: datetime | None = None,
         priority: Priority = Priority.NORMAL,
         client_id: str,
+        max_runtime_seconds: float | None = None,
         **kwargs: Any,
     ) -> int:
         """Enqueue a task, updating if client_id already exists.
@@ -183,14 +236,19 @@ class PQ:
             run_at: When to run the task. Defaults to now.
             priority: Task priority. Higher = higher priority. Defaults to NORMAL.
             client_id: Client-provided identifier. Required for conflict resolution.
+            max_runtime_seconds: Per-task wall-clock cap in seconds. See ``enqueue`` for
+                details. ``None`` (the default) leaves the worker's own
+                configured ``max_runtime_seconds`` in effect.
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
             Task ID.
 
         Raises:
-            ValueError: If task is a lambda, closure, or cannot be imported.
+            ValueError: If task is a lambda, closure, or cannot be imported,
+                or if ``max_runtime_seconds`` is not None and ``<= 0``.
         """
+        _validate_max_runtime(max_runtime_seconds)
         name = get_function_path(task)
         payload = serialize(args, kwargs)
 
@@ -206,6 +264,7 @@ class PQ:
                 priority=priority,
                 status=TaskStatus.PENDING,
                 run_at=run_at,
+                max_runtime_seconds=max_runtime_seconds,
             )
             .on_conflict_do_update(
                 index_elements=["client_id"],
@@ -215,6 +274,7 @@ class PQ:
                     "priority": priority,
                     "status": TaskStatus.PENDING,
                     "run_at": run_at,
+                    "max_runtime_seconds": max_runtime_seconds,
                     "attempts": 0,
                     "started_at": None,
                     "completed_at": None,
@@ -239,6 +299,7 @@ class PQ:
         max_concurrent: int | None = 1,
         key: str = "",
         active: bool = True,
+        max_runtime_seconds: float | None = None,
         **kwargs: Any,
     ) -> int:
         """Schedule a periodic task.
@@ -260,6 +321,14 @@ class PQ:
                 Defaults to "" (empty string).
             active: Whether the task is active. Inactive tasks are not executed.
                 Defaults to True.
+            max_runtime_seconds: Per-execution wall-clock cap in seconds. When ``None``
+                (the common case), each execution uses the worker's configured
+                default. When set, this schedule's executions get the
+                supplied ceiling, and the ``locked_until`` window (used when
+                ``max_concurrent`` is in effect) is extended to match so the
+                lock doesn't expire while the execution is legitimately still
+                running. Periodic tasks are not subject to the stale-task
+                reaper, so this knob is purely about the wall-clock cap.
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
@@ -270,6 +339,7 @@ class PQ:
             ValueError: If cron expression is invalid.
             ValueError: If max_concurrent is greater than 1.
             ValueError: If task is a lambda, closure, or cannot be imported.
+            ValueError: If ``max_runtime_seconds`` is not None and ``<= 0``.
             IntegrityError: If client_id already exists.
         """
         if run_every is None and cron is None:
@@ -281,6 +351,7 @@ class PQ:
                 f"max_concurrent must be 1 or None, got {max_concurrent} "
                 "(values > 1 reserved for future use)"
             )
+        _validate_max_runtime(max_runtime_seconds)
 
         # Validate and normalize cron expression
         cron_expr: str | None = None
@@ -321,6 +392,7 @@ class PQ:
                     client_id=client_id,
                     max_concurrent=max_concurrent,
                     active=active,
+                    max_runtime_seconds=max_runtime_seconds,
                 )
                 .on_conflict_do_update(
                     index_elements=["name", "key"],
@@ -332,6 +404,7 @@ class PQ:
                         "next_run": next_run,
                         "max_concurrent": max_concurrent,
                         "active": active,
+                        "max_runtime_seconds": max_runtime_seconds,
                     },
                 )
                 .returning(Periodic.id)
@@ -516,39 +589,85 @@ class PQ:
         process remains to update their status. This method detects those
         orphaned rows and transitions them to FAILED.
 
+        Tasks enqueued with a per-task ``max_runtime_seconds`` override get a
+        proportionally larger reaper window: the effective threshold for
+        a row is ``max(threshold, max_runtime_seconds * 2)``. This avoids
+        reaping a legitimately long-running task whose declared budget
+        exceeds the global default. NULL ``max_runtime_seconds`` (the
+        common case) falls back to the supplied ``threshold`` unchanged.
+
         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)``.
+            threshold: Default per-task stale window for tasks that don't
+                have a ``max_runtime_seconds`` override (or whose override
+                is smaller than this default). A task is stale when
+                ``started_at + effective_threshold < now()``. Should be
+                at least 2x the worker's own ``max_runtime_seconds``, e.g.
+                ``timedelta(seconds=max_runtime_seconds * 2)``.
 
         Returns:
             Number of tasks reaped.
         """
         now = datetime.now(UTC)
-        cutoff = now - threshold
+        threshold_seconds = threshold.total_seconds()
+        # Per-row effective stale window: the larger of the supplied
+        # default and 2x the row's per-task override (NULL → just the
+        # default). Computed in SQL with ``GREATEST`` + ``COALESCE``
+        # so the reaper stays a single round-trip even when the row
+        # set is heterogeneous in declared budget.
+        effective_threshold_seconds = sa.func.greatest(
+            threshold_seconds,
+            sa.func.coalesce(Task.max_runtime_seconds * 2, threshold_seconds),
+        )
+        stale_cutoff = sa.func.now() - sa.func.make_interval(
+            sa.literal(0),  # years
+            sa.literal(0),  # months
+            sa.literal(0),  # weeks
+            sa.literal(0),  # days
+            sa.literal(0),  # hours
+            sa.literal(0),  # mins
+            effective_threshold_seconds,  # secs
+        )
+        # Per-row ``error`` message includes the values that actually
+        # decided this row's fate: the row's own
+        # ``max_runtime_seconds`` (or ``NULL`` if unset) and the
+        # effective threshold the reaper applied. This avoids the
+        # operator needing a separate query to figure out "why did MY
+        # long-budget task get reaped?" — the answer is in the row.
+        # Built with Postgres ``format()`` so the message is computed
+        # per row in the same UPDATE round-trip.
+        per_row_error = sa.func.format(
+            "Reaped: task still RUNNING past its stale window "
+            "(default threshold=%s s, per-task max_runtime_seconds=%s, "
+            "effective threshold=%s s). Worker likely died.",
+            threshold_seconds,
+            sa.func.coalesce(sa.cast(Task.max_runtime_seconds, sa.String), "NULL"),
+            effective_threshold_seconds,
+        )
         with self.session() as session:
             stmt = (
                 update(Task)
                 .where(
                     Task.status == TaskStatus.RUNNING,
-                    Task.started_at < cutoff,
+                    Task.started_at < stale_cutoff,
                 )
                 .values(
                     status=TaskStatus.FAILED,
                     completed_at=now,
-                    error=(
-                        f"Reaped: task still RUNNING after {threshold} "
-                        f"(cutoff={cutoff.isoformat()}). Worker likely died."
-                    ),
+                    error=per_row_error,
+                )
+                .returning(
+                    Task.id,
+                    Task.name,
+                    Task.started_at,
+                    Task.max_runtime_seconds,
                 )
-                .returning(Task.id, Task.name, Task.started_at)
             )
             reaped = list(session.execute(stmt).all())
-            for task_id, name, started_at in reaped:
+            for task_id, name, started_at, max_runtime_seconds in reaped:
                 logger.warning(
                     f"Reaped stale task '{name}' (id={task_id},"
-                    f" started_at={started_at})"
+                    f" started_at={started_at},"
+                    f" max_runtime_seconds={max_runtime_seconds})"
                 )
             return len(reaped)
 

python_pq-0.7.2/src/pq/migrations/versions/20260527T170136Z_aee3e8e7e647_add_task_max_runtime_seconds.py

@@ -0,0 +1,50 @@
+"""add max_runtime_seconds to pq_tasks and pq_periodic
+
+Revision ID: aee3e8e7e647
+Revises: c3d4e5f6a7b8
+Create Date: 2026-05-27 17:01:36 Z
+
+Per-task override for the worker's wall-clock ``max_runtime`` cap, on
+both one-off tasks (``pq_tasks``) and periodic schedules
+(``pq_periodic``). Nullable on both so every existing row (and every
+existing enqueue / schedule call site that doesn't pass the new
+parameter) keeps the previous behaviour exactly — a NULL value tells
+the worker to use its own default.
+
+Schema impact on populated tables is intentionally minimal: PostgreSQL
+11+ treats ``ADD COLUMN ... DEFAULT NULL`` as a catalog-only operation
+(no table rewrite, brief ACCESS EXCLUSIVE lock on the system catalog
+row, typically < 100 ms even for tables with millions of rows). No
+backfill — NULL is the intended default.
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "aee3e8e7e647"
+down_revision: Union[str, Sequence[str], None] = "c3d4e5f6a7b8"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add the nullable ``max_runtime_seconds`` column to both task tables."""
+    op.add_column(
+        "pq_tasks",
+        sa.Column("max_runtime_seconds", sa.Float(), nullable=True),
+    )
+    op.add_column(
+        "pq_periodic",
+        sa.Column("max_runtime_seconds", sa.Float(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    """Remove the ``max_runtime_seconds`` column from both task tables."""
+    op.drop_column("pq_periodic", "max_runtime_seconds")
+    op.drop_column("pq_tasks", "max_runtime_seconds")

{python_pq-0.7.1 → python_pq-0.7.2}/src/pq/models.py

@@ -9,6 +9,7 @@ from sqlalchemy import (
     Boolean,
     DateTime,
     Enum,
+    Float,
     Identity,
     Index,
     Integer,
@@ -70,6 +71,14 @@ class Task(Base):
     )
     error: Mapped[str | None] = mapped_column(Text, nullable=True)
     attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # Per-task override of the worker-level ``max_runtime``. When NULL
+    # (the common case), the worker uses its configured default. When
+    # set, it caps this specific task's wall-clock at the given number
+    # of seconds AND extends the stale-reaper threshold proportionally
+    # (the reaper picks the larger of its global default and
+    # ``max_runtime_seconds * 2``). Useful for occasionally-long tasks
+    # in a fleet whose default is sized for typical short work.
+    max_runtime_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
 
 
 class Periodic(Base):
@@ -94,6 +103,17 @@ class Periodic(Base):
     next_run: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
     max_concurrent: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
     active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="true")
+    # Per-task override of the worker-level ``max_runtime``. Same semantics
+    # as ``Task.max_runtime_seconds`` — NULL means "use the worker's
+    # configured default", a set value caps this specific schedule's
+    # wall-clock at the given number of seconds and also extends the
+    # ``locked_until`` window (when ``max_concurrent`` is in effect) so
+    # the lock doesn't expire while the task is legitimately still
+    # running. Periodic tasks are not subject to the stale-task reaper
+    # (they're guarded by ``locked_until`` and the natural re-fire of
+    # the schedule), so this knob is purely about the per-execution
+    # wall-clock cap.
+    max_runtime_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
     last_run: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )

{python_pq-0.7.1 → python_pq-0.7.2}/src/pq/worker.py

@@ -596,6 +596,10 @@ def _process_one_off_task(
             name = task.name
             payload = task.payload
             task_id = task.id
+            # Per-task ``max_runtime_seconds`` (NULL → use worker default).
+            # Read while still in the session because the row is expunged
+            # below for the forked-child handoff.
+            task_max_runtime = task.max_runtime_seconds
 
             # Flush to commit status changes, then expunge for forked process
             session.flush()
@@ -605,6 +609,14 @@ def _process_one_off_task(
         logger.error(f"Error claiming task: {e}")
         return False
 
+    # Effective per-task wall-clock ceiling: per-task value when set,
+    # otherwise the worker's configured default. The reaper applies the
+    # same rule on its own (see ``Client.reap_stale_tasks``), so the
+    # two stay in sync without the worker having to coordinate.
+    effective_max_runtime = (
+        task_max_runtime if task_max_runtime is not None else max_runtime
+    )
+
     # Phase 2: Execute handler in forked process
     start = time.perf_counter()
     status = TaskStatus.COMPLETED
@@ -617,7 +629,7 @@ def _process_one_off_task(
             handler,
             args,
             kwargs,
-            max_runtime=max_runtime,
+            max_runtime=effective_max_runtime,
             task=task,
             pre_execute=pre_execute,
             post_execute=post_execute,
@@ -739,10 +751,27 @@ def _process_periodic_task(
             payload = periodic.payload
             periodic_id = periodic.id
             periodic_max_concurrent = periodic.max_concurrent
+            # Per-schedule ``max_runtime_seconds`` (NULL → use worker default).
+            # Read while still in the session because the row is expunged
+            # below for the forked-child handoff.
+            periodic_max_runtime = periodic.max_runtime_seconds
+
+            # Effective per-execution wall-clock ceiling: per-schedule value
+            # when set, otherwise the worker's configured default. Drives
+            # both the in-child timeout enforcement AND the
+            # ``locked_until`` window so the lock doesn't expire while a
+            # legitimately-long execution is still running.
+            effective_max_runtime = (
+                periodic_max_runtime
+                if periodic_max_runtime is not None
+                else max_runtime
+            )
 
             # Set lock before execution if concurrency is limited
             if periodic.max_concurrent is not None:
-                lock_duration = max_runtime if max_runtime > 0 else 3600
+                lock_duration = (
+                    effective_max_runtime if effective_max_runtime > 0 else 3600
+                )
                 periodic.locked_until = func.now() + timedelta(seconds=lock_duration)
 
             # Advance schedule BEFORE execution
@@ -769,7 +798,7 @@ def _process_periodic_task(
             handler,
             args,
             kwargs,
-            max_runtime=max_runtime,
+            max_runtime=effective_max_runtime,
             task=periodic,
             pre_execute=pre_execute,
             post_execute=post_execute,
@@ -851,6 +880,9 @@ def _claim_and_fork_one_off(
             name = task.name
             payload = task.payload
             task_id = task.id
+            # Per-task ``max_runtime_seconds`` (NULL → use worker default).
+            # Same handling as the sequential ``_process_one_off_task`` path.
+            task_max_runtime = task.max_runtime_seconds
 
             session.flush()
             session.expunge(task)
@@ -859,6 +891,10 @@ def _claim_and_fork_one_off(
         logger.error(f"Error claiming task: {e}")
         return None
 
+    effective_max_runtime = (
+        task_max_runtime if task_max_runtime is not None else max_runtime
+    )
+
     try:
         handler = resolve_function_path(name)
         args, kwargs = deserialize(payload)
@@ -866,7 +902,7 @@ def _claim_and_fork_one_off(
             handler,
             args,
             kwargs,
-            max_runtime=max_runtime,
+            max_runtime=effective_max_runtime,
             task=task,
             pre_execute=pre_execute,
             post_execute=post_execute,
@@ -934,9 +970,20 @@ def _claim_and_fork_periodic(
             payload = periodic.payload
             periodic_id = periodic.id
             periodic_max_concurrent = periodic.max_concurrent
+            # Per-schedule ``max_runtime_seconds`` (NULL → use worker default).
+            # Same handling as the sequential ``_process_periodic_task`` path.
+            periodic_max_runtime = periodic.max_runtime_seconds
+
+            effective_max_runtime = (
+                periodic_max_runtime
+                if periodic_max_runtime is not None
+                else max_runtime
+            )
 
             if periodic.max_concurrent is not None:
-                lock_duration = max_runtime if max_runtime > 0 else 3600
+                lock_duration = (
+                    effective_max_runtime if effective_max_runtime > 0 else 3600
+                )
                 periodic.locked_until = func.now() + timedelta(seconds=lock_duration)
 
             periodic.last_run = func.now()
@@ -959,7 +1006,7 @@ def _claim_and_fork_periodic(
             handler,
             args,
             kwargs,
-            max_runtime=max_runtime,
+            max_runtime=effective_max_runtime,
             task=periodic,
             pre_execute=pre_execute,
             post_execute=post_execute,