python-pq 0.2.3__tar.gz → 0.3.1__tar.gz

{python_pq-0.2.3 → python_pq-0.3.1}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.3
 Name: python-pq
-Version: 0.2.3
+Version: 0.3.1
 Summary: Postgres-backed job queue for Python
 Author: ricwo
 Author-email: ricwo <r@cogram.com>
+Requires-Dist: alembic>=1.17.2
 Requires-Dist: click>=8.3.1
 Requires-Dist: croniter>=6.0.0
 Requires-Dist: dill>=0.4.0
@@ -45,7 +46,7 @@ Requires PostgreSQL and Python 3.13+.
 from pq import PQ
 
 pq = PQ("postgresql://localhost/mydb")
-pq.create_tables()
+pq.run_db_migrations()  # Creates/updates tables
 
 def send_email(to: str, subject: str) -> None:
     print(f"Sending to {to}: {subject}")

{python_pq-0.2.3 → python_pq-0.3.1}/README.md

@@ -25,7 +25,7 @@ Requires PostgreSQL and Python 3.13+.
 from pq import PQ
 
 pq = PQ("postgresql://localhost/mydb")
-pq.create_tables()
+pq.run_db_migrations()  # Creates/updates tables
 
 def send_email(to: str, subject: str) -> None:
     print(f"Sending to {to}: {subject}")

