python-pq 0.5.0__tar.gz → 0.5.2__tar.gz

{python_pq-0.5.0 → python_pq-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-pq
-Version: 0.5.0
+Version: 0.5.2
 Summary: Postgres-backed job queue for Python
 Author: ricwo
 Author-email: ricwo <r@cogram.com>
@@ -166,6 +166,34 @@ pq.schedule(fast_idempotent_task, run_every=timedelta(seconds=30), max_concurren
 
 The lock auto-expires after `max_runtime` seconds (or 1 hour by default) for crash safety.
 
+### Pausing & Resuming
+
+Disable a periodic task without removing it:
+
+```python
+# Pause - task stays in the database but won't run
+pq.schedule(sync_inventory, run_every=timedelta(minutes=5), active=False)
+
+# Resume
+pq.schedule(sync_inventory, run_every=timedelta(minutes=5), active=True)
+```
+
+New schedules are active by default.
+
+### 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.5.0 → python_pq-0.5.2}/README.md

@@ -145,6 +145,34 @@ pq.schedule(fast_idempotent_task, run_every=timedelta(seconds=30), max_concurren
 
 The lock auto-expires after `max_runtime` seconds (or 1 hour by default) for crash safety.
 
+### Pausing & Resuming
+
+Disable a periodic task without removing it:
+
+```python
+# Pause - task stays in the database but won't run
+pq.schedule(sync_inventory, run_every=timedelta(minutes=5), active=False)
+
+# Resume
+pq.schedule(sync_inventory, run_every=timedelta(minutes=5), active=True)
+```
+
+New schedules are active by default.
+
+### 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.5.0 → python_pq-0.5.2}/pyproject.toml

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

{python_pq-0.5.0 → python_pq-0.5.2}/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.5.0"
+__version__ = "0.5.2"
 
 __all__ = [
     "PQ",

{python_pq-0.5.0 → python_pq-0.5.2}/src/pq/client.py

@@ -236,6 +236,8 @@ class PQ:
         priority: Priority = Priority.NORMAL,
         client_id: str | None = None,
         max_concurrent: int | None = 1,
+        key: str = "",
+        active: bool = True,
         **kwargs: Any,
     ) -> int:
         """Schedule a periodic task.
@@ -253,6 +255,10 @@ class PQ:
             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).
+            active: Whether the task is active. Inactive tasks are not executed.
+                Defaults to True.
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
@@ -305,6 +311,7 @@ class PQ:
                 insert(Periodic)
                 .values(
                     name=name,
+                    key=key,
                     payload=payload,
                     priority=priority,
                     run_every=run_every,
@@ -312,9 +319,10 @@ class PQ:
                     next_run=next_run,
                     client_id=client_id,
                     max_concurrent=max_concurrent,
+                    active=active,
                 )
                 .on_conflict_do_update(
-                    index_elements=["name"],
+                    index_elements=["name", "key"],
                     set_={
                         "payload": payload,
                         "priority": priority,
@@ -322,6 +330,7 @@ class PQ:
                         "cron": cron_expr,
                         "next_run": next_run,
                         "max_concurrent": max_concurrent,
+                        "active": active,
                     },
                 )
                 .returning(Periodic.id)
@@ -343,18 +352,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.2/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.5.2/src/pq/migrations/versions/20260217T120000Z_c3d4e5f6a7b8_add_periodic_active.py

@@ -0,0 +1,32 @@
+"""add periodic active
+
+Revision ID: c3d4e5f6a7b8
+Revises: b7c8d9e0f1a2
+Create Date: 2026-02-17 12:00:00 Z
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "c3d4e5f6a7b8"
+down_revision: Union[str, Sequence[str], None] = "b7c8d9e0f1a2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add active column to pq_periodic."""
+    op.add_column(
+        "pq_periodic",
+        sa.Column("active", sa.Boolean(), nullable=False, server_default="true"),
+    )
+
+
+def downgrade() -> None:
+    """Remove active column from pq_periodic."""
+    op.drop_column("pq_periodic", "active")

{python_pq-0.5.0 → python_pq-0.5.2}/src/pq/models.py

@@ -6,6 +6,7 @@ from typing import Any
 
 from sqlalchemy import (
     BigInteger,
+    Boolean,
     DateTime,
     Enum,
     Identity,
@@ -15,6 +16,7 @@ from sqlalchemy import (
     SmallInteger,
     String,
     Text,
+    UniqueConstraint,
     func,
 )
 from sqlalchemy.dialects.postgresql import JSONB
@@ -76,19 +78,22 @@ 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)
+    active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="true")
     last_run: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )

{python_pq-0.5.0 → python_pq-0.5.2}/src/pq/worker.py

@@ -560,6 +560,7 @@ def _process_periodic_task(
             # Claim highest priority due periodic task with FOR UPDATE SKIP LOCKED
             # Filter out tasks that are locked (max_concurrent=1 and locked_until in future)
             stmt = select(Periodic).where(
+                Periodic.active.is_(True),
                 Periodic.next_run <= func.now(),
                 or_(
                     Periodic.max_concurrent.is_(None),