python-pq 0.4.1__tar.gz → 0.5.1__tar.gz

{python_pq-0.4.1 → python_pq-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-pq
-Version: 0.4.1
+Version: 0.5.1
 Summary: Postgres-backed job queue for Python
 Author: ricwo
 Author-email: ricwo <r@cogram.com>
@@ -35,7 +35,7 @@ Postgres-backed job queue for Python with fork-based worker isolation.
 ## Installation
 
 ```bash
-uv add pq
+uv add python-pq
 ```
 
 Requires PostgreSQL and Python 3.13+.
@@ -152,6 +152,34 @@ pq.schedule(weekly_report, cron="0 9 * * 1")  # Monday 9am
 pq.schedule(report, run_every=timedelta(hours=1), report_type="hourly")
 ```
 
+### Overlap Control
+
+By default, periodic tasks don't overlap — if an instance is still running when the next tick arrives, the tick is skipped:
+
+```python
+# Default: max_concurrent=1, no overlap
+pq.schedule(sync_inventory, run_every=timedelta(minutes=5))
+
+# Opt in to unlimited concurrency (overlap allowed)
+pq.schedule(fast_idempotent_task, run_every=timedelta(seconds=30), max_concurrent=None)
+```
+
+The lock auto-expires after `max_runtime` seconds (or 1 hour by default) for crash safety.
+
+### Multiple Schedules (Key)
+
+Use `key` to register the same function multiple times with different configurations:
+
+```python
+pq.schedule(sync_data, run_every=timedelta(hours=1), key="us", region="us")
+pq.schedule(sync_data, run_every=timedelta(hours=2), key="eu", region="eu")
+
+# Unschedule only the US schedule
+pq.unschedule(sync_data, key="us")
+```
+
+Omitting `key` defaults to `""` — backward-compatible with single-schedule usage.
+
 ### Unscheduling
 
 ```python

{python_pq-0.4.1 → python_pq-0.5.1}/README.md

@@ -14,7 +14,7 @@ Postgres-backed job queue for Python with fork-based worker isolation.
 ## Installation
 
 ```bash
-uv add pq
+uv add python-pq
 ```
 
 Requires PostgreSQL and Python 3.13+.
@@ -131,6 +131,34 @@ pq.schedule(weekly_report, cron="0 9 * * 1")  # Monday 9am
 pq.schedule(report, run_every=timedelta(hours=1), report_type="hourly")
 ```
 
+### Overlap Control
+
+By default, periodic tasks don't overlap — if an instance is still running when the next tick arrives, the tick is skipped:
+
+```python
+# Default: max_concurrent=1, no overlap
+pq.schedule(sync_inventory, run_every=timedelta(minutes=5))
+
+# Opt in to unlimited concurrency (overlap allowed)
+pq.schedule(fast_idempotent_task, run_every=timedelta(seconds=30), max_concurrent=None)
+```
+
+The lock auto-expires after `max_runtime` seconds (or 1 hour by default) for crash safety.
+
+### Multiple Schedules (Key)
+
+Use `key` to register the same function multiple times with different configurations:
+
+```python
+pq.schedule(sync_data, run_every=timedelta(hours=1), key="us", region="us")
+pq.schedule(sync_data, run_every=timedelta(hours=2), key="eu", region="eu")
+
+# Unschedule only the US schedule
+pq.unschedule(sync_data, key="us")
+```
+
+Omitting `key` defaults to `""` — backward-compatible with single-schedule usage.
+
 ### Unscheduling
 
 ```python

{python_pq-0.4.1 → python_pq-0.5.1}/pyproject.toml

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

{python_pq-0.4.1 → python_pq-0.5.1}/src/pq/__init__.py

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

{python_pq-0.4.1 → python_pq-0.5.1}/src/pq/client.py

@@ -235,6 +235,8 @@ class PQ:
         cron: str | croniter | None = None,
         priority: Priority = Priority.NORMAL,
         client_id: str | None = None,
+        max_concurrent: int | None = 1,
+        key: str = "",
         **kwargs: Any,
     ) -> int:
         """Schedule a periodic task.
@@ -249,6 +251,11 @@ class PQ:
             cron: Cron expression string (e.g., "0 9 * * 1") or croniter object.
             priority: Task priority. Higher = higher priority. Defaults to NORMAL.
             client_id: Optional client-provided identifier. Must be unique if provided.
+            max_concurrent: Maximum concurrent executions. Default 1 (no overlap).
+                Set to None for unlimited concurrency. Values > 1 are reserved
+                for future use and raise ValueError.
+            key: Discriminator for multiple schedules of the same function.
+                Defaults to "" (empty string).
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
@@ -257,6 +264,7 @@ class PQ:
         Raises:
             ValueError: If neither run_every nor cron is provided, or if both are.
             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.
             IntegrityError: If client_id already exists.
         """