{python_pq-0.2.3 → python_pq-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-pq"
-version = "0.2.3"
+version = "0.3.1"
 description = "Postgres-backed job queue for Python"
 readme = "README.md"
 authors = [
@@ -8,6 +8,7 @@ authors = [
 ]
 requires-python = ">=3.13,<3.15"
 dependencies = [
+    "alembic>=1.17.2",
     "click>=8.3.1",
     "croniter>=6.0.0",
     "dill>=0.4.0",
@@ -38,8 +39,8 @@ module-name = "pq"
 dev = [
     "pre-commit>=4.5.1",
     "pytest>=9.0.2",
-    "ruff>=0.14.10",
-    "ty>=0.0.8",
+    "ruff>=0.14.11",
+    "ty>=0.0.10",
 ]
 
 [tool.pytest.ini_options]

{python_pq-0.2.3 → python_pq-0.3.1}/src/pq/client.py

@@ -1,5 +1,6 @@
 """PQ client - main interface for task queue."""
 
+import importlib.resources
 from collections.abc import Callable, Set
 from contextlib import contextmanager
 from datetime import UTC, datetime, timedelta
@@ -65,12 +66,41 @@ class PQ:
         """Exit context manager and close connections."""
         self.close()
 
+    def run_db_migrations(self) -> None:
+        """Run database migrations to latest version.
+
+        Call this once at application startup before using the queue.
+        Uses Alembic to apply any pending migrations. Safe to call
+        multiple times - only pending migrations are applied.
+
+        Example:
+            pq = PQ("postgresql://localhost/mydb")
+            pq.run_db_migrations()
+        """
+        # Lazy import to avoid fork issues on macOS
+        from alembic import command
+        from alembic.config import Config
+
+        # Get migrations directory from within the installed package
+        migrations_pkg = importlib.resources.files("pq.migrations")
+        migrations_dir = str(migrations_pkg)
+
+        alembic_cfg = Config()
+        alembic_cfg.set_main_option("script_location", migrations_dir)
+        alembic_cfg.set_main_option("sqlalchemy.url", str(self._engine.url))
+        command.upgrade(alembic_cfg, "head")
+
     def create_tables(self) -> None:
-        """Create all tables (for testing)."""
+        """Create all tables directly (for testing only).
+
+        For production, use run_db_migrations() instead. This method
+        bypasses Alembic and creates tables directly via SQLAlchemy,
+        which doesn't track schema versions.
+        """
         Base.metadata.create_all(self._engine)
 
     def drop_tables(self) -> None:
-        """Drop all tables (for testing)."""
+        """Drop all tables (for testing only)."""
         Base.metadata.drop_all(self._engine)
 
     def clear_all(self) -> None:
@@ -85,6 +115,7 @@ class PQ:
         *args: Any,
         run_at: datetime | None = None,
         priority: Priority = Priority.NORMAL,
+        client_id: str | None = None,
         **kwargs: Any,
     ) -> int:
         """Enqueue a one-off task.
@@ -94,6 +125,7 @@ class PQ:
             *args: Positional arguments to pass to the handler.
             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.
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
@@ -101,6 +133,7 @@ class PQ:
 
         Raises:
             ValueError: If task is a lambda, closure, or cannot be imported.
+            IntegrityError: If client_id already exists.
         """
         name = get_function_path(task)
         payload = serialize(args, kwargs)
@@ -108,7 +141,13 @@ class PQ:
         if run_at is None:
             run_at = datetime.now(UTC)
 
-        task_obj = Task(name=name, payload=payload, run_at=run_at, priority=priority)
+        task_obj = Task(
+            name=name,
+            payload=payload,
+            run_at=run_at,
+            priority=priority,
+            client_id=client_id,
+        )
 
         with self.session() as session:
             session.add(task_obj)
@@ -122,6 +161,7 @@ class PQ:
         run_every: timedelta | None = None,
         cron: str | croniter | None = None,
         priority: Priority = Priority.NORMAL,
+        client_id: str | None = None,
         **kwargs: Any,
     ) -> int:
         """Schedule a periodic task.
@@ -135,6 +175,7 @@ class PQ:
             run_every: Interval between executions (e.g., timedelta(hours=1)).
             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.
             **kwargs: Keyword arguments to pass to the handler.
 
         Returns:
@@ -144,6 +185,7 @@ class PQ:
             ValueError: If neither run_every nor cron is provided, or if both are.
             ValueError: If cron expression is invalid.
             ValueError: If task is a lambda, closure, or cannot be imported.
+            IntegrityError: If client_id already exists.
         """
         if run_every is None and cron is None:
             raise ValueError("Either run_every or cron must be provided")
@@ -185,6 +227,7 @@ class PQ:
                     run_every=run_every,
                     cron=cron_expr,
                     next_run=next_run,
+                    client_id=client_id,
                 )
                 .on_conflict_do_update(
                     index_elements=["name"],
@@ -261,6 +304,38 @@ class PQ:
                 session.expunge(task)
             return task
 
+    def get_task_by_client_id(self, client_id: str) -> Task | None:
+        """Get a task by client_id.
+
+        Args:
+            client_id: Client-provided identifier.
+
+        Returns:
+            Task object or None if not found.
+        """
+        with self.session() as session:
+            stmt = select(Task).where(Task.client_id == client_id)
+            task = session.execute(stmt).scalar_one_or_none()
+            if task:
+                session.expunge(task)
+            return task
+
+    def get_periodic_by_client_id(self, client_id: str) -> Periodic | None:
+        """Get a periodic task by client_id.
+
+        Args:
+            client_id: Client-provided identifier.
+
+        Returns:
+            Periodic object or None if not found.
+        """
+        with self.session() as session:
+            stmt = select(Periodic).where(Periodic.client_id == client_id)
+            periodic = session.execute(stmt).scalar_one_or_none()
+            if periodic:
+                session.expunge(periodic)
+            return periodic
+
     def list_failed(self, limit: int = 100) -> list[Task]:
         """List failed tasks.
 

python_pq-0.3.1/src/pq/migrations/README

@@ -0,0 +1 @@
+Generic single-database configuration.

python_pq-0.3.1/src/pq/migrations/__init__.py

@@ -0,0 +1 @@
+"""Alembic migrations for pq database schema."""

python_pq-0.3.1/src/pq/migrations/env.py

@@ -0,0 +1,85 @@
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+
+from alembic import context
+
+from pq.models import Base
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# pq models metadata for autogenerate support
+target_metadata = Base.metadata
+
+# Custom version table name to match pq_ naming convention
+VERSION_TABLE = "pq_schema_version"
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        version_table=VERSION_TABLE,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    # Support both ini file config and programmatic config
+    config_section = config.get_section(config.config_ini_section, {})
+    url = config.get_main_option("sqlalchemy.url")
+
+    if url and not config_section.get("sqlalchemy.url"):
+        # URL was set programmatically, add it to config section
+        config_section["sqlalchemy.url"] = url
+
+    connectable = engine_from_config(
+        config_section,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            version_table=VERSION_TABLE,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

python_pq-0.3.1/src/pq/migrations/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

python_pq-0.3.1/src/pq/migrations/versions/20260109T055839Z_476683af098d_initial_schema.py

@@ -0,0 +1,97 @@
+"""initial schema
+
+Revision ID: 476683af098d
+Revises:
+Create Date: 2026-01-09 05:58:39.589866 Z
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "476683af098d"
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "pq_periodic",
+        sa.Column("id", sa.BigInteger(), sa.Identity(always=False), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("payload", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.Column("priority", sa.SmallInteger(), nullable=False),
+        sa.Column("run_every", sa.Interval(), nullable=True),
+        sa.Column("cron", sa.String(length=100), nullable=True),
+        sa.Column("next_run", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("last_run", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("name"),
+    )
+    op.create_index(
+        "ix_pq_periodic_priority_next_run",
+        "pq_periodic",
+        ["priority", "next_run"],
+        unique=False,
+    )
+    op.create_table(
+        "pq_tasks",
+        sa.Column("id", sa.BigInteger(), sa.Identity(always=False), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("payload", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.Column("priority", sa.SmallInteger(), nullable=False),
+        sa.Column(
+            "status",
+            sa.Enum(
+                "PENDING",
+                "RUNNING",
+                "COMPLETED",
+                "FAILED",
+                name="task_status",
+                create_constraint=True,
+            ),
+            nullable=False,
+        ),
+        sa.Column("run_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("started_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.Column("attempts", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_pq_tasks_status_priority_run_at",
+        "pq_tasks",
+        ["status", "priority", "run_at"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index("ix_pq_tasks_status_priority_run_at", table_name="pq_tasks")
+    op.drop_table("pq_tasks")
+    op.drop_index("ix_pq_periodic_priority_next_run", table_name="pq_periodic")
+    op.drop_table("pq_periodic")
+    # ### end Alembic commands ###

python_pq-0.3.1/src/pq/migrations/versions/20260109T063747Z_2483bec70083_add_client_id.py

@@ -0,0 +1,54 @@
+"""add client_id
+
+Revision ID: 2483bec70083
+Revises: 476683af098d
+Create Date: 2026-01-09 06:37:47 Z
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "2483bec70083"
+down_revision: Union[str, Sequence[str], None] = "476683af098d"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add client_id column to pq_tasks and pq_periodic tables."""
+    # Add client_id column to pq_tasks
+    op.add_column(
+        "pq_tasks",
+        sa.Column("client_id", sa.String(length=255), nullable=True),
+    )
+    op.create_index(
+        "ix_pq_tasks_client_id",
+        "pq_tasks",
+        ["client_id"],
+        unique=True,
+    )
+
+    # Add client_id column to pq_periodic
+    op.add_column(
+        "pq_periodic",
+        sa.Column("client_id", sa.String(length=255), nullable=True),
+    )
+    op.create_index(
+        "ix_pq_periodic_client_id",
+        "pq_periodic",
+        ["client_id"],
+        unique=True,
+    )
+
+
+def downgrade() -> None:
+    """Remove client_id column from pq_tasks and pq_periodic tables."""
+    op.drop_index("ix_pq_periodic_client_id", table_name="pq_periodic")
+    op.drop_column("pq_periodic", "client_id")
+    op.drop_index("ix_pq_tasks_client_id", table_name="pq_tasks")
+    op.drop_column("pq_tasks", "client_id")

python_pq-0.3.1/src/pq/migrations/versions/__init__.py

@@ -0,0 +1 @@
+"""Migration versions."""

{python_pq-0.2.3 → python_pq-0.3.1}/src/pq/models.py

@@ -45,6 +45,9 @@ class Task(Base):
     )
 
     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)
     payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
     priority: Mapped[int] = mapped_column(SmallInteger, nullable=False, default=0)
@@ -76,6 +79,9 @@ class Periodic(Base):
     )
 
     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)
     payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
     priority: Mapped[int] = mapped_column(SmallInteger, nullable=False, default=0)