pg-task-tracker 0.1.0__tar.gz

pg_task_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: pg-task-tracker
+Version: 0.1.0
+Summary: Add your description here
+Keywords: 
+Author: craig stevenson
+Author-email: craig stevenson <craig.stevenson@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/craig-stevenson/pg-task-tracker
+Project-URL: Issues, https://github.com/craig-stevenson/pg-task-tracker/issues
+Project-URL: Repository, https://github.com/craig-stevenson/pg-task-tracker
+Description-Content-Type: text/markdown
+

pg_task_tracker-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "pg-task-tracker"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "craig stevenson", email = "craig.stevenson@gmail.com" }
+]
+requires-python = ">=3.12"
+license = "MIT"
+keywords = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "sqlmodel>=0.0.22",
+    "psycopg2-binary>=2.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/craig-stevenson/pg-task-tracker"
+Repository = "https://github.com/craig-stevenson/pg-task-tracker"
+Issues = "https://github.com/craig-stevenson/pg-task-tracker/issues"
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ty",
+    "pytest",
+]
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+unresolved-reference = "error"
+unresolved-import = "error"

pg_task_tracker-0.1.0/src/pg_task_tracker/__init__.py

@@ -0,0 +1,15 @@
+from pg_task_tracker._types import StepStatus, TaskStatus
+from pg_task_tracker.models import Task, TaskStep
+from pg_task_tracker.schema import ensure_schema, get_migration_sql
+from pg_task_tracker.tracker import TaskHandle, TaskTracker
+
+__all__ = [
+    "TaskTracker",
+    "TaskHandle",
+    "ensure_schema",
+    "get_migration_sql",
+    "Task",
+    "TaskStep",
+    "StepStatus",
+    "TaskStatus",
+]

pg_task_tracker-0.1.0/src/pg_task_tracker/_types.py

@@ -0,0 +1,4 @@
+from typing import Literal
+
+StepStatus = Literal["pending", "running", "completed", "failed"]
+TaskStatus = Literal["pending", "running", "completed", "failed"]

pg_task_tracker-0.1.0/src/pg_task_tracker/migrations/001_initial.sql

@@ -0,0 +1,35 @@
+-- pg_task_tracker: initial schema
+-- Apply with: psql -f 001_initial.sql your_database
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS st_task (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name        VARCHAR(255) NOT NULL,
+    status      VARCHAR(20)  NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending', 'running', 'completed', 'failed')),
+    created_at  TIMESTAMPTZ  NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ  NOT NULL DEFAULT now(),
+    metadata    JSONB
+);
+
+CREATE INDEX IF NOT EXISTS ix_st_task_name   ON st_task (name);
+CREATE INDEX IF NOT EXISTS ix_st_task_status ON st_task (status);
+
+CREATE TABLE IF NOT EXISTS st_task_step (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    task_id       UUID         NOT NULL REFERENCES st_task(id) ON DELETE CASCADE,
+    name          VARCHAR(255) NOT NULL,
+    status        VARCHAR(20)  NOT NULL DEFAULT 'pending'
+                  CHECK (status IN ('pending', 'running', 'completed', 'failed')),
+    step_order    INTEGER      NOT NULL,
+    created_at    TIMESTAMPTZ  NOT NULL DEFAULT now(),
+    started_at    TIMESTAMPTZ,
+    completed_at  TIMESTAMPTZ,
+    metadata      JSONB,
+    UNIQUE (task_id, name)
+);
+
+CREATE INDEX IF NOT EXISTS ix_st_task_step_task_id ON st_task_step (task_id);
+
+COMMIT;

pg_task_tracker-0.1.0/src/pg_task_tracker/models.py

@@ -0,0 +1,44 @@
+import uuid as _uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import Column, JSON, String, UniqueConstraint
+from sqlmodel import Field, Relationship, SQLModel
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class TaskStep(SQLModel, table=True):
+    __tablename__ = "st_task_step"
+    __table_args__ = (UniqueConstraint("task_id", "name"),)
+
+    id: _uuid.UUID = Field(default_factory=_uuid.uuid4, primary_key=True)
+    task_id: _uuid.UUID = Field(foreign_key="st_task.id", index=True)
+    name: str = Field(max_length=255)
+    status: str = Field(default="pending", sa_column=Column(String(20), nullable=False, server_default="pending"))
+    step_order: int
+    created_at: datetime = Field(default_factory=_utcnow)
+    started_at: datetime | None = Field(default=None)
+    completed_at: datetime | None = Field(default=None)
+    step_metadata: dict[str, Any] | None = Field(
+        default=None, sa_column=Column("metadata", JSON, nullable=True)
+    )
+
+    task: "Task" = Relationship(back_populates="steps")
+
+
+class Task(SQLModel, table=True):
+    __tablename__ = "st_task"
+
+    id: _uuid.UUID = Field(default_factory=_uuid.uuid4, primary_key=True)
+    name: str = Field(max_length=255, index=True)
+    status: str = Field(default="pending", sa_column=Column(String(20), nullable=False, server_default="pending"))
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    task_metadata: dict[str, Any] | None = Field(
+        default=None, sa_column=Column("metadata", JSON, nullable=True)
+    )
+
+    steps: list[TaskStep] = Relationship(back_populates="task")