@@ -264,6 +272,11 @@ class PQ:
             raise ValueError("Either run_every or cron must be provided")
         if run_every is not None and cron is not None:
             raise ValueError("Only one of run_every or cron can be provided")
+        if max_concurrent is not None and max_concurrent > 1:
+            raise ValueError(
+                f"max_concurrent must be 1 or None, got {max_concurrent} "
+                "(values > 1 reserved for future use)"
+            )
 
         # Validate and normalize cron expression
         cron_expr: str | None = None
@@ -295,21 +308,24 @@ class PQ:
                 insert(Periodic)
                 .values(
                     name=name,
+                    key=key,
                     payload=payload,
                     priority=priority,
                     run_every=run_every,
                     cron=cron_expr,
                     next_run=next_run,
                     client_id=client_id,
+                    max_concurrent=max_concurrent,
                 )
                 .on_conflict_do_update(
-                    index_elements=["name"],
+                    index_elements=["name", "key"],
                     set_={
                         "payload": payload,
                         "priority": priority,
                         "run_every": run_every,
                         "cron": cron_expr,
                         "next_run": next_run,
+                        "max_concurrent": max_concurrent,
                     },
                 )
                 .returning(Periodic.id)
@@ -331,18 +347,19 @@ class PQ:
             result = session.execute(stmt)
             return result.rowcount > 0
 
-    def unschedule(self, task: Callable[..., Any]) -> bool:
+    def unschedule(self, task: Callable[..., Any], *, key: str = "") -> bool:
         """Remove a periodic task.
 
         Args:
             task: The scheduled function to remove.
+            key: Discriminator key. Defaults to "" (the default schedule).
 
         Returns:
             True if task was found and deleted, False otherwise.
         """
         name = get_function_path(task)
         with self.session() as session:
-            stmt = delete(Periodic).where(Periodic.name == name)
+            stmt = delete(Periodic).where(Periodic.name == name, Periodic.key == key)
             result = session.execute(stmt)
             return result.rowcount > 0
 

python_pq-0.5.1/src/pq/migrations/versions/20260205T120000Z_a1b2c3d4e5f6_add_max_concurrent.py

@@ -0,0 +1,39 @@
+"""add max_concurrent
+
+Revision ID: a1b2c3d4e5f6
+Revises: 2483bec70083
+Create Date: 2026-02-05 12:00:00 Z
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: Union[str, Sequence[str], None] = "2483bec70083"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add max_concurrent and locked_until columns to pq_periodic."""
+    op.add_column(
+        "pq_periodic",
+        sa.Column("max_concurrent", sa.SmallInteger(), nullable=True),
+    )
+    op.add_column(
+        "pq_periodic",
+        sa.Column("locked_until", sa.DateTime(timezone=True), nullable=True),
+    )
+    # Backfill existing rows to default max_concurrent=1
+    op.execute("UPDATE pq_periodic SET max_concurrent = 1 WHERE max_concurrent IS NULL")
+
+
+def downgrade() -> None:
+    """Remove max_concurrent and locked_until columns from pq_periodic."""
+    op.drop_column("pq_periodic", "locked_until")
+    op.drop_column("pq_periodic", "max_concurrent")

python_pq-0.5.1/src/pq/migrations/versions/20260205T180000Z_b7c8d9e0f1a2_add_periodic_key.py

