shqaff 0.0.1__tar.gz

shqaff-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ice1x
+
+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.

shqaff-0.0.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: shqaff
+Version: 0.0.1
+Summary: A lightweight, PostgreSQL-backed task queue for Python
+Author: ilia iakhin
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: psycopg2-binary>=2.9
+Dynamic: license-file
+
+# shqaff
+
+## Overview
+
+shqaff is a minimal task queue built with Python and SQLAlchemy. It stores jobs in a PostgreSQL table and processes them with registered consumers.
+
+## Installation
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+2. Configure database settings with environment variables such as `SHAQAFF_DB_HOST` and `SHAQAFF_DB_NAME` or rely on defaults.
+
+## Usage
+
+1. Initialize the database and start the example process:
+   ```bash
+   python main.py
+   ```
+2. The demo task creates a payload and processes it through a consumer.
+
+## Testing
+
+Run the test suite:
+```bash
+pytest
+```

shqaff-0.0.1/README.md

@@ -0,0 +1,28 @@
+# shqaff
+
+## Overview
+
+shqaff is a minimal task queue built with Python and SQLAlchemy. It stores jobs in a PostgreSQL table and processes them with registered consumers.
+
+## Installation
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+2. Configure database settings with environment variables such as `SHAQAFF_DB_HOST` and `SHAQAFF_DB_NAME` or rely on defaults.
+
+## Usage
+
+1. Initialize the database and start the example process:
+   ```bash
+   python main.py
+   ```
+2. The demo task creates a payload and processes it through a consumer.
+
+## Testing
+
+Run the test suite:
+```bash
+pytest
+```

