pgwerk 0.1.0__tar.gz

pgwerk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/ci.yml"
+      - "pgwerk/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "LICENSE"
+  pull_request:
+    branches: [main]
+    paths:
+      - ".github/workflows/ci.yml"
+      - "pgwerk/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "LICENSE"
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} / Postgres ${{ matrix.postgres-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+        postgres-version: ["16"]
+
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres-version }}
+        env:
+          POSTGRES_USER: pgwerk
+          POSTGRES_PASSWORD: pgwerk
+          POSTGRES_DB: pgwerk_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Unit tests
+        run: uv run pytest tests/unit/ -v --tb=short
+
+      - name: Integration tests
+        env:
+          PGWERK_TEST_DSN: postgresql://pgwerk:pgwerk@localhost/pgwerk_test
+        run: uv run pytest tests/integration/ -v --tb=short

pgwerk-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - "CHANGELOG.md"
+      - "docs/assets/**"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Deploy
+        run: uv run mkdocs gh-deploy --force

pgwerk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ── Build dashboard ──────────────────────────────────────────────────
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: pnpm
+          cache-dependency-path: dashboard/pnpm-lock.yaml
+
+      - name: Install dashboard dependencies
+        run: pnpm install --frozen-lockfile
+        working-directory: dashboard
+
+      - name: Build dashboard
+        run: pnpm build
+        working-directory: dashboard
+        # outputs to pgwerk/api/static/ via vite.config.ts outDir
+
+      # ── Build and publish Python wheel ───────────────────────────────────
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}