pg_task_tracker-0.1.0/src/pg_task_tracker/schema.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import importlib.resources
+
+from sqlalchemy import Engine
+from sqlmodel import SQLModel
+
+from pg_task_tracker import models as _models  # noqa: F401 — ensure tables are registered
+
+
+def ensure_schema(engine: Engine) -> None:
+    """Create all tables if they don't already exist."""
+    SQLModel.metadata.create_all(engine)
+
+
+def get_migration_sql() -> str:
+    """Return the contents of the bundled SQL migration file."""
+    return (
+        importlib.resources.files("pg_task_tracker")
+        .joinpath("migrations/001_initial.sql")
+        .read_text(encoding="utf-8")
+    )

pg_task_tracker-0.1.0/src/pg_task_tracker/tracker.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import Engine, func
+from sqlmodel import Session, select
+
+from pg_task_tracker._types import StepStatus, TaskStatus
+from pg_task_tracker.models import Task, TaskStep, _utcnow
+
+
+class TaskHandle:
+    """Handle to a single task. Provides methods to add and update steps."""
+
+    def __init__(self, task_id: UUID, session: Session) -> None:
+        self._task_id = task_id
+        self._session = session
+
+    @property
+    def task_id(self) -> UUID:
+        return self._task_id
+
+    def add_step(
+        self,
+        name: str,
+        *,
+        status: StepStatus = "pending",
+        metadata: dict[str, Any] | None = None,
+    ) -> TaskStep:
+        """Append a new step to this task."""
+        current_max = self._session.exec(
+            select(func.max(TaskStep.step_order)).where(
+                TaskStep.task_id == self._task_id
+            )
+        ).one()
+        next_order = (current_max or 0) + 1
+
+        now = _utcnow()
+        step = TaskStep(
+            task_id=self._task_id,
+            name=name,
+            status=status,
+            step_order=next_order,
+            started_at=now if status == "running" else None,
+            step_metadata=metadata,
+        )
+        self._session.add(step)
+        self._session.commit()
+        self._session.refresh(step)
+        return step
+
+    def update_step(
+        self,
+        name: str,
+        *,
+        status: StepStatus | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> TaskStep:
+        """Update an existing step by name."""
+        step = self._session.exec(
+            select(TaskStep).where(
+                TaskStep.task_id == self._task_id,
+                TaskStep.name == name,
+            )
+        ).one()
+
+        if status is not None:
+            step.status = status
+            now = _utcnow()
+            if status == "running":
+                step.started_at = now
+            elif status in ("completed", "failed"):
+                step.completed_at = now
+
+        if metadata is not None:
+            step.step_metadata = metadata
+
+        self._session.commit()
+        self._session.refresh(step)
+        return step
+
+    def get_steps(self) -> list[TaskStep]:
+        """Return all steps for this task, ordered by step_order."""
+        return list(
+            self._session.exec(
+                select(TaskStep)
+                .where(TaskStep.task_id == self._task_id)
+                .order_by(TaskStep.step_order)  # ty: ignore[invalid-argument-type]
+            ).all()
+        )
+
+    def update_status(self, status: TaskStatus) -> None:
+        """Update the task's own status."""
+        task = self._session.get_one(Task, self._task_id)
+        task.status = status
+        task.updated_at = _utcnow()
+        self._session.commit()
+
+
+class TaskTracker:
+    """Entry point for tracking multi-step tasks in PostgreSQL."""
+
+    def __init__(self, engine: Engine) -> None:
+        self._engine = engine
+
+    def _get_session(self) -> Session:
+        return Session(self._engine)
+
+    def create_task(
+        self,
+        name: str,
+        *,
+        status: TaskStatus = "pending",
+        metadata: dict[str, Any] | None = None,
+    ) -> TaskHandle:
+        """Create a new task and return a handle to it."""
+        session = self._get_session()
+        task = Task(name=name, status=status, task_metadata=metadata)
+        session.add(task)
+        session.commit()
+        session.refresh(task)
+        return TaskHandle(task.id, session)
+
+    def get_task(self, task_id: UUID) -> TaskHandle:
+        """Resume working with an existing task by its UUID."""
+        session = self._get_session()
+        session.get_one(Task, task_id)
+        return TaskHandle(task_id, session)
+
+    def get_task_by_name(self, name: str) -> TaskHandle:
+        """Look up a task by name. Raises if not found or if multiple match."""
+        session = self._get_session()
+        task = session.exec(select(Task).where(Task.name == name)).one()
+        return TaskHandle(task.id, session)