shqaff-0.0.1/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "shqaff"
+version = "0.0.1"
+description = "A lightweight, PostgreSQL-backed task queue for Python"
+authors = [
+    { name="ilia iakhin" }
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "SQLAlchemy>=2.0",
+    "psycopg2-binary>=2.9",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["shqaff*"]

shqaff-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shqaff-0.0.1/shqaff/config.py

@@ -0,0 +1,11 @@
+import os
+
+
+DB_HOST = os.getenv("SHAQAFF_DB_HOST", "localhost")
+DB_PORT = os.getenv("SHAQAFF_DB_PORT", "5432")
+DB_NAME = os.getenv("SHAQAFF_DB_NAME", "shqaff")
+DB_USER = os.getenv("SHAQAFF_DB_USER", "postgres")
+DB_PASS = os.getenv("SHAQAFF_DB_PASS", "")
+
+
+DATABASE_URL = f"postgresql://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}"

shqaff-0.0.1/shqaff/consumer.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+
+class Consumer(ABC):
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @abstractmethod
+    def run(self, payload: dict) -> None:
+        pass

shqaff-0.0.1/shqaff/db.py

@@ -0,0 +1,22 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, scoped_session
+
+from .config import DATABASE_URL
+from .models import Base
+
+
+engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+
+SessionLocal = scoped_session(sessionmaker(bind=engine))
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def init_db():
+    Base.metadata.create_all(bind=engine)

shqaff-0.0.1/shqaff/event_loop.py

@@ -0,0 +1,53 @@
+import time
+from datetime import datetime
+
+from shqaff.models import TaskQueue
+from shqaff.registry import consumer_registry
+from shqaff.task import Task
+from shqaff.status import TaskStatus
+
+
+def process_once(db, batch_size: int = 10):
+    tasks = (
+        db.query(TaskQueue)
+        .filter(TaskQueue.status == TaskStatus.PENDING.value)
+        .limit(batch_size)
+        .with_for_update(skip_locked=True)
+        .all()
+    )
+
+    for task_model in tasks:
+        consumer_cls = consumer_registry.get(task_model.consumer)
+        if not consumer_cls:
+            continue
+
+        task = Task(task_model)
+
+        try:
+            task.start()
+            task_model.last_attempt_at = datetime.utcnow()
+            db.commit()
+
+            consumer = consumer_cls()
+            consumer.run(task_model.payload)
+
+            task.succeed()
+
+        except Exception as e:
+            task_model.retries += 1
+            task_model.error = str(e)
+
+            if task_model.retries >= task_model.max_retries:
+                task.fail()
+            else:
+                task_model.status = TaskStatus.PENDING.value
+
+        finally:
+            task_model.updated_at = datetime.utcnow()
+            db.commit()
+
+
+def process_tasks(db, poll_interval: int = 5, batch_size: int = 10):
+    while True:
+        process_once(db, batch_size=batch_size)
+        time.sleep(poll_interval)

shqaff-0.0.1/shqaff/fsm.py

@@ -0,0 +1,24 @@
+from transitions import Machine
+
+from .status import TaskStatus
+
+
+class TaskStateMachine:
+
+    states = [status.value for status in TaskStatus]
+
+    def __init__(self, initial: TaskStatus | str = TaskStatus.PENDING):
+        self.state = initial.value if isinstance(initial, TaskStatus) else initial
+
+        self.machine = Machine(
+            model=self,
+            states=TaskStateMachine.states,
+            initial=self.state,
+        )
+
+        self.machine.add_transition("start", source=TaskStatus.PENDING.value, dest=TaskStatus.IN_PROGRESS.value)
+        self.machine.add_transition("succeed", source=TaskStatus.IN_PROGRESS.value, dest=TaskStatus.DONE.value)
+        self.machine.add_transition("fail", source=TaskStatus.IN_PROGRESS.value, dest=TaskStatus.FAILED.value)
+
+    def get_state(self) -> TaskStatus:
+        return TaskStatus(self.state)

shqaff-0.0.1/shqaff/models.py

@@ -0,0 +1,22 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, JSON, func
+
+from sqlalchemy.orm import declarative_base
+
+
+Base = declarative_base()
+
+
+class TaskQueue(Base):
+    __tablename__ = "task_queue"
+
+    id = Column(Integer, primary_key=True)
+    task_name = Column(String, nullable=False)
+    payload = Column(JSON, nullable=True)
+    consumer = Column(String, nullable=False)
+    status = Column(String, default="pending", nullable=False)
+    retries = Column(Integer, default=0, nullable=False)
+    max_retries = Column(Integer, default=3, nullable=False)
+    error = Column(Text, nullable=True)
+    created_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(DateTime, onupdate=func.now())
+    last_attempt_at = Column(DateTime)

shqaff-0.0.1/shqaff/producer.py

@@ -0,0 +1,17 @@
+from sqlalchemy.orm import Session
+from .models import TaskQueue
+from .status import TaskStatus
+
+
+def create_task(
+    db: Session, task_name: str, consumer: str, payload: dict, max_retries: int = 3
+) -> None:
+    task = TaskQueue(
+        task_name=task_name,
+        consumer=consumer,
+        payload=payload,
+        max_retries=max_retries,
+        status=TaskStatus.PENDING.value,
+    )
+    db.add(task)
+    db.commit()

shqaff-0.0.1/shqaff/registry.py

@@ -0,0 +1,9 @@
+from typing import Dict, Type
+from .consumer import Consumer
+
+
+consumer_registry: Dict[str, Type[Consumer]] = {}
+
+
+def register_consumer(consumer_cls: Type[Consumer]) -> None:
+    consumer_registry[consumer_cls().name] = consumer_cls

shqaff-0.0.1/shqaff/status.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    DONE = "done"
+    FAILED = "failed"

shqaff-0.0.1/shqaff/task.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+
+from shqaff.models import TaskQueue
+from shqaff.fsm import TaskStateMachine
+
+
+@dataclass
+class Task:
+    task: TaskQueue
+    fsm: TaskStateMachine = field(init=False)
+
+    def __post_init__(self):
+        self.fsm = TaskStateMachine(initial=self.task.status)
+
+    def start(self):
+        self.fsm.start()
+        self.task.status = self.fsm.get_state().value
+
+    def succeed(self):
+        self.fsm.succeed()
+        self.task.status = self.fsm.get_state().value
+
+    def fail(self):
+        self.fsm.fail()
+        self.task.status = self.fsm.get_state().value
+
+    @property
+    def model(self) -> TaskQueue:
+        return self.task

shqaff-0.0.1/shqaff/tests/conftest.py

@@ -0,0 +1,25 @@
+import pytest
+from shqaff.db import init_db, SessionLocal
+from shqaff.models import TaskQueue
+from shqaff.registry import consumer_registry
+
+
+@pytest.fixture(autouse=True)
+def clear_consumer_registry():
+    consumer_registry.clear()
+    yield
+    consumer_registry.clear()
+
+
+@pytest.fixture(scope="function")
+def db():
+    init_db()
+    session = SessionLocal()
+
+    # Clean the table before each test
+    session.query(TaskQueue).delete()
+    session.commit()
+
+    yield session
+
+    session.close()

shqaff-0.0.1/shqaff/tests/test_event_loop.py

@@ -0,0 +1,34 @@
+from shqaff.models import TaskQueue
+from shqaff.registry import register_consumer
+from shqaff.event_loop import process_once
+from shqaff.consumer import Consumer
+from shqaff.producer import create_task
+from shqaff.status import TaskStatus
+
+
+class DummyConsumer(Consumer):
+    name = "dummy"
+    processed = []
+
+    def run(self, payload: dict) -> None:
+        self.__class__.processed.append(payload)
+
+
+def test_event_loop_processes_task(db):
+    register_consumer(DummyConsumer)
+
+    create_task(
+        db=db,
+        task_name="some_task",
+        consumer="dummy",
+        payload={"hello": "world"},
+        max_retries=1,
+    )
+
+    process_once(db=db, batch_size=1)
+
+    task = db.query(TaskQueue).filter_by(consumer="dummy").first()
+    assert task.status == TaskStatus.DONE.value
+    assert task.error is None
+    assert task.retries == 0
+    assert DummyConsumer.processed[-1] == {"hello": "world"}

shqaff-0.0.1/shqaff/tests/test_fail_after_max_retries.py

@@ -0,0 +1,32 @@
+from shqaff.consumer import Consumer
+from shqaff.registry import register_consumer
+from shqaff.producer import create_task
+from shqaff.event_loop import process_once
+from shqaff.models import TaskQueue
+from shqaff.status import TaskStatus
+
+
+class AlwaysFailingConsumer(Consumer):
+    name = "always_fail"
+
+    def run(self, payload: dict) -> None:
+        raise RuntimeError("crash")
+
+
+def test_task_fails_permanently_after_max_retries(db):
+    register_consumer(AlwaysFailingConsumer)
+
+    create_task(
+        db=db,
+        task_name="fail_task",
+        consumer="always_fail",
+        payload={},
+        max_retries=1,
+    )
+
+    process_once(db)
+
+    task = db.query(TaskQueue).first()
+    assert task.status == TaskStatus.FAILED.value
+    assert task.retries == 1
+    assert "crash" in task.error

shqaff-0.0.1/shqaff/tests/test_invalid_fsm_transition.py

@@ -0,0 +1,11 @@
+import pytest
+from shqaff.fsm import TaskStateMachine
+from transitions.core import MachineError
+from shqaff.status import TaskStatus
+
+
+def test_invalid_fsm_transition_raises():
+    fsm = TaskStateMachine(initial=TaskStatus.DONE)
+
+    with pytest.raises(MachineError):
+        fsm.start()

shqaff-0.0.1/shqaff/tests/test_retry_logic.py

@@ -0,0 +1,36 @@
+from shqaff.consumer import Consumer
+from shqaff.registry import register_consumer
+from shqaff.producer import create_task
+from shqaff.event_loop import process_once
+from shqaff.models import TaskQueue
+from shqaff.status import TaskStatus
+
+
+class FailingOnceConsumer(Consumer):
+    name = "fail_once"
+    call_count = 0
+
+    def run(self, payload: dict) -> None:
+        self.__class__.call_count += 1
+        if self.__class__.call_count == 1:
+            raise Exception("fail once")
+
+
+def test_retry_logic(db):
+    FailingOnceConsumer.call_count = 0
+    register_consumer(FailingOnceConsumer)
+
+    create_task(
+        db=db,
+        task_name="retry_task",
+        consumer="fail_once",
+        payload={},
+        max_retries=2,
+    )
+
+    process_once(db=db, batch_size=1)
+
+    task = db.query(TaskQueue).filter_by(consumer="fail_once").first()
+    assert task.status == TaskStatus.PENDING.value
+    assert task.retries == 1
+    assert "fail once" in task.error

shqaff-0.0.1/shqaff/tests/test_smoke.py

@@ -0,0 +1,24 @@
+from shqaff.models import TaskQueue
+from shqaff.producer import create_task
+from shqaff.status import TaskStatus
+
+
+def test_create_task(db):
+    create_task(
+        db=db,
+        task_name="test_task",
+        consumer="test_consumer",
+        payload={"foo": "bar"},
+        max_retries=2,
+    )
+
+    task = (
+        db.query(TaskQueue)
+        .filter_by(task_name="test_task", consumer="test_consumer")
+        .first()
+    )
+
+    assert task is not None
+    assert task.payload["foo"] == "bar"
+    assert task.status == TaskStatus.PENDING.value
+    assert task.max_retries == 2

shqaff-0.0.1/shqaff/tests/test_task_fsm.py

@@ -0,0 +1,27 @@
+from shqaff.models import TaskQueue
+from shqaff.task import Task
+from shqaff.status import TaskStatus
+
+
+def test_fsm_transitions():
+    task_model = TaskQueue(status=TaskStatus.PENDING.value)
+    task = Task(task_model)
+
+    assert task_model.status == TaskStatus.PENDING.value
+
+    task.start()
+    assert task_model.status == TaskStatus.IN_PROGRESS.value
+
+    task.succeed()
+    assert task_model.status == TaskStatus.DONE.value
+
+
+def test_fsm_failure_transition():
+    task_model = TaskQueue(status=TaskStatus.PENDING.value)
+    task = Task(task_model)
+
+    task.start()
+    assert task_model.status == TaskStatus.IN_PROGRESS.value
+
+    task.fail()
+    assert task_model.status == TaskStatus.FAILED.value

shqaff-0.0.1/shqaff.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: shqaff
+Version: 0.0.1
+Summary: A lightweight, PostgreSQL-backed task queue for Python
+Author: ilia iakhin
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: psycopg2-binary>=2.9
+Dynamic: license-file
+
+# shqaff
+
+## Overview
+
+shqaff is a minimal task queue built with Python and SQLAlchemy. It stores jobs in a PostgreSQL table and processes them with registered consumers.
+
+## Installation
+
+1. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+2. Configure database settings with environment variables such as `SHAQAFF_DB_HOST` and `SHAQAFF_DB_NAME` or rely on defaults.
+
+## Usage
+
+1. Initialize the database and start the example process:
+   ```bash
+   python main.py
+   ```
+2. The demo task creates a payload and processes it through a consumer.
+
+## Testing
+
+Run the test suite:
+```bash
+pytest
+```

shqaff-0.0.1/shqaff.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+LICENSE
+README.md
+pyproject.toml
+shqaff/__init__.py
+shqaff/config.py
+shqaff/consumer.py
+shqaff/db.py
+shqaff/event_loop.py
+shqaff/fsm.py
+shqaff/models.py
+shqaff/producer.py
+shqaff/registry.py
+shqaff/status.py
+shqaff/task.py
+shqaff.egg-info/PKG-INFO
+shqaff.egg-info/SOURCES.txt
+shqaff.egg-info/dependency_links.txt
+shqaff.egg-info/requires.txt
+shqaff.egg-info/top_level.txt
+shqaff/tests/__init__.py
+shqaff/tests/conftest.py
+shqaff/tests/test_event_loop.py
+shqaff/tests/test_fail_after_max_retries.py
+shqaff/tests/test_invalid_fsm_transition.py
+shqaff/tests/test_retry_logic.py
+shqaff/tests/test_smoke.py
+shqaff/tests/test_task_fsm.py

shqaff-0.0.1/shqaff.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shqaff-0.0.1/shqaff.egg-info/requires.txt

@@ -0,0 +1,2 @@
+SQLAlchemy>=2.0
+psycopg2-binary>=2.9

shqaff-0.0.1/shqaff.egg-info/top_level.txt

@@ -0,0 +1 @@
+shqaff