pgwerk-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+.refs
+.claude
+.local
+.internals
+.env
+.envrc
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.log
+.coverage
+.coverage.*
+htmlcov/
+.coverage
+.vscode/
+.pytest_cache/
+node_modules/
+dashboard/dist/
+*.tsbuildinfo
+dashboard/package-lock.json
+pgwerk/api/static/*
+!pgwerk/api/static/.gitkeep
+site/
+.DS_Store

pgwerk-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-22
+
+### Added
+
+- `Werk` app class — connect/disconnect, enqueue, enqueue_many, get_job, get_executions, cancel_job, sweep
+- `AsyncWorker`, `ThreadWorker`, `ProcessWorker`, `ForkWorker` — four concurrency models
+- `LISTEN/NOTIFY` wake-up so workers react instantly to new jobs
+- `SELECT … FOR UPDATE SKIP LOCKED` dequeue with Priority, RoundRobin, and Random strategies
+- `Retry` — configurable max attempts and per-interval back-off delays
+- `Repeat` — re-enqueue a job N more times after each successful run
+- `Dependency` / DAG — jobs that wait for one or more upstream jobs to complete
+- Idempotency keys (`_key`) — duplicate enqueues silently dropped
+- Group keys (`_group`) — at most one active job per group at a time
+- `_heartbeat` — worker auto-renews long-running jobs to prevent sweep reaping
+- `CronScheduler` + `CronJob` — cron-expression and interval-based recurring jobs, with Postgres advisory lock so only one scheduler runs at a time
+- `JSONSerializer` (default) and `PickleSerializer`
+- Auto-migration on `connect()` with advisory lock to prevent races
+- `before_process` / `after_process` hooks on workers
+- `on_success` / `on_failure` / `on_stopped` callbacks per job
+- `failure_mode=delete` — terminal failures remove the row instead of marking it failed
+- `result_ttl` / `failure_ttl` — automatic expiry of completed / failed rows
+- `burst` mode — worker exits once the queue drains
+- `BaseWorker.push_exception_handler` / `pop_exception_handler` stack
+- `werk` CLI — `worker`, `info`, `purge` sub-commands
+- REST API (optional `litestar` extra) — job inspection and queue stats
+- Prometheus metrics exporter (optional `prometheus-client` extra)
+- `werk info` dashboard using `rich` + `plotext` (optional `analytics` extra)

pgwerk-0.1.0/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+**wrk** is a Postgres-backed job queue library. It auto-migrates a shared schema on first connect using advisory locks to prevent races.
+
+## Commands
+
+### Python
+
+```bash
+# Install (dev)
+uv sync --extra dev
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/unit/test_job.py
+
+# Run integration tests (requires Postgres — see below)
+PGWERK_TEST_DSN="postgresql://pgwerk:pgwerk@localhost/pgwerk_test" uv run pytest tests/integration/
+
+# Lint
+uv run ruff check .
+uv run ruff format .
+```
+
+
+## Integration test database
+
+Integration tests expect a Postgres instance at `postgresql://pgwerk:pgwerk@localhost/pgwerk_test` (override with `PGWERK_TEST_DSN`). Tables are auto-created by `Werk.connect()` / `app.connect()` and truncated between tests via the `app` fixture in `tests/integration/conftest.py`.
+
+## Architecture
+
+### Schema (both implementations)
+
+Four tables, prefixed (default `_pgwerk_`), optionally schema-qualified:
+
+| Table | Purpose |
+|---|---|
+| `_pgwerk_worker` | Registered worker instances + heartbeat |
+| `_pgwerk_jobs` | The job queue — all state lives here |
+| `_pgwerk_worker_jobs` | Claim tracking (worker ↔ job) |
+| `_pgwerk_jobs_executions` | Per-attempt execution history |
+| `_pgwerk_job_deps` | Job dependency graph (Python only) |
+
+Dequeue uses `SELECT … FOR UPDATE SKIP LOCKED` inside a transaction for safe concurrent polling. Workers also use `LISTEN/NOTIFY` for instant wake-up on enqueue.
+
+### Python worker hierarchy
+
+`BaseWorker` (polling loop, dequeue, ack/nack) is subclassed by:
+- `AsyncWorker` — asyncio, runs handlers as coroutines
+- `ThreadWorker` — runs handlers in a thread pool
+- `ProcessWorker` — runs handlers in a process pool
+- `ForkWorker` — forks per job
+
+### Python-only features vs Go
+
+The Python implementation adds: `Retry` (exponential back-off intervals), `Repeat` (recurring jobs), `Callback` (on_success/on_failure hooks), `Dependency` (DAG dependencies), `CronScheduler`, pluggable `Serializer` (JSON/Pickle), `heartbeat_secs` for long-running jobs, and a `CLI` (`werk` command via Click).
+
+The Go implementation is a leaner subset: enqueue, get, cancel, and a single goroutine-based `Worker`.
+
+### Configuration
+
+Both use an options/builder pattern. Python: `Werk(dsn, prefix=..., schema=..., serializer=...)`. Go: `New(dsn, WithSchema(...), WithPrefix(...), WithPoolSize(...))`. Table names are constructed at init time and stored — never interpolated at query time except through the pre-built identifiers.

pgwerk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Thanks for taking the time. Here's how to get up and running and what to expect when you open a PR.
+
+## Setup
+
+You need Python 3.11+ and a Postgres instance for integration tests.
+
+```bash
+# Clone
+git clone https://github.com/pgwerk/pgwerk
+cd pgwerk
+
+# Install with dev extras
+uv sync --extra dev
+
+# Start Postgres (Docker example)
+docker run -d \
+  --name pgwerk-postgres \
+  -e POSTGRES_USER=pgwerk \
+  -e POSTGRES_PASSWORD=pgwerk \
+  -e POSTGRES_DB=pgwerk_test \
+  -p 5432:5432 \
+  postgres:16
+```
+
+## Running tests
+
+```bash
+# Unit tests (no Postgres needed)
+uv run pytest tests/unit/
+
+# Integration tests
+PGWERK_TEST_DSN="postgresql://pgwerk:pgwerk@localhost/pgwerk_test" uv run pytest tests/integration/
+
+# All tests
+PGWERK_TEST_DSN="postgresql://pgwerk:pgwerk@localhost/pgwerk_test" uv run pytest
+
+# Single file
+uv run pytest tests/unit/test_job.py -v
+```
+
+## Linting
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+CI runs both on every push and pull request.
+
+## Opening a PR
+
+- Keep PRs focused — one concern per PR makes review faster.
+- Add or update tests for any changed behaviour.
+- Integration tests live in `tests/integration/`; unit tests in `tests/unit/`.
+- Update `CHANGELOG.md` under `[Unreleased]` with a brief description of your change.
+- CI must pass before merge.
+
+## Project structure
+
+```
+pgwerk/              source package
+  app.py          Werk app (connect, enqueue, inspect)
+  worker/         BaseWorker + AsyncWorker / ThreadWorker / ProcessWorker / ForkWorker
+  repos.py        Database repository layer (all SQL lives here)
+  database.py     Migration runner
+  schemas.py      Pydantic / dataclass models
+  cron.py         CronScheduler + CronJob
+  cli/            Click CLI (wrk worker / info / purge)
+  api/            Optional Litestar REST API
+  exporter/       Optional Prometheus metrics
+tests/
+  unit/           Pure-Python unit tests, no DB required
+  integration/    Full-stack tests against a live Postgres instance
+```
+
+## Reporting bugs
+
+Open an issue with:
+1. What you expected to happen.
+2. What actually happened (include logs where relevant).
+3. A minimal reproduction — ideally a single `pytest` test or a short script.

pgwerk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Caio Cavalcanti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pgwerk-0.1.0/Makefile

@@ -0,0 +1,59 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help setup lint format test test-unit test-integration docs docs-build docs-deploy dashboard clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# ── Setup ─────────────────────────────────────────────────────────────────────
+
+setup: ## Install all dependencies and set up the dev environment
+	uv sync --extra dev
+	pnpm install --dir dashboard
+	@echo ""
+	@echo "Done. To run integration tests, export PGWERK_TEST_DSN:"
+	@echo "  export PGWERK_TEST_DSN=postgresql://werk:wrk@localhost/wrk_test"
+
+# ── Code quality ──────────────────────────────────────────────────────────────
+
+lint: ## Run the linter
+	uv run ruff check .
+
+format: ## Format code
+	uv run ruff format .
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+test: ## Run all tests (requires PGWERK_TEST_DSN for integration)
+	uv run pytest
+
+test-unit: ## Run unit tests only
+	uv run pytest tests/unit/
+
+test-integration: ## Run integration tests (requires PGWERK_TEST_DSN)
+	uv run pytest tests/integration/
+
+# ── Dashboard ─────────────────────────────────────────────────────────────────
+
+dashboard: ## Run dashboard dev server (proxies API at localhost:8000)
+	pnpm --dir dashboard dev
+
+# ── Docs ──────────────────────────────────────────────────────────────────────
+
+docs: ## Serve docs locally at http://127.0.0.1:8000
+	uv run mkdocs serve
+
+docs-build: ## Build docs to site/
+	uv run mkdocs build
+
+docs-deploy: ## Deploy docs to GitHub Pages
+	uv run mkdocs gh-deploy --force
+
+# ── Housekeeping ──────────────────────────────────────────────────────────────
+
+clean: ## Remove caches and build artifacts
+	find . -type d -name __pycache__ -exec rm -r {} + 2>/dev/null; true
+	find . -type d -name .pytest_cache -exec rm -r {} + 2>/dev/null; true
+	find . -type d -name .mypy_cache  -exec rm -r {} + 2>/dev/null; true
+	find . -name "*.pyc" -delete
+	find . -name ".coverage" -delete