@@ -0,0 +1,38 @@
+"""add periodic key
+
+Revision ID: b7c8d9e0f1a2
+Revises: a1b2c3d4e5f6
+Create Date: 2026-02-05 18:00:00 Z
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "b7c8d9e0f1a2"
+down_revision: Union[str, Sequence[str], None] = "a1b2c3d4e5f6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add key column to pq_periodic and update unique constraint."""
+    op.add_column(
+        "pq_periodic",
+        sa.Column("key", sa.String(255), nullable=False, server_default=""),
+    )
+    op.drop_constraint("pq_periodic_name_key", "pq_periodic", type_="unique")
+    op.create_unique_constraint(
+        "uq_pq_periodic_name_key", "pq_periodic", ["name", "key"]
+    )
+
+
+def downgrade() -> None:
+    """Remove key column and restore original unique constraint."""
+    op.drop_constraint("uq_pq_periodic_name_key", "pq_periodic", type_="unique")
+    op.drop_column("pq_periodic", "key")
+    op.create_unique_constraint("pq_periodic_name_key", "pq_periodic", ["name"])

{python_pq-0.4.1 → python_pq-0.5.1}/src/pq/models.py

@@ -15,6 +15,7 @@ from sqlalchemy import (
     SmallInteger,
     String,
     Text,
+    UniqueConstraint,
     func,
 )
 from sqlalchemy.dialects.postgresql import JSONB
@@ -76,21 +77,27 @@ class Periodic(Base):
     __tablename__ = "pq_periodic"
     __table_args__ = (
         Index("ix_pq_periodic_priority_next_run", "priority", "next_run"),
+        UniqueConstraint("name", "key"),
     )
 
     id: Mapped[int] = mapped_column(BigInteger, Identity(), primary_key=True)
     client_id: Mapped[str | None] = mapped_column(
         String(255), nullable=True, unique=True, index=True
     )
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    key: Mapped[str] = mapped_column(String(255), nullable=False, server_default="")
     payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
     priority: Mapped[int] = mapped_column(SmallInteger, nullable=False, default=0)
     run_every: Mapped[timedelta | None] = mapped_column(Interval, nullable=True)
     cron: Mapped[str | None] = mapped_column(String(100), nullable=True)
     next_run: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    max_concurrent: Mapped[int | None] = mapped_column(SmallInteger, nullable=True)
     last_run: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )
+    locked_until: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, server_default=func.now()
     )

{python_pq-0.4.1 → python_pq-0.5.1}/src/pq/worker.py

@@ -18,7 +18,7 @@ from typing import TYPE_CHECKING, Any, Protocol
 
 from croniter import croniter
 from loguru import logger
-from sqlalchemy import func, select
+from sqlalchemy import func, or_, select, update
 
 from pq.models import Periodic, Task, TaskStatus
 from pq.registry import resolve_function_path
@@ -558,7 +558,15 @@ def _process_periodic_task(
     try:
         with pq.session() as session:
             # Claim highest priority due periodic task with FOR UPDATE SKIP LOCKED
-            stmt = select(Periodic).where(Periodic.next_run <= func.now())
+            # Filter out tasks that are locked (max_concurrent=1 and locked_until in future)
+            stmt = select(Periodic).where(
+                Periodic.next_run <= func.now(),
+                or_(
+                    Periodic.max_concurrent.is_(None),
+                    Periodic.locked_until.is_(None),
+                    Periodic.locked_until <= func.now(),
+                ),
+            )
             if priorities:
                 stmt = stmt.where(Periodic.priority.in_([p.value for p in priorities]))
             stmt = (
@@ -571,9 +579,16 @@ def _process_periodic_task(
             if periodic is None:
                 return False
 
-            # Get task data
+            # Get task data before expunge
             name = periodic.name
             payload = periodic.payload
+            periodic_id = periodic.id
+            periodic_max_concurrent = periodic.max_concurrent
+
+            # 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
+                periodic.locked_until = func.now() + timedelta(seconds=lock_duration)
 
             # Advance schedule BEFORE execution
             periodic.last_run = func.now()
@@ -623,4 +638,17 @@ def _process_periodic_task(
         elapsed = time.perf_counter() - start
         logger.error(f"Periodic task '{name}' failed after {elapsed:.3f} s: {e}")
 
+    finally:
+        # Clear lock after execution (success or failure)
+        if periodic_max_concurrent is not None:
+            try:
+                with pq.session() as session:
+                    session.execute(
+                        update(Periodic)
+                        .where(Periodic.id == periodic_id)
+                        .values(locked_until=None)
+                    )
+            except Exception as e:
+                logger.error(f"Failed to clear lock for periodic task '{name}': {e}")
+
     return True